You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

17867 lines
476KB

  1. @chapter Filtering Introduction
  2. @c man begin FILTERING INTRODUCTION
  3. Filtering in FFmpeg is enabled through the libavfilter library.
  4. In libavfilter, a filter can have multiple inputs and multiple
  5. outputs.
  6. To illustrate the sorts of things that are possible, we consider the
  7. following filtergraph.
  8. @verbatim
  9. [main]
  10. input --> split ---------------------> overlay --> output
  11. | ^
  12. |[tmp] [flip]|
  13. +-----> crop --> vflip -------+
  14. @end verbatim
  15. This filtergraph splits the input stream in two streams, then sends one
  16. stream through the crop filter and the vflip filter, before merging it
  17. back with the other stream by overlaying it on top. You can use the
  18. following command to achieve this:
  19. @example
  20. ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
  21. @end example
  22. The result will be that the top half of the video is mirrored
  23. onto the bottom half of the output video.
  24. Filters in the same linear chain are separated by commas, and distinct
  25. linear chains of filters are separated by semicolons. In our example,
  26. @var{crop,vflip} are in one linear chain, @var{split} and
  27. @var{overlay} are separately in another. The points where the linear
  28. chains join are labelled by names enclosed in square brackets. In the
  29. example, the split filter generates two outputs that are associated to
  30. the labels @var{[main]} and @var{[tmp]}.
  31. The stream sent to the second output of @var{split}, labelled as
  32. @var{[tmp]}, is processed through the @var{crop} filter, which crops
  33. away the lower half part of the video, and then vertically flipped. The
  34. @var{overlay} filter takes in input the first unchanged output of the
  35. split filter (which was labelled as @var{[main]}), and overlay on its
  36. lower half the output generated by the @var{crop,vflip} filterchain.
  37. Some filters take in input a list of parameters: they are specified
  38. after the filter name and an equal sign, and are separated from each other
  39. by a colon.
  40. There exist so-called @var{source filters} that do not have an
  41. audio/video input, and @var{sink filters} that will not have audio/video
  42. output.
  43. @c man end FILTERING INTRODUCTION
  44. @chapter graph2dot
  45. @c man begin GRAPH2DOT
  46. The @file{graph2dot} program included in the FFmpeg @file{tools}
  47. directory can be used to parse a filtergraph description and issue a
  48. corresponding textual representation in the dot language.
  49. Invoke the command:
  50. @example
  51. graph2dot -h
  52. @end example
  53. to see how to use @file{graph2dot}.
  54. You can then pass the dot description to the @file{dot} program (from
  55. the graphviz suite of programs) and obtain a graphical representation
  56. of the filtergraph.
  57. For example the sequence of commands:
  58. @example
  59. echo @var{GRAPH_DESCRIPTION} | \
  60. tools/graph2dot -o graph.tmp && \
  61. dot -Tpng graph.tmp -o graph.png && \
  62. display graph.png
  63. @end example
  64. can be used to create and display an image representing the graph
  65. described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
  66. a complete self-contained graph, with its inputs and outputs explicitly defined.
  67. For example if your command line is of the form:
  68. @example
  69. ffmpeg -i infile -vf scale=640:360 outfile
  70. @end example
  71. your @var{GRAPH_DESCRIPTION} string will need to be of the form:
  72. @example
  73. nullsrc,scale=640:360,nullsink
  74. @end example
  75. you may also need to set the @var{nullsrc} parameters and add a @var{format}
  76. filter in order to simulate a specific input file.
  77. @c man end GRAPH2DOT
  78. @chapter Filtergraph description
  79. @c man begin FILTERGRAPH DESCRIPTION
  80. A filtergraph is a directed graph of connected filters. It can contain
  81. cycles, and there can be multiple links between a pair of
  82. filters. Each link has one input pad on one side connecting it to one
  83. filter from which it takes its input, and one output pad on the other
  84. side connecting it to one filter accepting its output.
  85. Each filter in a filtergraph is an instance of a filter class
  86. registered in the application, which defines the features and the
  87. number of input and output pads of the filter.
  88. A filter with no input pads is called a "source", and a filter with no
  89. output pads is called a "sink".
  90. @anchor{Filtergraph syntax}
  91. @section Filtergraph syntax
  92. A filtergraph has a textual representation, which is recognized by the
  93. @option{-filter}/@option{-vf}/@option{-af} and
  94. @option{-filter_complex} options in @command{ffmpeg} and
  95. @option{-vf}/@option{-af} in @command{ffplay}, and by the
  96. @code{avfilter_graph_parse_ptr()} function defined in
  97. @file{libavfilter/avfilter.h}.
  98. A filterchain consists of a sequence of connected filters, each one
  99. connected to the previous one in the sequence. A filterchain is
  100. represented by a list of ","-separated filter descriptions.
  101. A filtergraph consists of a sequence of filterchains. A sequence of
  102. filterchains is represented by a list of ";"-separated filterchain
  103. descriptions.
  104. A filter is represented by a string of the form:
  105. [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
  106. @var{filter_name} is the name of the filter class of which the
  107. described filter is an instance of, and has to be the name of one of
  108. the filter classes registered in the program.
  109. The name of the filter class is optionally followed by a string
  110. "=@var{arguments}".
  111. @var{arguments} is a string which contains the parameters used to
  112. initialize the filter instance. It may have one of two forms:
  113. @itemize
  114. @item
  115. A ':'-separated list of @var{key=value} pairs.
  116. @item
  117. A ':'-separated list of @var{value}. In this case, the keys are assumed to be
  118. the option names in the order they are declared. E.g. the @code{fade} filter
  119. declares three options in this order -- @option{type}, @option{start_frame} and
  120. @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
  121. @var{in} is assigned to the option @option{type}, @var{0} to
  122. @option{start_frame} and @var{30} to @option{nb_frames}.
  123. @item
  124. A ':'-separated list of mixed direct @var{value} and long @var{key=value}
  125. pairs. The direct @var{value} must precede the @var{key=value} pairs, and
  126. follow the same constraints order of the previous point. The following
  127. @var{key=value} pairs can be set in any preferred order.
  128. @end itemize
  129. If the option value itself is a list of items (e.g. the @code{format} filter
  130. takes a list of pixel formats), the items in the list are usually separated by
  131. @samp{|}.
  132. The list of arguments can be quoted using the character @samp{'} as initial
  133. and ending mark, and the character @samp{\} for escaping the characters
  134. within the quoted text; otherwise the argument string is considered
  135. terminated when the next special character (belonging to the set
  136. @samp{[]=;,}) is encountered.
  137. The name and arguments of the filter are optionally preceded and
  138. followed by a list of link labels.
  139. A link label allows one to name a link and associate it to a filter output
  140. or input pad. The preceding labels @var{in_link_1}
  141. ... @var{in_link_N}, are associated to the filter input pads,
  142. the following labels @var{out_link_1} ... @var{out_link_M}, are
  143. associated to the output pads.
  144. When two link labels with the same name are found in the
  145. filtergraph, a link between the corresponding input and output pad is
  146. created.
  147. If an output pad is not labelled, it is linked by default to the first
  148. unlabelled input pad of the next filter in the filterchain.
  149. For example in the filterchain
  150. @example
  151. nullsrc, split[L1], [L2]overlay, nullsink
  152. @end example
  153. the split filter instance has two output pads, and the overlay filter
  154. instance two input pads. The first output pad of split is labelled
  155. "L1", the first input pad of overlay is labelled "L2", and the second
  156. output pad of split is linked to the second input pad of overlay,
  157. which are both unlabelled.
  158. In a filter description, if the input label of the first filter is not
  159. specified, "in" is assumed; if the output label of the last filter is not
  160. specified, "out" is assumed.
  161. In a complete filterchain all the unlabelled filter input and output
  162. pads must be connected. A filtergraph is considered valid if all the
  163. filter input and output pads of all the filterchains are connected.
  164. Libavfilter will automatically insert @ref{scale} filters where format
  165. conversion is required. It is possible to specify swscale flags
  166. for those automatically inserted scalers by prepending
  167. @code{sws_flags=@var{flags};}
  168. to the filtergraph description.
  169. Here is a BNF description of the filtergraph syntax:
  170. @example
  171. @var{NAME} ::= sequence of alphanumeric characters and '_'
  172. @var{LINKLABEL} ::= "[" @var{NAME} "]"
  173. @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
  174. @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
  175. @var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
  176. @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
  177. @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
  178. @end example
  179. @section Notes on filtergraph escaping
  180. Filtergraph description composition entails several levels of
  181. escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
  182. section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
  183. information about the employed escaping procedure.
  184. A first level escaping affects the content of each filter option
  185. value, which may contain the special character @code{:} used to
  186. separate values, or one of the escaping characters @code{\'}.
  187. A second level escaping affects the whole filter description, which
  188. may contain the escaping characters @code{\'} or the special
  189. characters @code{[],;} used by the filtergraph description.
  190. Finally, when you specify a filtergraph on a shell commandline, you
  191. need to perform a third level escaping for the shell special
  192. characters contained within it.
  193. For example, consider the following string to be embedded in
  194. the @ref{drawtext} filter description @option{text} value:
  195. @example
  196. this is a 'string': may contain one, or more, special characters
  197. @end example
  198. This string contains the @code{'} special escaping character, and the
  199. @code{:} special character, so it needs to be escaped in this way:
  200. @example
  201. text=this is a \'string\'\: may contain one, or more, special characters
  202. @end example
  203. A second level of escaping is required when embedding the filter
  204. description in a filtergraph description, in order to escape all the
  205. filtergraph special characters. Thus the example above becomes:
  206. @example
  207. drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
  208. @end example
  209. (note that in addition to the @code{\'} escaping special characters,
  210. also @code{,} needs to be escaped).
  211. Finally an additional level of escaping is needed when writing the
  212. filtergraph description in a shell command, which depends on the
  213. escaping rules of the adopted shell. For example, assuming that
  214. @code{\} is special and needs to be escaped with another @code{\}, the
  215. previous string will finally result in:
  216. @example
  217. -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
  218. @end example
  219. @chapter Timeline editing
  220. Some filters support a generic @option{enable} option. For the filters
  221. supporting timeline editing, this option can be set to an expression which is
  222. evaluated before sending a frame to the filter. If the evaluation is non-zero,
  223. the filter will be enabled, otherwise the frame will be sent unchanged to the
  224. next filter in the filtergraph.
  225. The expression accepts the following values:
  226. @table @samp
  227. @item t
  228. timestamp expressed in seconds, NAN if the input timestamp is unknown
  229. @item n
  230. sequential number of the input frame, starting from 0
  231. @item pos
  232. the position in the file of the input frame, NAN if unknown
  233. @item w
  234. @item h
  235. width and height of the input frame if video
  236. @end table
  237. Additionally, these filters support an @option{enable} command that can be used
  238. to re-define the expression.
  239. Like any other filtering option, the @option{enable} option follows the same
  240. rules.
  241. For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
  242. minutes, and a @ref{curves} filter starting at 3 seconds:
  243. @example
  244. smartblur = enable='between(t,10,3*60)',
  245. curves = enable='gte(t,3)' : preset=cross_process
  246. @end example
  247. @c man end FILTERGRAPH DESCRIPTION
  248. @chapter Audio Filters
  249. @c man begin AUDIO FILTERS
  250. When you configure your FFmpeg build, you can disable any of the
  251. existing filters using @code{--disable-filters}.
  252. The configure output will show the audio filters included in your
  253. build.
  254. Below is a description of the currently available audio filters.
  255. @section acompressor
  256. A compressor is mainly used to reduce the dynamic range of a signal.
  257. Especially modern music is mostly compressed at a high ratio to
  258. improve the overall loudness. It's done to get the highest attention
  259. of a listener, "fatten" the sound and bring more "power" to the track.
  260. If a signal is compressed too much it may sound dull or "dead"
  261. afterwards or it may start to "pump" (which could be a powerful effect
  262. but can also destroy a track completely).
  263. The right compression is the key to reach a professional sound and is
  264. the high art of mixing and mastering. Because of its complex settings
  265. it may take a long time to get the right feeling for this kind of effect.
  266. Compression is done by detecting the volume above a chosen level
  267. @code{threshold} and dividing it by the factor set with @code{ratio}.
  268. So if you set the threshold to -12dB and your signal reaches -6dB a ratio
  269. of 2:1 will result in a signal at -9dB. Because an exact manipulation of
  270. the signal would cause distortion of the waveform the reduction can be
  271. levelled over the time. This is done by setting "Attack" and "Release".
  272. @code{attack} determines how long the signal has to rise above the threshold
  273. before any reduction will occur and @code{release} sets the time the signal
  274. has to fall below the threshold to reduce the reduction again. Shorter signals
  275. than the chosen attack time will be left untouched.
  276. The overall reduction of the signal can be made up afterwards with the
  277. @code{makeup} setting. So compressing the peaks of a signal about 6dB and
  278. raising the makeup to this level results in a signal twice as loud than the
  279. source. To gain a softer entry in the compression the @code{knee} flattens the
  280. hard edge at the threshold in the range of the chosen decibels.
  281. The filter accepts the following options:
  282. @table @option
  283. @item level_in
  284. Set input gain. Default is 1. Range is between 0.015625 and 64.
  285. @item threshold
  286. If a signal of second stream rises above this level it will affect the gain
  287. reduction of the first stream.
  288. By default it is 0.125. Range is between 0.00097563 and 1.
  289. @item ratio
  290. Set a ratio by which the signal is reduced. 1:2 means that if the level
  291. rose 4dB above the threshold, it will be only 2dB above after the reduction.
  292. Default is 2. Range is between 1 and 20.
  293. @item attack
  294. Amount of milliseconds the signal has to rise above the threshold before gain
  295. reduction starts. Default is 20. Range is between 0.01 and 2000.
  296. @item release
  297. Amount of milliseconds the signal has to fall below the threshold before
  298. reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
  299. @item makeup
  300. Set the amount by how much signal will be amplified after processing.
  301. Default is 2. Range is from 1 and 64.
  302. @item knee
  303. Curve the sharp knee around the threshold to enter gain reduction more softly.
  304. Default is 2.82843. Range is between 1 and 8.
  305. @item link
  306. Choose if the @code{average} level between all channels of input stream
  307. or the louder(@code{maximum}) channel of input stream affects the
  308. reduction. Default is @code{average}.
  309. @item detection
  310. Should the exact signal be taken in case of @code{peak} or an RMS one in case
  311. of @code{rms}. Default is @code{rms} which is mostly smoother.
  312. @item mix
  313. How much to use compressed signal in output. Default is 1.
  314. Range is between 0 and 1.
  315. @end table
  316. @section acrossfade
  317. Apply cross fade from one input audio stream to another input audio stream.
  318. The cross fade is applied for specified duration near the end of first stream.
  319. The filter accepts the following options:
  320. @table @option
  321. @item nb_samples, ns
  322. Specify the number of samples for which the cross fade effect has to last.
  323. At the end of the cross fade effect the first input audio will be completely
  324. silent. Default is 44100.
  325. @item duration, d
  326. Specify the duration of the cross fade effect. See
  327. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  328. for the accepted syntax.
  329. By default the duration is determined by @var{nb_samples}.
  330. If set this option is used instead of @var{nb_samples}.
  331. @item overlap, o
  332. Should first stream end overlap with second stream start. Default is enabled.
  333. @item curve1
  334. Set curve for cross fade transition for first stream.
  335. @item curve2
  336. Set curve for cross fade transition for second stream.
  337. For description of available curve types see @ref{afade} filter description.
  338. @end table
  339. @subsection Examples
  340. @itemize
  341. @item
  342. Cross fade from one input to another:
  343. @example
  344. ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
  345. @end example
  346. @item
  347. Cross fade from one input to another but without overlapping:
  348. @example
  349. ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
  350. @end example
  351. @end itemize
  352. @section acrusher
  353. Reduce audio bit resolution.
  354. This filter is bit crusher with enhanced functionality. A bit crusher
  355. is used to audibly reduce number of bits an audio signal is sampled
  356. with. This doesn't change the bit depth at all, it just produces the
  357. effect. Material reduced in bit depth sounds more harsh and "digital".
  358. This filter is able to even round to continous values instead of discrete
  359. bit depths.
  360. Additionally it has a D/C offset which results in different crushing of
  361. the lower and the upper half of the signal.
  362. An Anti-Aliasing setting is able to produce "softer" crushing sounds.
  363. Another feature of this filter is the logarithmic mode.
  364. This setting switches from linear distances between bits to logarithmic ones.
  365. The result is a much more "natural" sounding crusher which doesn't gate low
  366. signals for example. The human ear has a logarithmic perception, too
  367. so this kind of crushing is much more pleasant.
  368. Logarithmic crushing is also able to get anti-aliased.
  369. The filter accepts the following options:
  370. @table @option
  371. @item level_in
  372. Set level in.
  373. @item level_out
  374. Set level out.
  375. @item bits
  376. Set bit reduction.
  377. @item mix
  378. Set mixing ammount.
  379. @item mode
  380. Can be linear: @code{lin} or logarithmic: @code{log}.
  381. @item dc
  382. Set DC.
  383. @item aa
  384. Set anti-aliasing.
  385. @item samples
  386. Set sample reduction.
  387. @item lfo
  388. Enable LFO. By default disabled.
  389. @item lforange
  390. Set LFO range.
  391. @item lforate
  392. Set LFO rate.
  393. @end table
  394. @section adelay
  395. Delay one or more audio channels.
  396. Samples in delayed channel are filled with silence.
  397. The filter accepts the following option:
  398. @table @option
  399. @item delays
  400. Set list of delays in milliseconds for each channel separated by '|'.
  401. At least one delay greater than 0 should be provided.
  402. Unused delays will be silently ignored. If number of given delays is
  403. smaller than number of channels all remaining channels will not be delayed.
  404. If you want to delay exact number of samples, append 'S' to number.
  405. @end table
  406. @subsection Examples
  407. @itemize
  408. @item
  409. Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
  410. the second channel (and any other channels that may be present) unchanged.
  411. @example
  412. adelay=1500|0|500
  413. @end example
  414. @item
  415. Delay second channel by 500 samples, the third channel by 700 samples and leave
  416. the first channel (and any other channels that may be present) unchanged.
  417. @example
  418. adelay=0|500S|700S
  419. @end example
  420. @end itemize
  421. @section aecho
  422. Apply echoing to the input audio.
  423. Echoes are reflected sound and can occur naturally amongst mountains
  424. (and sometimes large buildings) when talking or shouting; digital echo
  425. effects emulate this behaviour and are often used to help fill out the
  426. sound of a single instrument or vocal. The time difference between the
  427. original signal and the reflection is the @code{delay}, and the
  428. loudness of the reflected signal is the @code{decay}.
  429. Multiple echoes can have different delays and decays.
  430. A description of the accepted parameters follows.
  431. @table @option
  432. @item in_gain
  433. Set input gain of reflected signal. Default is @code{0.6}.
  434. @item out_gain
  435. Set output gain of reflected signal. Default is @code{0.3}.
  436. @item delays
  437. Set list of time intervals in milliseconds between original signal and reflections
  438. separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
  439. Default is @code{1000}.
  440. @item decays
  441. Set list of loudnesses of reflected signals separated by '|'.
  442. Allowed range for each @code{decay} is @code{(0 - 1.0]}.
  443. Default is @code{0.5}.
  444. @end table
  445. @subsection Examples
  446. @itemize
  447. @item
  448. Make it sound as if there are twice as many instruments as are actually playing:
  449. @example
  450. aecho=0.8:0.88:60:0.4
  451. @end example
  452. @item
  453. If delay is very short, then it sound like a (metallic) robot playing music:
  454. @example
  455. aecho=0.8:0.88:6:0.4
  456. @end example
  457. @item
  458. A longer delay will sound like an open air concert in the mountains:
  459. @example
  460. aecho=0.8:0.9:1000:0.3
  461. @end example
  462. @item
  463. Same as above but with one more mountain:
  464. @example
  465. aecho=0.8:0.9:1000|1800:0.3|0.25
  466. @end example
  467. @end itemize
  468. @section aemphasis
  469. Audio emphasis filter creates or restores material directly taken from LPs or
  470. emphased CDs with different filter curves. E.g. to store music on vinyl the
  471. signal has to be altered by a filter first to even out the disadvantages of
  472. this recording medium.
  473. Once the material is played back the inverse filter has to be applied to
  474. restore the distortion of the frequency response.
  475. The filter accepts the following options:
  476. @table @option
  477. @item level_in
  478. Set input gain.
  479. @item level_out
  480. Set output gain.
  481. @item mode
  482. Set filter mode. For restoring material use @code{reproduction} mode, otherwise
  483. use @code{production} mode. Default is @code{reproduction} mode.
  484. @item type
  485. Set filter type. Selects medium. Can be one of the following:
  486. @table @option
  487. @item col
  488. select Columbia.
  489. @item emi
  490. select EMI.
  491. @item bsi
  492. select BSI (78RPM).
  493. @item riaa
  494. select RIAA.
  495. @item cd
  496. select Compact Disc (CD).
  497. @item 50fm
  498. select 50µs (FM).
  499. @item 75fm
  500. select 75µs (FM).
  501. @item 50kf
  502. select 50µs (FM-KF).
  503. @item 75kf
  504. select 75µs (FM-KF).
  505. @end table
  506. @end table
  507. @section aeval
  508. Modify an audio signal according to the specified expressions.
  509. This filter accepts one or more expressions (one for each channel),
  510. which are evaluated and used to modify a corresponding audio signal.
  511. It accepts the following parameters:
  512. @table @option
  513. @item exprs
  514. Set the '|'-separated expressions list for each separate channel. If
  515. the number of input channels is greater than the number of
  516. expressions, the last specified expression is used for the remaining
  517. output channels.
  518. @item channel_layout, c
  519. Set output channel layout. If not specified, the channel layout is
  520. specified by the number of expressions. If set to @samp{same}, it will
  521. use by default the same input channel layout.
  522. @end table
  523. Each expression in @var{exprs} can contain the following constants and functions:
  524. @table @option
  525. @item ch
  526. channel number of the current expression
  527. @item n
  528. number of the evaluated sample, starting from 0
  529. @item s
  530. sample rate
  531. @item t
  532. time of the evaluated sample expressed in seconds
  533. @item nb_in_channels
  534. @item nb_out_channels
  535. input and output number of channels
  536. @item val(CH)
  537. the value of input channel with number @var{CH}
  538. @end table
  539. Note: this filter is slow. For faster processing you should use a
  540. dedicated filter.
  541. @subsection Examples
  542. @itemize
  543. @item
  544. Half volume:
  545. @example
  546. aeval=val(ch)/2:c=same
  547. @end example
  548. @item
  549. Invert phase of the second channel:
  550. @example
  551. aeval=val(0)|-val(1)
  552. @end example
  553. @end itemize
  554. @anchor{afade}
  555. @section afade
  556. Apply fade-in/out effect to input audio.
  557. A description of the accepted parameters follows.
  558. @table @option
  559. @item type, t
  560. Specify the effect type, can be either @code{in} for fade-in, or
  561. @code{out} for a fade-out effect. Default is @code{in}.
  562. @item start_sample, ss
  563. Specify the number of the start sample for starting to apply the fade
  564. effect. Default is 0.
  565. @item nb_samples, ns
  566. Specify the number of samples for which the fade effect has to last. At
  567. the end of the fade-in effect the output audio will have the same
  568. volume as the input audio, at the end of the fade-out transition
  569. the output audio will be silence. Default is 44100.
  570. @item start_time, st
  571. Specify the start time of the fade effect. Default is 0.
  572. The value must be specified as a time duration; see
  573. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  574. for the accepted syntax.
  575. If set this option is used instead of @var{start_sample}.
  576. @item duration, d
  577. Specify the duration of the fade effect. See
  578. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  579. for the accepted syntax.
  580. At the end of the fade-in effect the output audio will have the same
  581. volume as the input audio, at the end of the fade-out transition
  582. the output audio will be silence.
  583. By default the duration is determined by @var{nb_samples}.
  584. If set this option is used instead of @var{nb_samples}.
  585. @item curve
  586. Set curve for fade transition.
  587. It accepts the following values:
  588. @table @option
  589. @item tri
  590. select triangular, linear slope (default)
  591. @item qsin
  592. select quarter of sine wave
  593. @item hsin
  594. select half of sine wave
  595. @item esin
  596. select exponential sine wave
  597. @item log
  598. select logarithmic
  599. @item ipar
  600. select inverted parabola
  601. @item qua
  602. select quadratic
  603. @item cub
  604. select cubic
  605. @item squ
  606. select square root
  607. @item cbr
  608. select cubic root
  609. @item par
  610. select parabola
  611. @item exp
  612. select exponential
  613. @item iqsin
  614. select inverted quarter of sine wave
  615. @item ihsin
  616. select inverted half of sine wave
  617. @item dese
  618. select double-exponential seat
  619. @item desi
  620. select double-exponential sigmoid
  621. @end table
  622. @end table
  623. @subsection Examples
  624. @itemize
  625. @item
  626. Fade in first 15 seconds of audio:
  627. @example
  628. afade=t=in:ss=0:d=15
  629. @end example
  630. @item
  631. Fade out last 25 seconds of a 900 seconds audio:
  632. @example
  633. afade=t=out:st=875:d=25
  634. @end example
  635. @end itemize
  636. @section afftfilt
  637. Apply arbitrary expressions to samples in frequency domain.
  638. @table @option
  639. @item real
  640. Set frequency domain real expression for each separate channel separated
  641. by '|'. Default is "1".
  642. If the number of input channels is greater than the number of
  643. expressions, the last specified expression is used for the remaining
  644. output channels.
  645. @item imag
  646. Set frequency domain imaginary expression for each separate channel
  647. separated by '|'. If not set, @var{real} option is used.
  648. Each expression in @var{real} and @var{imag} can contain the following
  649. constants:
  650. @table @option
  651. @item sr
  652. sample rate
  653. @item b
  654. current frequency bin number
  655. @item nb
  656. number of available bins
  657. @item ch
  658. channel number of the current expression
  659. @item chs
  660. number of channels
  661. @item pts
  662. current frame pts
  663. @end table
  664. @item win_size
  665. Set window size.
  666. It accepts the following values:
  667. @table @samp
  668. @item w16
  669. @item w32
  670. @item w64
  671. @item w128
  672. @item w256
  673. @item w512
  674. @item w1024
  675. @item w2048
  676. @item w4096
  677. @item w8192
  678. @item w16384
  679. @item w32768
  680. @item w65536
  681. @end table
  682. Default is @code{w4096}
  683. @item win_func
  684. Set window function. Default is @code{hann}.
  685. @item overlap
  686. Set window overlap. If set to 1, the recommended overlap for selected
  687. window function will be picked. Default is @code{0.75}.
  688. @end table
  689. @subsection Examples
  690. @itemize
  691. @item
  692. Leave almost only low frequencies in audio:
  693. @example
  694. afftfilt="1-clip((b/nb)*b,0,1)"
  695. @end example
  696. @end itemize
  697. @anchor{aformat}
  698. @section aformat
  699. Set output format constraints for the input audio. The framework will
  700. negotiate the most appropriate format to minimize conversions.
  701. It accepts the following parameters:
  702. @table @option
  703. @item sample_fmts
  704. A '|'-separated list of requested sample formats.
  705. @item sample_rates
  706. A '|'-separated list of requested sample rates.
  707. @item channel_layouts
  708. A '|'-separated list of requested channel layouts.
  709. See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  710. for the required syntax.
  711. @end table
  712. If a parameter is omitted, all values are allowed.
  713. Force the output to either unsigned 8-bit or signed 16-bit stereo
  714. @example
  715. aformat=sample_fmts=u8|s16:channel_layouts=stereo
  716. @end example
  717. @section agate
  718. A gate is mainly used to reduce lower parts of a signal. This kind of signal
  719. processing reduces disturbing noise between useful signals.
  720. Gating is done by detecting the volume below a chosen level @var{threshold}
  721. and divide it by the factor set with @var{ratio}. The bottom of the noise
  722. floor is set via @var{range}. Because an exact manipulation of the signal
  723. would cause distortion of the waveform the reduction can be levelled over
  724. time. This is done by setting @var{attack} and @var{release}.
  725. @var{attack} determines how long the signal has to fall below the threshold
  726. before any reduction will occur and @var{release} sets the time the signal
  727. has to raise above the threshold to reduce the reduction again.
  728. Shorter signals than the chosen attack time will be left untouched.
  729. @table @option
  730. @item level_in
  731. Set input level before filtering.
  732. Default is 1. Allowed range is from 0.015625 to 64.
  733. @item range
  734. Set the level of gain reduction when the signal is below the threshold.
  735. Default is 0.06125. Allowed range is from 0 to 1.
  736. @item threshold
  737. If a signal rises above this level the gain reduction is released.
  738. Default is 0.125. Allowed range is from 0 to 1.
  739. @item ratio
  740. Set a ratio about which the signal is reduced.
  741. Default is 2. Allowed range is from 1 to 9000.
  742. @item attack
  743. Amount of milliseconds the signal has to rise above the threshold before gain
  744. reduction stops.
  745. Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
  746. @item release
  747. Amount of milliseconds the signal has to fall below the threshold before the
  748. reduction is increased again. Default is 250 milliseconds.
  749. Allowed range is from 0.01 to 9000.
  750. @item makeup
  751. Set amount of amplification of signal after processing.
  752. Default is 1. Allowed range is from 1 to 64.
  753. @item knee
  754. Curve the sharp knee around the threshold to enter gain reduction more softly.
  755. Default is 2.828427125. Allowed range is from 1 to 8.
  756. @item detection
  757. Choose if exact signal should be taken for detection or an RMS like one.
  758. Default is rms. Can be peak or rms.
  759. @item link
  760. Choose if the average level between all channels or the louder channel affects
  761. the reduction.
  762. Default is average. Can be average or maximum.
  763. @end table
  764. @section alimiter
  765. The limiter prevents input signal from raising over a desired threshold.
  766. This limiter uses lookahead technology to prevent your signal from distorting.
  767. It means that there is a small delay after signal is processed. Keep in mind
  768. that the delay it produces is the attack time you set.
  769. The filter accepts the following options:
  770. @table @option
  771. @item level_in
  772. Set input gain. Default is 1.
  773. @item level_out
  774. Set output gain. Default is 1.
  775. @item limit
  776. Don't let signals above this level pass the limiter. Default is 1.
  777. @item attack
  778. The limiter will reach its attenuation level in this amount of time in
  779. milliseconds. Default is 5 milliseconds.
  780. @item release
  781. Come back from limiting to attenuation 1.0 in this amount of milliseconds.
  782. Default is 50 milliseconds.
  783. @item asc
  784. When gain reduction is always needed ASC takes care of releasing to an
  785. average reduction level rather than reaching a reduction of 0 in the release
  786. time.
  787. @item asc_level
  788. Select how much the release time is affected by ASC, 0 means nearly no changes
  789. in release time while 1 produces higher release times.
  790. @item level
  791. Auto level output signal. Default is enabled.
  792. This normalizes audio back to 0dB if enabled.
  793. @end table
  794. Depending on picked setting it is recommended to upsample input 2x or 4x times
  795. with @ref{aresample} before applying this filter.
  796. @section allpass
  797. Apply a two-pole all-pass filter with central frequency (in Hz)
  798. @var{frequency}, and filter-width @var{width}.
  799. An all-pass filter changes the audio's frequency to phase relationship
  800. without changing its frequency to amplitude relationship.
  801. The filter accepts the following options:
  802. @table @option
  803. @item frequency, f
  804. Set frequency in Hz.
  805. @item width_type
  806. Set method to specify band-width of filter.
  807. @table @option
  808. @item h
  809. Hz
  810. @item q
  811. Q-Factor
  812. @item o
  813. octave
  814. @item s
  815. slope
  816. @end table
  817. @item width, w
  818. Specify the band-width of a filter in width_type units.
  819. @end table
  820. @section aloop
  821. Loop audio samples.
  822. The filter accepts the following options:
  823. @table @option
  824. @item loop
  825. Set the number of loops.
  826. @item size
  827. Set maximal number of samples.
  828. @item start
  829. Set first sample of loop.
  830. @end table
  831. @anchor{amerge}
  832. @section amerge
  833. Merge two or more audio streams into a single multi-channel stream.
  834. The filter accepts the following options:
  835. @table @option
  836. @item inputs
  837. Set the number of inputs. Default is 2.
  838. @end table
  839. If the channel layouts of the inputs are disjoint, and therefore compatible,
  840. the channel layout of the output will be set accordingly and the channels
  841. will be reordered as necessary. If the channel layouts of the inputs are not
  842. disjoint, the output will have all the channels of the first input then all
  843. the channels of the second input, in that order, and the channel layout of
  844. the output will be the default value corresponding to the total number of
  845. channels.
  846. For example, if the first input is in 2.1 (FL+FR+LF) and the second input
  847. is FC+BL+BR, then the output will be in 5.1, with the channels in the
  848. following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
  849. first input, b1 is the first channel of the second input).
  850. On the other hand, if both input are in stereo, the output channels will be
  851. in the default order: a1, a2, b1, b2, and the channel layout will be
  852. arbitrarily set to 4.0, which may or may not be the expected value.
  853. All inputs must have the same sample rate, and format.
  854. If inputs do not have the same duration, the output will stop with the
  855. shortest.
  856. @subsection Examples
  857. @itemize
  858. @item
  859. Merge two mono files into a stereo stream:
  860. @example
  861. amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
  862. @end example
  863. @item
  864. Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
  865. @example
  866. 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
  867. @end example
  868. @end itemize
  869. @section amix
  870. Mixes multiple audio inputs into a single output.
  871. Note that this filter only supports float samples (the @var{amerge}
  872. and @var{pan} audio filters support many formats). If the @var{amix}
  873. input has integer samples then @ref{aresample} will be automatically
  874. inserted to perform the conversion to float samples.
  875. For example
  876. @example
  877. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
  878. @end example
  879. will mix 3 input audio streams to a single output with the same duration as the
  880. first input and a dropout transition time of 3 seconds.
  881. It accepts the following parameters:
  882. @table @option
  883. @item inputs
  884. The number of inputs. If unspecified, it defaults to 2.
  885. @item duration
  886. How to determine the end-of-stream.
  887. @table @option
  888. @item longest
  889. The duration of the longest input. (default)
  890. @item shortest
  891. The duration of the shortest input.
  892. @item first
  893. The duration of the first input.
  894. @end table
  895. @item dropout_transition
  896. The transition time, in seconds, for volume renormalization when an input
  897. stream ends. The default value is 2 seconds.
  898. @end table
  899. @section anequalizer
  900. High-order parametric multiband equalizer for each channel.
  901. It accepts the following parameters:
  902. @table @option
  903. @item params
  904. This option string is in format:
  905. "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
  906. Each equalizer band is separated by '|'.
  907. @table @option
  908. @item chn
  909. Set channel number to which equalization will be applied.
  910. If input doesn't have that channel the entry is ignored.
  911. @item f
  912. Set central frequency for band.
  913. If input doesn't have that frequency the entry is ignored.
  914. @item w
  915. Set band width in hertz.
  916. @item g
  917. Set band gain in dB.
  918. @item t
  919. Set filter type for band, optional, can be:
  920. @table @samp
  921. @item 0
  922. Butterworth, this is default.
  923. @item 1
  924. Chebyshev type 1.
  925. @item 2
  926. Chebyshev type 2.
  927. @end table
  928. @end table
  929. @item curves
  930. With this option activated frequency response of anequalizer is displayed
  931. in video stream.
  932. @item size
  933. Set video stream size. Only useful if curves option is activated.
  934. @item mgain
  935. Set max gain that will be displayed. Only useful if curves option is activated.
  936. Setting this to reasonable value allows to display gain which is derived from
  937. neighbour bands which are too close to each other and thus produce higher gain
  938. when both are activated.
  939. @item fscale
  940. Set frequency scale used to draw frequency response in video output.
  941. Can be linear or logarithmic. Default is logarithmic.
  942. @item colors
  943. Set color for each channel curve which is going to be displayed in video stream.
  944. This is list of color names separated by space or by '|'.
  945. Unrecognised or missing colors will be replaced by white color.
  946. @end table
  947. @subsection Examples
  948. @itemize
  949. @item
  950. Lower gain by 10 of central frequency 200Hz and width 100 Hz
  951. for first 2 channels using Chebyshev type 1 filter:
  952. @example
  953. anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
  954. @end example
  955. @end itemize
  956. @subsection Commands
  957. This filter supports the following commands:
  958. @table @option
  959. @item change
  960. Alter existing filter parameters.
  961. Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
  962. @var{fN} is existing filter number, starting from 0, if no such filter is available
  963. error is returned.
  964. @var{freq} set new frequency parameter.
  965. @var{width} set new width parameter in herz.
  966. @var{gain} set new gain parameter in dB.
  967. Full filter invocation with asendcmd may look like this:
  968. asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
  969. @end table
  970. @section anull
  971. Pass the audio source unchanged to the output.
  972. @section apad
  973. Pad the end of an audio stream with silence.
  974. This can be used together with @command{ffmpeg} @option{-shortest} to
  975. extend audio streams to the same length as the video stream.
  976. A description of the accepted options follows.
  977. @table @option
  978. @item packet_size
  979. Set silence packet size. Default value is 4096.
  980. @item pad_len
  981. Set the number of samples of silence to add to the end. After the
  982. value is reached, the stream is terminated. This option is mutually
  983. exclusive with @option{whole_len}.
  984. @item whole_len
  985. Set the minimum total number of samples in the output audio stream. If
  986. the value is longer than the input audio length, silence is added to
  987. the end, until the value is reached. This option is mutually exclusive
  988. with @option{pad_len}.
  989. @end table
  990. If neither the @option{pad_len} nor the @option{whole_len} option is
  991. set, the filter will add silence to the end of the input stream
  992. indefinitely.
  993. @subsection Examples
  994. @itemize
  995. @item
  996. Add 1024 samples of silence to the end of the input:
  997. @example
  998. apad=pad_len=1024
  999. @end example
  1000. @item
  1001. Make sure the audio output will contain at least 10000 samples, pad
  1002. the input with silence if required:
  1003. @example
  1004. apad=whole_len=10000
  1005. @end example
  1006. @item
  1007. Use @command{ffmpeg} to pad the audio input with silence, so that the
  1008. video stream will always result the shortest and will be converted
  1009. until the end in the output file when using the @option{shortest}
  1010. option:
  1011. @example
  1012. ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
  1013. @end example
  1014. @end itemize
  1015. @section aphaser
  1016. Add a phasing effect to the input audio.
  1017. A phaser filter creates series of peaks and troughs in the frequency spectrum.
  1018. The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
  1019. A description of the accepted parameters follows.
  1020. @table @option
  1021. @item in_gain
  1022. Set input gain. Default is 0.4.
  1023. @item out_gain
  1024. Set output gain. Default is 0.74
  1025. @item delay
  1026. Set delay in milliseconds. Default is 3.0.
  1027. @item decay
  1028. Set decay. Default is 0.4.
  1029. @item speed
  1030. Set modulation speed in Hz. Default is 0.5.
  1031. @item type
  1032. Set modulation type. Default is triangular.
  1033. It accepts the following values:
  1034. @table @samp
  1035. @item triangular, t
  1036. @item sinusoidal, s
  1037. @end table
  1038. @end table
  1039. @section apulsator
  1040. Audio pulsator is something between an autopanner and a tremolo.
  1041. But it can produce funny stereo effects as well. Pulsator changes the volume
  1042. of the left and right channel based on a LFO (low frequency oscillator) with
  1043. different waveforms and shifted phases.
  1044. This filter have the ability to define an offset between left and right
  1045. channel. An offset of 0 means that both LFO shapes match each other.
  1046. The left and right channel are altered equally - a conventional tremolo.
  1047. An offset of 50% means that the shape of the right channel is exactly shifted
  1048. in phase (or moved backwards about half of the frequency) - pulsator acts as
  1049. an autopanner. At 1 both curves match again. Every setting in between moves the
  1050. phase shift gapless between all stages and produces some "bypassing" sounds with
  1051. sine and triangle waveforms. The more you set the offset near 1 (starting from
  1052. the 0.5) the faster the signal passes from the left to the right speaker.
  1053. The filter accepts the following options:
  1054. @table @option
  1055. @item level_in
  1056. Set input gain. By default it is 1. Range is [0.015625 - 64].
  1057. @item level_out
  1058. Set output gain. By default it is 1. Range is [0.015625 - 64].
  1059. @item mode
  1060. Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
  1061. sawup or sawdown. Default is sine.
  1062. @item amount
  1063. Set modulation. Define how much of original signal is affected by the LFO.
  1064. @item offset_l
  1065. Set left channel offset. Default is 0. Allowed range is [0 - 1].
  1066. @item offset_r
  1067. Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
  1068. @item width
  1069. Set pulse width. Default is 1. Allowed range is [0 - 2].
  1070. @item timing
  1071. Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
  1072. @item bpm
  1073. Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
  1074. is set to bpm.
  1075. @item ms
  1076. Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
  1077. is set to ms.
  1078. @item hz
  1079. Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
  1080. if timing is set to hz.
  1081. @end table
  1082. @anchor{aresample}
  1083. @section aresample
  1084. Resample the input audio to the specified parameters, using the
  1085. libswresample library. If none are specified then the filter will
  1086. automatically convert between its input and output.
  1087. This filter is also able to stretch/squeeze the audio data to make it match
  1088. the timestamps or to inject silence / cut out audio to make it match the
  1089. timestamps, do a combination of both or do neither.
  1090. The filter accepts the syntax
  1091. [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
  1092. expresses a sample rate and @var{resampler_options} is a list of
  1093. @var{key}=@var{value} pairs, separated by ":". See the
  1094. ffmpeg-resampler manual for the complete list of supported options.
  1095. @subsection Examples
  1096. @itemize
  1097. @item
  1098. Resample the input audio to 44100Hz:
  1099. @example
  1100. aresample=44100
  1101. @end example
  1102. @item
  1103. Stretch/squeeze samples to the given timestamps, with a maximum of 1000
  1104. samples per second compensation:
  1105. @example
  1106. aresample=async=1000
  1107. @end example
  1108. @end itemize
  1109. @section areverse
  1110. Reverse an audio clip.
  1111. Warning: This filter requires memory to buffer the entire clip, so trimming
  1112. is suggested.
  1113. @subsection Examples
  1114. @itemize
  1115. @item
  1116. Take the first 5 seconds of a clip, and reverse it.
  1117. @example
  1118. atrim=end=5,areverse
  1119. @end example
  1120. @end itemize
  1121. @section asetnsamples
  1122. Set the number of samples per each output audio frame.
  1123. The last output packet may contain a different number of samples, as
  1124. the filter will flush all the remaining samples when the input audio
  1125. signal its end.
  1126. The filter accepts the following options:
  1127. @table @option
  1128. @item nb_out_samples, n
  1129. Set the number of frames per each output audio frame. The number is
  1130. intended as the number of samples @emph{per each channel}.
  1131. Default value is 1024.
  1132. @item pad, p
  1133. If set to 1, the filter will pad the last audio frame with zeroes, so
  1134. that the last frame will contain the same number of samples as the
  1135. previous ones. Default value is 1.
  1136. @end table
  1137. For example, to set the number of per-frame samples to 1234 and
  1138. disable padding for the last frame, use:
  1139. @example
  1140. asetnsamples=n=1234:p=0
  1141. @end example
  1142. @section asetrate
  1143. Set the sample rate without altering the PCM data.
  1144. This will result in a change of speed and pitch.
  1145. The filter accepts the following options:
  1146. @table @option
  1147. @item sample_rate, r
  1148. Set the output sample rate. Default is 44100 Hz.
  1149. @end table
  1150. @section ashowinfo
  1151. Show a line containing various information for each input audio frame.
  1152. The input audio is not modified.
  1153. The shown line contains a sequence of key/value pairs of the form
  1154. @var{key}:@var{value}.
  1155. The following values are shown in the output:
  1156. @table @option
  1157. @item n
  1158. The (sequential) number of the input frame, starting from 0.
  1159. @item pts
  1160. The presentation timestamp of the input frame, in time base units; the time base
  1161. depends on the filter input pad, and is usually 1/@var{sample_rate}.
  1162. @item pts_time
  1163. The presentation timestamp of the input frame in seconds.
  1164. @item pos
  1165. position of the frame in the input stream, -1 if this information in
  1166. unavailable and/or meaningless (for example in case of synthetic audio)
  1167. @item fmt
  1168. The sample format.
  1169. @item chlayout
  1170. The channel layout.
  1171. @item rate
  1172. The sample rate for the audio frame.
  1173. @item nb_samples
  1174. The number of samples (per channel) in the frame.
  1175. @item checksum
  1176. The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
  1177. audio, the data is treated as if all the planes were concatenated.
  1178. @item plane_checksums
  1179. A list of Adler-32 checksums for each data plane.
  1180. @end table
  1181. @anchor{astats}
  1182. @section astats
  1183. Display time domain statistical information about the audio channels.
  1184. Statistics are calculated and displayed for each audio channel and,
  1185. where applicable, an overall figure is also given.
  1186. It accepts the following option:
  1187. @table @option
  1188. @item length
  1189. Short window length in seconds, used for peak and trough RMS measurement.
  1190. Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.1 - 10]}.
  1191. @item metadata
  1192. Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
  1193. where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
  1194. disabled.
  1195. Available keys for each channel are:
  1196. DC_offset
  1197. Min_level
  1198. Max_level
  1199. Min_difference
  1200. Max_difference
  1201. Mean_difference
  1202. Peak_level
  1203. RMS_peak
  1204. RMS_trough
  1205. Crest_factor
  1206. Flat_factor
  1207. Peak_count
  1208. Bit_depth
  1209. and for Overall:
  1210. DC_offset
  1211. Min_level
  1212. Max_level
  1213. Min_difference
  1214. Max_difference
  1215. Mean_difference
  1216. Peak_level
  1217. RMS_level
  1218. RMS_peak
  1219. RMS_trough
  1220. Flat_factor
  1221. Peak_count
  1222. Bit_depth
  1223. Number_of_samples
  1224. For example full key look like this @code{lavfi.astats.1.DC_offset} or
  1225. this @code{lavfi.astats.Overall.Peak_count}.
  1226. For description what each key means read below.
  1227. @item reset
  1228. Set number of frame after which stats are going to be recalculated.
  1229. Default is disabled.
  1230. @end table
  1231. A description of each shown parameter follows:
  1232. @table @option
  1233. @item DC offset
  1234. Mean amplitude displacement from zero.
  1235. @item Min level
  1236. Minimal sample level.
  1237. @item Max level
  1238. Maximal sample level.
  1239. @item Min difference
  1240. Minimal difference between two consecutive samples.
  1241. @item Max difference
  1242. Maximal difference between two consecutive samples.
  1243. @item Mean difference
  1244. Mean difference between two consecutive samples.
  1245. The average of each difference between two consecutive samples.
  1246. @item Peak level dB
  1247. @item RMS level dB
  1248. Standard peak and RMS level measured in dBFS.
  1249. @item RMS peak dB
  1250. @item RMS trough dB
  1251. Peak and trough values for RMS level measured over a short window.
  1252. @item Crest factor
  1253. Standard ratio of peak to RMS level (note: not in dB).
  1254. @item Flat factor
  1255. Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
  1256. (i.e. either @var{Min level} or @var{Max level}).
  1257. @item Peak count
  1258. Number of occasions (not the number of samples) that the signal attained either
  1259. @var{Min level} or @var{Max level}.
  1260. @item Bit depth
  1261. Overall bit depth of audio. Number of bits used for each sample.
  1262. @end table
  1263. @section asyncts
  1264. Synchronize audio data with timestamps by squeezing/stretching it and/or
  1265. dropping samples/adding silence when needed.
  1266. This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
  1267. It accepts the following parameters:
  1268. @table @option
  1269. @item compensate
  1270. Enable stretching/squeezing the data to make it match the timestamps. Disabled
  1271. by default. When disabled, time gaps are covered with silence.
  1272. @item min_delta
  1273. The minimum difference between timestamps and audio data (in seconds) to trigger
  1274. adding/dropping samples. The default value is 0.1. If you get an imperfect
  1275. sync with this filter, try setting this parameter to 0.
  1276. @item max_comp
  1277. The maximum compensation in samples per second. Only relevant with compensate=1.
  1278. The default value is 500.
  1279. @item first_pts
  1280. Assume that the first PTS should be this value. The time base is 1 / sample
  1281. rate. This allows for padding/trimming at the start of the stream. By default,
  1282. no assumption is made about the first frame's expected PTS, so no padding or
  1283. trimming is done. For example, this could be set to 0 to pad the beginning with
  1284. silence if an audio stream starts after the video stream or to trim any samples
  1285. with a negative PTS due to encoder delay.
  1286. @end table
  1287. @section atempo
  1288. Adjust audio tempo.
  1289. The filter accepts exactly one parameter, the audio tempo. If not
  1290. specified then the filter will assume nominal 1.0 tempo. Tempo must
  1291. be in the [0.5, 2.0] range.
  1292. @subsection Examples
  1293. @itemize
  1294. @item
  1295. Slow down audio to 80% tempo:
  1296. @example
  1297. atempo=0.8
  1298. @end example
  1299. @item
  1300. To speed up audio to 125% tempo:
  1301. @example
  1302. atempo=1.25
  1303. @end example
  1304. @end itemize
  1305. @section atrim
  1306. Trim the input so that the output contains one continuous subpart of the input.
  1307. It accepts the following parameters:
  1308. @table @option
  1309. @item start
  1310. Timestamp (in seconds) of the start of the section to keep. I.e. the audio
  1311. sample with the timestamp @var{start} will be the first sample in the output.
  1312. @item end
  1313. Specify time of the first audio sample that will be dropped, i.e. the
  1314. audio sample immediately preceding the one with the timestamp @var{end} will be
  1315. the last sample in the output.
  1316. @item start_pts
  1317. Same as @var{start}, except this option sets the start timestamp in samples
  1318. instead of seconds.
  1319. @item end_pts
  1320. Same as @var{end}, except this option sets the end timestamp in samples instead
  1321. of seconds.
  1322. @item duration
  1323. The maximum duration of the output in seconds.
  1324. @item start_sample
  1325. The number of the first sample that should be output.
  1326. @item end_sample
  1327. The number of the first sample that should be dropped.
  1328. @end table
  1329. @option{start}, @option{end}, and @option{duration} are expressed as time
  1330. duration specifications; see
  1331. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  1332. Note that the first two sets of the start/end options and the @option{duration}
  1333. option look at the frame timestamp, while the _sample options simply count the
  1334. samples that pass through the filter. So start/end_pts and start/end_sample will
  1335. give different results when the timestamps are wrong, inexact or do not start at
  1336. zero. Also note that this filter does not modify the timestamps. If you wish
  1337. to have the output timestamps start at zero, insert the asetpts filter after the
  1338. atrim filter.
  1339. If multiple start or end options are set, this filter tries to be greedy and
  1340. keep all samples that match at least one of the specified constraints. To keep
  1341. only the part that matches all the constraints at once, chain multiple atrim
  1342. filters.
  1343. The defaults are such that all the input is kept. So it is possible to set e.g.
  1344. just the end values to keep everything before the specified time.
  1345. Examples:
  1346. @itemize
  1347. @item
  1348. Drop everything except the second minute of input:
  1349. @example
  1350. ffmpeg -i INPUT -af atrim=60:120
  1351. @end example
  1352. @item
  1353. Keep only the first 1000 samples:
  1354. @example
  1355. ffmpeg -i INPUT -af atrim=end_sample=1000
  1356. @end example
  1357. @end itemize
  1358. @section bandpass
  1359. Apply a two-pole Butterworth band-pass filter with central
  1360. frequency @var{frequency}, and (3dB-point) band-width width.
  1361. The @var{csg} option selects a constant skirt gain (peak gain = Q)
  1362. instead of the default: constant 0dB peak gain.
  1363. The filter roll off at 6dB per octave (20dB per decade).
  1364. The filter accepts the following options:
  1365. @table @option
  1366. @item frequency, f
  1367. Set the filter's central frequency. Default is @code{3000}.
  1368. @item csg
  1369. Constant skirt gain if set to 1. Defaults to 0.
  1370. @item width_type
  1371. Set method to specify band-width of filter.
  1372. @table @option
  1373. @item h
  1374. Hz
  1375. @item q
  1376. Q-Factor
  1377. @item o
  1378. octave
  1379. @item s
  1380. slope
  1381. @end table
  1382. @item width, w
  1383. Specify the band-width of a filter in width_type units.
  1384. @end table
  1385. @section bandreject
  1386. Apply a two-pole Butterworth band-reject filter with central
  1387. frequency @var{frequency}, and (3dB-point) band-width @var{width}.
  1388. The filter roll off at 6dB per octave (20dB per decade).
  1389. The filter accepts the following options:
  1390. @table @option
  1391. @item frequency, f
  1392. Set the filter's central frequency. Default is @code{3000}.
  1393. @item width_type
  1394. Set method to specify band-width of filter.
  1395. @table @option
  1396. @item h
  1397. Hz
  1398. @item q
  1399. Q-Factor
  1400. @item o
  1401. octave
  1402. @item s
  1403. slope
  1404. @end table
  1405. @item width, w
  1406. Specify the band-width of a filter in width_type units.
  1407. @end table
  1408. @section bass
  1409. Boost or cut the bass (lower) frequencies of the audio using a two-pole
  1410. shelving filter with a response similar to that of a standard
  1411. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  1412. The filter accepts the following options:
  1413. @table @option
  1414. @item gain, g
  1415. Give the gain at 0 Hz. Its useful range is about -20
  1416. (for a large cut) to +20 (for a large boost).
  1417. Beware of clipping when using a positive gain.
  1418. @item frequency, f
  1419. Set the filter's central frequency and so can be used
  1420. to extend or reduce the frequency range to be boosted or cut.
  1421. The default value is @code{100} Hz.
  1422. @item width_type
  1423. Set method to specify band-width of filter.
  1424. @table @option
  1425. @item h
  1426. Hz
  1427. @item q
  1428. Q-Factor
  1429. @item o
  1430. octave
  1431. @item s
  1432. slope
  1433. @end table
  1434. @item width, w
  1435. Determine how steep is the filter's shelf transition.
  1436. @end table
  1437. @section biquad
  1438. Apply a biquad IIR filter with the given coefficients.
  1439. Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
  1440. are the numerator and denominator coefficients respectively.
  1441. @section bs2b
  1442. Bauer stereo to binaural transformation, which improves headphone listening of
  1443. stereo audio records.
  1444. It accepts the following parameters:
  1445. @table @option
  1446. @item profile
  1447. Pre-defined crossfeed level.
  1448. @table @option
  1449. @item default
  1450. Default level (fcut=700, feed=50).
  1451. @item cmoy
  1452. Chu Moy circuit (fcut=700, feed=60).
  1453. @item jmeier
  1454. Jan Meier circuit (fcut=650, feed=95).
  1455. @end table
  1456. @item fcut
  1457. Cut frequency (in Hz).
  1458. @item feed
  1459. Feed level (in Hz).
  1460. @end table
  1461. @section channelmap
  1462. Remap input channels to new locations.
  1463. It accepts the following parameters:
  1464. @table @option
  1465. @item channel_layout
  1466. The channel layout of the output stream.
  1467. @item map
  1468. Map channels from input to output. The argument is a '|'-separated list of
  1469. mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
  1470. @var{in_channel} form. @var{in_channel} can be either the name of the input
  1471. channel (e.g. FL for front left) or its index in the input channel layout.
  1472. @var{out_channel} is the name of the output channel or its index in the output
  1473. channel layout. If @var{out_channel} is not given then it is implicitly an
  1474. index, starting with zero and increasing by one for each mapping.
  1475. @end table
  1476. If no mapping is present, the filter will implicitly map input channels to
  1477. output channels, preserving indices.
  1478. For example, assuming a 5.1+downmix input MOV file,
  1479. @example
  1480. ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
  1481. @end example
  1482. will create an output WAV file tagged as stereo from the downmix channels of
  1483. the input.
  1484. To fix a 5.1 WAV improperly encoded in AAC's native channel order
  1485. @example
  1486. ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
  1487. @end example
  1488. @section channelsplit
  1489. Split each channel from an input audio stream into a separate output stream.
  1490. It accepts the following parameters:
  1491. @table @option
  1492. @item channel_layout
  1493. The channel layout of the input stream. The default is "stereo".
  1494. @end table
  1495. For example, assuming a stereo input MP3 file,
  1496. @example
  1497. ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
  1498. @end example
  1499. will create an output Matroska file with two audio streams, one containing only
  1500. the left channel and the other the right channel.
  1501. Split a 5.1 WAV file into per-channel files:
  1502. @example
  1503. ffmpeg -i in.wav -filter_complex
  1504. 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
  1505. -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
  1506. front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
  1507. side_right.wav
  1508. @end example
  1509. @section chorus
  1510. Add a chorus effect to the audio.
  1511. Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
  1512. Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
  1513. constant, with chorus, it is varied using using sinusoidal or triangular modulation.
  1514. The modulation depth defines the range the modulated delay is played before or after
  1515. the delay. Hence the delayed sound will sound slower or faster, that is the delayed
  1516. sound tuned around the original one, like in a chorus where some vocals are slightly
  1517. off key.
  1518. It accepts the following parameters:
  1519. @table @option
  1520. @item in_gain
  1521. Set input gain. Default is 0.4.
  1522. @item out_gain
  1523. Set output gain. Default is 0.4.
  1524. @item delays
  1525. Set delays. A typical delay is around 40ms to 60ms.
  1526. @item decays
  1527. Set decays.
  1528. @item speeds
  1529. Set speeds.
  1530. @item depths
  1531. Set depths.
  1532. @end table
  1533. @subsection Examples
  1534. @itemize
  1535. @item
  1536. A single delay:
  1537. @example
  1538. chorus=0.7:0.9:55:0.4:0.25:2
  1539. @end example
  1540. @item
  1541. Two delays:
  1542. @example
  1543. chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
  1544. @end example
  1545. @item
  1546. Fuller sounding chorus with three delays:
  1547. @example
  1548. chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3
  1549. @end example
  1550. @end itemize
  1551. @section compand
  1552. Compress or expand the audio's dynamic range.
  1553. It accepts the following parameters:
  1554. @table @option
  1555. @item attacks
  1556. @item decays
  1557. A list of times in seconds for each channel over which the instantaneous level
  1558. of the input signal is averaged to determine its volume. @var{attacks} refers to
  1559. increase of volume and @var{decays} refers to decrease of volume. For most
  1560. situations, the attack time (response to the audio getting louder) should be
  1561. shorter than the decay time, because the human ear is more sensitive to sudden
  1562. loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
  1563. a typical value for decay is 0.8 seconds.
  1564. If specified number of attacks & decays is lower than number of channels, the last
  1565. set attack/decay will be used for all remaining channels.
  1566. @item points
  1567. A list of points for the transfer function, specified in dB relative to the
  1568. maximum possible signal amplitude. Each key points list must be defined using
  1569. the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
  1570. @code{x0/y0 x1/y1 x2/y2 ....}
  1571. The input values must be in strictly increasing order but the transfer function
  1572. does not have to be monotonically rising. The point @code{0/0} is assumed but
  1573. may be overridden (by @code{0/out-dBn}). Typical values for the transfer
  1574. function are @code{-70/-70|-60/-20}.
  1575. @item soft-knee
  1576. Set the curve radius in dB for all joints. It defaults to 0.01.
  1577. @item gain
  1578. Set the additional gain in dB to be applied at all points on the transfer
  1579. function. This allows for easy adjustment of the overall gain.
  1580. It defaults to 0.
  1581. @item volume
  1582. Set an initial volume, in dB, to be assumed for each channel when filtering
  1583. starts. This permits the user to supply a nominal level initially, so that, for
  1584. example, a very large gain is not applied to initial signal levels before the
  1585. companding has begun to operate. A typical value for audio which is initially
  1586. quiet is -90 dB. It defaults to 0.
  1587. @item delay
  1588. Set a delay, in seconds. The input audio is analyzed immediately, but audio is
  1589. delayed before being fed to the volume adjuster. Specifying a delay
  1590. approximately equal to the attack/decay times allows the filter to effectively
  1591. operate in predictive rather than reactive mode. It defaults to 0.
  1592. @end table
  1593. @subsection Examples
  1594. @itemize
  1595. @item
  1596. Make music with both quiet and loud passages suitable for listening to in a
  1597. noisy environment:
  1598. @example
  1599. compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
  1600. @end example
  1601. Another example for audio with whisper and explosion parts:
  1602. @example
  1603. compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
  1604. @end example
  1605. @item
  1606. A noise gate for when the noise is at a lower level than the signal:
  1607. @example
  1608. compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
  1609. @end example
  1610. @item
  1611. Here is another noise gate, this time for when the noise is at a higher level
  1612. than the signal (making it, in some ways, similar to squelch):
  1613. @example
  1614. compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
  1615. @end example
  1616. @item
  1617. 2:1 compression starting at -6dB:
  1618. @example
  1619. compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
  1620. @end example
  1621. @item
  1622. 2:1 compression starting at -9dB:
  1623. @example
  1624. compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
  1625. @end example
  1626. @item
  1627. 2:1 compression starting at -12dB:
  1628. @example
  1629. compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
  1630. @end example
  1631. @item
  1632. 2:1 compression starting at -18dB:
  1633. @example
  1634. compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
  1635. @end example
  1636. @item
  1637. 3:1 compression starting at -15dB:
  1638. @example
  1639. compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
  1640. @end example
  1641. @item
  1642. Compressor/Gate:
  1643. @example
  1644. compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
  1645. @end example
  1646. @item
  1647. Expander:
  1648. @example
  1649. compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
  1650. @end example
  1651. @item
  1652. Hard limiter at -6dB:
  1653. @example
  1654. compand=attacks=0:points=-80/-80|-6/-6|20/-6
  1655. @end example
  1656. @item
  1657. Hard limiter at -12dB:
  1658. @example
  1659. compand=attacks=0:points=-80/-80|-12/-12|20/-12
  1660. @end example
  1661. @item
  1662. Hard noise gate at -35 dB:
  1663. @example
  1664. compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
  1665. @end example
  1666. @item
  1667. Soft limiter:
  1668. @example
  1669. compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
  1670. @end example
  1671. @end itemize
  1672. @section compensationdelay
  1673. Compensation Delay Line is a metric based delay to compensate differing
  1674. positions of microphones or speakers.
  1675. For example, you have recorded guitar with two microphones placed in
  1676. different location. Because the front of sound wave has fixed speed in
  1677. normal conditions, the phasing of microphones can vary and depends on
  1678. their location and interposition. The best sound mix can be achieved when
  1679. these microphones are in phase (synchronized). Note that distance of
  1680. ~30 cm between microphones makes one microphone to capture signal in
  1681. antiphase to another microphone. That makes the final mix sounding moody.
  1682. This filter helps to solve phasing problems by adding different delays
  1683. to each microphone track and make them synchronized.
  1684. The best result can be reached when you take one track as base and
  1685. synchronize other tracks one by one with it.
  1686. Remember that synchronization/delay tolerance depends on sample rate, too.
  1687. Higher sample rates will give more tolerance.
  1688. It accepts the following parameters:
  1689. @table @option
  1690. @item mm
  1691. Set millimeters distance. This is compensation distance for fine tuning.
  1692. Default is 0.
  1693. @item cm
  1694. Set cm distance. This is compensation distance for tightening distance setup.
  1695. Default is 0.
  1696. @item m
  1697. Set meters distance. This is compensation distance for hard distance setup.
  1698. Default is 0.
  1699. @item dry
  1700. Set dry amount. Amount of unprocessed (dry) signal.
  1701. Default is 0.
  1702. @item wet
  1703. Set wet amount. Amount of processed (wet) signal.
  1704. Default is 1.
  1705. @item temp
  1706. Set temperature degree in Celsius. This is the temperature of the environment.
  1707. Default is 20.
  1708. @end table
  1709. @section crystalizer
  1710. Simple algorithm to expand audio dynamic range.
  1711. The filter accepts the following options:
  1712. @table @option
  1713. @item i
  1714. Sets the intensity of effect (default: 2.0). Must be in range between 0.0
  1715. (unchanged sound) to 10.0 (maximum effect).
  1716. @item c
  1717. Enable clipping. By default is enabled.
  1718. @end table
  1719. @section dcshift
  1720. Apply a DC shift to the audio.
  1721. This can be useful to remove a DC offset (caused perhaps by a hardware problem
  1722. in the recording chain) from the audio. The effect of a DC offset is reduced
  1723. headroom and hence volume. The @ref{astats} filter can be used to determine if
  1724. a signal has a DC offset.
  1725. @table @option
  1726. @item shift
  1727. Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
  1728. the audio.
  1729. @item limitergain
  1730. Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
  1731. used to prevent clipping.
  1732. @end table
  1733. @section dynaudnorm
  1734. Dynamic Audio Normalizer.
  1735. This filter applies a certain amount of gain to the input audio in order
  1736. to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
  1737. contrast to more "simple" normalization algorithms, the Dynamic Audio
  1738. Normalizer *dynamically* re-adjusts the gain factor to the input audio.
  1739. This allows for applying extra gain to the "quiet" sections of the audio
  1740. while avoiding distortions or clipping the "loud" sections. In other words:
  1741. The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
  1742. sections, in the sense that the volume of each section is brought to the
  1743. same target level. Note, however, that the Dynamic Audio Normalizer achieves
  1744. this goal *without* applying "dynamic range compressing". It will retain 100%
  1745. of the dynamic range *within* each section of the audio file.
  1746. @table @option
  1747. @item f
  1748. Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
  1749. Default is 500 milliseconds.
  1750. The Dynamic Audio Normalizer processes the input audio in small chunks,
  1751. referred to as frames. This is required, because a peak magnitude has no
  1752. meaning for just a single sample value. Instead, we need to determine the
  1753. peak magnitude for a contiguous sequence of sample values. While a "standard"
  1754. normalizer would simply use the peak magnitude of the complete file, the
  1755. Dynamic Audio Normalizer determines the peak magnitude individually for each
  1756. frame. The length of a frame is specified in milliseconds. By default, the
  1757. Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
  1758. been found to give good results with most files.
  1759. Note that the exact frame length, in number of samples, will be determined
  1760. automatically, based on the sampling rate of the individual input audio file.
  1761. @item g
  1762. Set the Gaussian filter window size. In range from 3 to 301, must be odd
  1763. number. Default is 31.
  1764. Probably the most important parameter of the Dynamic Audio Normalizer is the
  1765. @code{window size} of the Gaussian smoothing filter. The filter's window size
  1766. is specified in frames, centered around the current frame. For the sake of
  1767. simplicity, this must be an odd number. Consequently, the default value of 31
  1768. takes into account the current frame, as well as the 15 preceding frames and
  1769. the 15 subsequent frames. Using a larger window results in a stronger
  1770. smoothing effect and thus in less gain variation, i.e. slower gain
  1771. adaptation. Conversely, using a smaller window results in a weaker smoothing
  1772. effect and thus in more gain variation, i.e. faster gain adaptation.
  1773. In other words, the more you increase this value, the more the Dynamic Audio
  1774. Normalizer will behave like a "traditional" normalization filter. On the
  1775. contrary, the more you decrease this value, the more the Dynamic Audio
  1776. Normalizer will behave like a dynamic range compressor.
  1777. @item p
  1778. Set the target peak value. This specifies the highest permissible magnitude
  1779. level for the normalized audio input. This filter will try to approach the
  1780. target peak magnitude as closely as possible, but at the same time it also
  1781. makes sure that the normalized signal will never exceed the peak magnitude.
  1782. A frame's maximum local gain factor is imposed directly by the target peak
  1783. magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
  1784. It is not recommended to go above this value.
  1785. @item m
  1786. Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
  1787. The Dynamic Audio Normalizer determines the maximum possible (local) gain
  1788. factor for each input frame, i.e. the maximum gain factor that does not
  1789. result in clipping or distortion. The maximum gain factor is determined by
  1790. the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
  1791. additionally bounds the frame's maximum gain factor by a predetermined
  1792. (global) maximum gain factor. This is done in order to avoid excessive gain
  1793. factors in "silent" or almost silent frames. By default, the maximum gain
  1794. factor is 10.0, For most inputs the default value should be sufficient and
  1795. it usually is not recommended to increase this value. Though, for input
  1796. with an extremely low overall volume level, it may be necessary to allow even
  1797. higher gain factors. Note, however, that the Dynamic Audio Normalizer does
  1798. not simply apply a "hard" threshold (i.e. cut off values above the threshold).
  1799. Instead, a "sigmoid" threshold function will be applied. This way, the
  1800. gain factors will smoothly approach the threshold value, but never exceed that
  1801. value.
  1802. @item r
  1803. Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
  1804. By default, the Dynamic Audio Normalizer performs "peak" normalization.
  1805. This means that the maximum local gain factor for each frame is defined
  1806. (only) by the frame's highest magnitude sample. This way, the samples can
  1807. be amplified as much as possible without exceeding the maximum signal
  1808. level, i.e. without clipping. Optionally, however, the Dynamic Audio
  1809. Normalizer can also take into account the frame's root mean square,
  1810. abbreviated RMS. In electrical engineering, the RMS is commonly used to
  1811. determine the power of a time-varying signal. It is therefore considered
  1812. that the RMS is a better approximation of the "perceived loudness" than
  1813. just looking at the signal's peak magnitude. Consequently, by adjusting all
  1814. frames to a constant RMS value, a uniform "perceived loudness" can be
  1815. established. If a target RMS value has been specified, a frame's local gain
  1816. factor is defined as the factor that would result in exactly that RMS value.
  1817. Note, however, that the maximum local gain factor is still restricted by the
  1818. frame's highest magnitude sample, in order to prevent clipping.
  1819. @item n
  1820. Enable channels coupling. By default is enabled.
  1821. By default, the Dynamic Audio Normalizer will amplify all channels by the same
  1822. amount. This means the same gain factor will be applied to all channels, i.e.
  1823. the maximum possible gain factor is determined by the "loudest" channel.
  1824. However, in some recordings, it may happen that the volume of the different
  1825. channels is uneven, e.g. one channel may be "quieter" than the other one(s).
  1826. In this case, this option can be used to disable the channel coupling. This way,
  1827. the gain factor will be determined independently for each channel, depending
  1828. only on the individual channel's highest magnitude sample. This allows for
  1829. harmonizing the volume of the different channels.
  1830. @item c
  1831. Enable DC bias correction. By default is disabled.
  1832. An audio signal (in the time domain) is a sequence of sample values.
  1833. In the Dynamic Audio Normalizer these sample values are represented in the
  1834. -1.0 to 1.0 range, regardless of the original input format. Normally, the
  1835. audio signal, or "waveform", should be centered around the zero point.
  1836. That means if we calculate the mean value of all samples in a file, or in a
  1837. single frame, then the result should be 0.0 or at least very close to that
  1838. value. If, however, there is a significant deviation of the mean value from
  1839. 0.0, in either positive or negative direction, this is referred to as a
  1840. DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
  1841. Audio Normalizer provides optional DC bias correction.
  1842. With DC bias correction enabled, the Dynamic Audio Normalizer will determine
  1843. the mean value, or "DC correction" offset, of each input frame and subtract
  1844. that value from all of the frame's sample values which ensures those samples
  1845. are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
  1846. boundaries, the DC correction offset values will be interpolated smoothly
  1847. between neighbouring frames.
  1848. @item b
  1849. Enable alternative boundary mode. By default is disabled.
  1850. The Dynamic Audio Normalizer takes into account a certain neighbourhood
  1851. around each frame. This includes the preceding frames as well as the
  1852. subsequent frames. However, for the "boundary" frames, located at the very
  1853. beginning and at the very end of the audio file, not all neighbouring
  1854. frames are available. In particular, for the first few frames in the audio
  1855. file, the preceding frames are not known. And, similarly, for the last few
  1856. frames in the audio file, the subsequent frames are not known. Thus, the
  1857. question arises which gain factors should be assumed for the missing frames
  1858. in the "boundary" region. The Dynamic Audio Normalizer implements two modes
  1859. to deal with this situation. The default boundary mode assumes a gain factor
  1860. of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
  1861. "fade out" at the beginning and at the end of the input, respectively.
  1862. @item s
  1863. Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
  1864. By default, the Dynamic Audio Normalizer does not apply "traditional"
  1865. compression. This means that signal peaks will not be pruned and thus the
  1866. full dynamic range will be retained within each local neighbourhood. However,
  1867. in some cases it may be desirable to combine the Dynamic Audio Normalizer's
  1868. normalization algorithm with a more "traditional" compression.
  1869. For this purpose, the Dynamic Audio Normalizer provides an optional compression
  1870. (thresholding) function. If (and only if) the compression feature is enabled,
  1871. all input frames will be processed by a soft knee thresholding function prior
  1872. to the actual normalization process. Put simply, the thresholding function is
  1873. going to prune all samples whose magnitude exceeds a certain threshold value.
  1874. However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
  1875. value. Instead, the threshold value will be adjusted for each individual
  1876. frame.
  1877. In general, smaller parameters result in stronger compression, and vice versa.
  1878. Values below 3.0 are not recommended, because audible distortion may appear.
  1879. @end table
  1880. @section earwax
  1881. Make audio easier to listen to on headphones.
  1882. This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
  1883. so that when listened to on headphones the stereo image is moved from
  1884. inside your head (standard for headphones) to outside and in front of
  1885. the listener (standard for speakers).
  1886. Ported from SoX.
  1887. @section equalizer
  1888. Apply a two-pole peaking equalisation (EQ) filter. With this
  1889. filter, the signal-level at and around a selected frequency can
  1890. be increased or decreased, whilst (unlike bandpass and bandreject
  1891. filters) that at all other frequencies is unchanged.
  1892. In order to produce complex equalisation curves, this filter can
  1893. be given several times, each with a different central frequency.
  1894. The filter accepts the following options:
  1895. @table @option
  1896. @item frequency, f
  1897. Set the filter's central frequency in Hz.
  1898. @item width_type
  1899. Set method to specify band-width of filter.
  1900. @table @option
  1901. @item h
  1902. Hz
  1903. @item q
  1904. Q-Factor
  1905. @item o
  1906. octave
  1907. @item s
  1908. slope
  1909. @end table
  1910. @item width, w
  1911. Specify the band-width of a filter in width_type units.
  1912. @item gain, g
  1913. Set the required gain or attenuation in dB.
  1914. Beware of clipping when using a positive gain.
  1915. @end table
  1916. @subsection Examples
  1917. @itemize
  1918. @item
  1919. Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
  1920. @example
  1921. equalizer=f=1000:width_type=h:width=200:g=-10
  1922. @end example
  1923. @item
  1924. Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
  1925. @example
  1926. equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5
  1927. @end example
  1928. @end itemize
  1929. @section extrastereo
  1930. Linearly increases the difference between left and right channels which
  1931. adds some sort of "live" effect to playback.
  1932. The filter accepts the following options:
  1933. @table @option
  1934. @item m
  1935. Sets the difference coefficient (default: 2.5). 0.0 means mono sound
  1936. (average of both channels), with 1.0 sound will be unchanged, with
  1937. -1.0 left and right channels will be swapped.
  1938. @item c
  1939. Enable clipping. By default is enabled.
  1940. @end table
  1941. @section firequalizer
  1942. Apply FIR Equalization using arbitrary frequency response.
  1943. The filter accepts the following option:
  1944. @table @option
  1945. @item gain
  1946. Set gain curve equation (in dB). The expression can contain variables:
  1947. @table @option
  1948. @item f
  1949. the evaluated frequency
  1950. @item sr
  1951. sample rate
  1952. @item ch
  1953. channel number, set to 0 when multichannels evaluation is disabled
  1954. @item chid
  1955. channel id, see libavutil/channel_layout.h, set to the first channel id when
  1956. multichannels evaluation is disabled
  1957. @item chs
  1958. number of channels
  1959. @item chlayout
  1960. channel_layout, see libavutil/channel_layout.h
  1961. @end table
  1962. and functions:
  1963. @table @option
  1964. @item gain_interpolate(f)
  1965. interpolate gain on frequency f based on gain_entry
  1966. @end table
  1967. This option is also available as command. Default is @code{gain_interpolate(f)}.
  1968. @item gain_entry
  1969. Set gain entry for gain_interpolate function. The expression can
  1970. contain functions:
  1971. @table @option
  1972. @item entry(f, g)
  1973. store gain entry at frequency f with value g
  1974. @end table
  1975. This option is also available as command.
  1976. @item delay
  1977. Set filter delay in seconds. Higher value means more accurate.
  1978. Default is @code{0.01}.
  1979. @item accuracy
  1980. Set filter accuracy in Hz. Lower value means more accurate.
  1981. Default is @code{5}.
  1982. @item wfunc
  1983. Set window function. Acceptable values are:
  1984. @table @option
  1985. @item rectangular
  1986. rectangular window, useful when gain curve is already smooth
  1987. @item hann
  1988. hann window (default)
  1989. @item hamming
  1990. hamming window
  1991. @item blackman
  1992. blackman window
  1993. @item nuttall3
  1994. 3-terms continuous 1st derivative nuttall window
  1995. @item mnuttall3
  1996. minimum 3-terms discontinuous nuttall window
  1997. @item nuttall
  1998. 4-terms continuous 1st derivative nuttall window
  1999. @item bnuttall
  2000. minimum 4-terms discontinuous nuttall (blackman-nuttall) window
  2001. @item bharris
  2002. blackman-harris window
  2003. @end table
  2004. @item fixed
  2005. If enabled, use fixed number of audio samples. This improves speed when
  2006. filtering with large delay. Default is disabled.
  2007. @item multi
  2008. Enable multichannels evaluation on gain. Default is disabled.
  2009. @item zero_phase
  2010. Enable zero phase mode by substracting timestamp to compensate delay.
  2011. Default is disabled.
  2012. @end table
  2013. @subsection Examples
  2014. @itemize
  2015. @item
  2016. lowpass at 1000 Hz:
  2017. @example
  2018. firequalizer=gain='if(lt(f,1000), 0, -INF)'
  2019. @end example
  2020. @item
  2021. lowpass at 1000 Hz with gain_entry:
  2022. @example
  2023. firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
  2024. @end example
  2025. @item
  2026. custom equalization:
  2027. @example
  2028. firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
  2029. @end example
  2030. @item
  2031. higher delay with zero phase to compensate delay:
  2032. @example
  2033. firequalizer=delay=0.1:fixed=on:zero_phase=on
  2034. @end example
  2035. @item
  2036. lowpass on left channel, highpass on right channel:
  2037. @example
  2038. firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
  2039. :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
  2040. @end example
  2041. @end itemize
  2042. @section flanger
  2043. Apply a flanging effect to the audio.
  2044. The filter accepts the following options:
  2045. @table @option
  2046. @item delay
  2047. Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
  2048. @item depth
  2049. Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2.
  2050. @item regen
  2051. Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
  2052. Default value is 0.
  2053. @item width
  2054. Set percentage of delayed signal mixed with original. Range from 0 to 100.
  2055. Default value is 71.
  2056. @item speed
  2057. Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
  2058. @item shape
  2059. Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
  2060. Default value is @var{sinusoidal}.
  2061. @item phase
  2062. Set swept wave percentage-shift for multi channel. Range from 0 to 100.
  2063. Default value is 25.
  2064. @item interp
  2065. Set delay-line interpolation, @var{linear} or @var{quadratic}.
  2066. Default is @var{linear}.
  2067. @end table
  2068. @section hdcd
  2069. Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
  2070. embedded HDCD codes is expanded into a 20-bit PCM stream.
  2071. The filter supports the Peak Extend and Low-level Gain Adjustment features
  2072. of HDCD, and detects the Transient Filter flag.
  2073. @example
  2074. ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
  2075. @end example
  2076. When using the filter with wav, note the default encoding for wav is 16-bit,
  2077. so the resulting 20-bit stream will be truncated back to 16-bit. Use something
  2078. like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
  2079. @example
  2080. ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
  2081. ffmpeg -i HDCD16.wav -af hdcd -acodec pcm_s24le OUT24.wav
  2082. @end example
  2083. The filter accepts the following options:
  2084. @table @option
  2085. @item disable_autoconvert
  2086. Disable any automatic format conversion or resampling in the filter graph.
  2087. @item process_stereo
  2088. Process the stereo channels together. If target_gain does not match between
  2089. channels, consider it invalid and use the last valid target_gain.
  2090. @item cdt_ms
  2091. Set the code detect timer period in ms.
  2092. @item force_pe
  2093. Always extend peaks above -3dBFS even if PE isn't signaled.
  2094. @item analyze_mode
  2095. Replace audio with a solid tone and adjust the amplitude to signal some
  2096. specific aspect of the decoding process. The output file can be loaded in
  2097. an audio editor alongside the original to aid analysis.
  2098. @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
  2099. Modes are:
  2100. @table @samp
  2101. @item 0, off
  2102. Disabled
  2103. @item 1, lle
  2104. Gain adjustment level at each sample
  2105. @item 2, pe
  2106. Samples where peak extend occurs
  2107. @item 3, cdt
  2108. Samples where the code detect timer is active
  2109. @item 4, tgm
  2110. Samples where the target gain does not match between channels
  2111. @end table
  2112. @end table
  2113. @section highpass
  2114. Apply a high-pass filter with 3dB point frequency.
  2115. The filter can be either single-pole, or double-pole (the default).
  2116. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  2117. The filter accepts the following options:
  2118. @table @option
  2119. @item frequency, f
  2120. Set frequency in Hz. Default is 3000.
  2121. @item poles, p
  2122. Set number of poles. Default is 2.
  2123. @item width_type
  2124. Set method to specify band-width of filter.
  2125. @table @option
  2126. @item h
  2127. Hz
  2128. @item q
  2129. Q-Factor
  2130. @item o
  2131. octave
  2132. @item s
  2133. slope
  2134. @end table
  2135. @item width, w
  2136. Specify the band-width of a filter in width_type units.
  2137. Applies only to double-pole filter.
  2138. The default is 0.707q and gives a Butterworth response.
  2139. @end table
  2140. @section join
  2141. Join multiple input streams into one multi-channel stream.
  2142. It accepts the following parameters:
  2143. @table @option
  2144. @item inputs
  2145. The number of input streams. It defaults to 2.
  2146. @item channel_layout
  2147. The desired output channel layout. It defaults to stereo.
  2148. @item map
  2149. Map channels from inputs to output. The argument is a '|'-separated list of
  2150. mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
  2151. form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
  2152. can be either the name of the input channel (e.g. FL for front left) or its
  2153. index in the specified input stream. @var{out_channel} is the name of the output
  2154. channel.
  2155. @end table
  2156. The filter will attempt to guess the mappings when they are not specified
  2157. explicitly. It does so by first trying to find an unused matching input channel
  2158. and if that fails it picks the first unused input channel.
  2159. Join 3 inputs (with properly set channel layouts):
  2160. @example
  2161. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
  2162. @end example
  2163. Build a 5.1 output from 6 single-channel streams:
  2164. @example
  2165. ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
  2166. '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'
  2167. out
  2168. @end example
  2169. @section ladspa
  2170. Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
  2171. To enable compilation of this filter you need to configure FFmpeg with
  2172. @code{--enable-ladspa}.
  2173. @table @option
  2174. @item file, f
  2175. Specifies the name of LADSPA plugin library to load. If the environment
  2176. variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
  2177. each one of the directories specified by the colon separated list in
  2178. @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
  2179. this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
  2180. @file{/usr/lib/ladspa/}.
  2181. @item plugin, p
  2182. Specifies the plugin within the library. Some libraries contain only
  2183. one plugin, but others contain many of them. If this is not set filter
  2184. will list all available plugins within the specified library.
  2185. @item controls, c
  2186. Set the '|' separated list of controls which are zero or more floating point
  2187. values that determine the behavior of the loaded plugin (for example delay,
  2188. threshold or gain).
  2189. Controls need to be defined using the following syntax:
  2190. c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
  2191. @var{valuei} is the value set on the @var{i}-th control.
  2192. Alternatively they can be also defined using the following syntax:
  2193. @var{value0}|@var{value1}|@var{value2}|..., where
  2194. @var{valuei} is the value set on the @var{i}-th control.
  2195. If @option{controls} is set to @code{help}, all available controls and
  2196. their valid ranges are printed.
  2197. @item sample_rate, s
  2198. Specify the sample rate, default to 44100. Only used if plugin have
  2199. zero inputs.
  2200. @item nb_samples, n
  2201. Set the number of samples per channel per each output frame, default
  2202. is 1024. Only used if plugin have zero inputs.
  2203. @item duration, d
  2204. Set the minimum duration of the sourced audio. See
  2205. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  2206. for the accepted syntax.
  2207. Note that the resulting duration may be greater than the specified duration,
  2208. as the generated audio is always cut at the end of a complete frame.
  2209. If not specified, or the expressed duration is negative, the audio is
  2210. supposed to be generated forever.
  2211. Only used if plugin have zero inputs.
  2212. @end table
  2213. @subsection Examples
  2214. @itemize
  2215. @item
  2216. List all available plugins within amp (LADSPA example plugin) library:
  2217. @example
  2218. ladspa=file=amp
  2219. @end example
  2220. @item
  2221. List all available controls and their valid ranges for @code{vcf_notch}
  2222. plugin from @code{VCF} library:
  2223. @example
  2224. ladspa=f=vcf:p=vcf_notch:c=help
  2225. @end example
  2226. @item
  2227. Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
  2228. plugin library:
  2229. @example
  2230. ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
  2231. @end example
  2232. @item
  2233. Add reverberation to the audio using TAP-plugins
  2234. (Tom's Audio Processing plugins):
  2235. @example
  2236. ladspa=file=tap_reverb:tap_reverb
  2237. @end example
  2238. @item
  2239. Generate white noise, with 0.2 amplitude:
  2240. @example
  2241. ladspa=file=cmt:noise_source_white:c=c0=.2
  2242. @end example
  2243. @item
  2244. Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
  2245. @code{C* Audio Plugin Suite} (CAPS) library:
  2246. @example
  2247. ladspa=file=caps:Click:c=c1=20'
  2248. @end example
  2249. @item
  2250. Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
  2251. @example
  2252. ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
  2253. @end example
  2254. @item
  2255. Increase volume by 20dB using fast lookahead limiter from Steve Harris
  2256. @code{SWH Plugins} collection:
  2257. @example
  2258. ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
  2259. @end example
  2260. @item
  2261. Attenuate low frequencies using Multiband EQ from Steve Harris
  2262. @code{SWH Plugins} collection:
  2263. @example
  2264. ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
  2265. @end example
  2266. @end itemize
  2267. @subsection Commands
  2268. This filter supports the following commands:
  2269. @table @option
  2270. @item cN
  2271. Modify the @var{N}-th control value.
  2272. If the specified value is not valid, it is ignored and prior one is kept.
  2273. @end table
  2274. @section loudnorm
  2275. EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
  2276. Support for both single pass (livestreams, files) and double pass (files) modes.
  2277. This algorithm can target IL, LRA, and maximum true peak.
  2278. To enable compilation of this filter you need to configure FFmpeg with
  2279. @code{--enable-libebur128}.
  2280. The filter accepts the following options:
  2281. @table @option
  2282. @item I, i
  2283. Set integrated loudness target.
  2284. Range is -70.0 - -5.0. Default value is -24.0.
  2285. @item LRA, lra
  2286. Set loudness range target.
  2287. Range is 1.0 - 20.0. Default value is 7.0.
  2288. @item TP, tp
  2289. Set maximum true peak.
  2290. Range is -9.0 - +0.0. Default value is -2.0.
  2291. @item measured_I, measured_i
  2292. Measured IL of input file.
  2293. Range is -99.0 - +0.0.
  2294. @item measured_LRA, measured_lra
  2295. Measured LRA of input file.
  2296. Range is 0.0 - 99.0.
  2297. @item measured_TP, measured_tp
  2298. Measured true peak of input file.
  2299. Range is -99.0 - +99.0.
  2300. @item measured_thresh
  2301. Measured threshold of input file.
  2302. Range is -99.0 - +0.0.
  2303. @item offset
  2304. Set offset gain. Gain is applied before the true-peak limiter.
  2305. Range is -99.0 - +99.0. Default is +0.0.
  2306. @item linear
  2307. Normalize linearly if possible.
  2308. measured_I, measured_LRA, measured_TP, and measured_thresh must also
  2309. to be specified in order to use this mode.
  2310. Options are true or false. Default is true.
  2311. @item dual_mono
  2312. Treat mono input files as "dual-mono". If a mono file is intended for playback
  2313. on a stereo system, its EBU R128 measurement will be perceptually incorrect.
  2314. If set to @code{true}, this option will compensate for this effect.
  2315. Multi-channel input files are not affected by this option.
  2316. Options are true or false. Default is false.
  2317. @item print_format
  2318. Set print format for stats. Options are summary, json, or none.
  2319. Default value is none.
  2320. @end table
  2321. @section lowpass
  2322. Apply a low-pass filter with 3dB point frequency.
  2323. The filter can be either single-pole or double-pole (the default).
  2324. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  2325. The filter accepts the following options:
  2326. @table @option
  2327. @item frequency, f
  2328. Set frequency in Hz. Default is 500.
  2329. @item poles, p
  2330. Set number of poles. Default is 2.
  2331. @item width_type
  2332. Set method to specify band-width of filter.
  2333. @table @option
  2334. @item h
  2335. Hz
  2336. @item q
  2337. Q-Factor
  2338. @item o
  2339. octave
  2340. @item s
  2341. slope
  2342. @end table
  2343. @item width, w
  2344. Specify the band-width of a filter in width_type units.
  2345. Applies only to double-pole filter.
  2346. The default is 0.707q and gives a Butterworth response.
  2347. @end table
  2348. @anchor{pan}
  2349. @section pan
  2350. Mix channels with specific gain levels. The filter accepts the output
  2351. channel layout followed by a set of channels definitions.
  2352. This filter is also designed to efficiently remap the channels of an audio
  2353. stream.
  2354. The filter accepts parameters of the form:
  2355. "@var{l}|@var{outdef}|@var{outdef}|..."
  2356. @table @option
  2357. @item l
  2358. output channel layout or number of channels
  2359. @item outdef
  2360. output channel specification, of the form:
  2361. "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
  2362. @item out_name
  2363. output channel to define, either a channel name (FL, FR, etc.) or a channel
  2364. number (c0, c1, etc.)
  2365. @item gain
  2366. multiplicative coefficient for the channel, 1 leaving the volume unchanged
  2367. @item in_name
  2368. input channel to use, see out_name for details; it is not possible to mix
  2369. named and numbered input channels
  2370. @end table
  2371. If the `=' in a channel specification is replaced by `<', then the gains for
  2372. that specification will be renormalized so that the total is 1, thus
  2373. avoiding clipping noise.
  2374. @subsection Mixing examples
  2375. For example, if you want to down-mix from stereo to mono, but with a bigger
  2376. factor for the left channel:
  2377. @example
  2378. pan=1c|c0=0.9*c0+0.1*c1
  2379. @end example
  2380. A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
  2381. 7-channels surround:
  2382. @example
  2383. pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
  2384. @end example
  2385. Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
  2386. that should be preferred (see "-ac" option) unless you have very specific
  2387. needs.
  2388. @subsection Remapping examples
  2389. The channel remapping will be effective if, and only if:
  2390. @itemize
  2391. @item gain coefficients are zeroes or ones,
  2392. @item only one input per channel output,
  2393. @end itemize
  2394. If all these conditions are satisfied, the filter will notify the user ("Pure
  2395. channel mapping detected"), and use an optimized and lossless method to do the
  2396. remapping.
  2397. For example, if you have a 5.1 source and want a stereo audio stream by
  2398. dropping the extra channels:
  2399. @example
  2400. pan="stereo| c0=FL | c1=FR"
  2401. @end example
  2402. Given the same source, you can also switch front left and front right channels
  2403. and keep the input channel layout:
  2404. @example
  2405. pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
  2406. @end example
  2407. If the input is a stereo audio stream, you can mute the front left channel (and
  2408. still keep the stereo channel layout) with:
  2409. @example
  2410. pan="stereo|c1=c1"
  2411. @end example
  2412. Still with a stereo audio stream input, you can copy the right channel in both
  2413. front left and right:
  2414. @example
  2415. pan="stereo| c0=FR | c1=FR"
  2416. @end example
  2417. @section replaygain
  2418. ReplayGain scanner filter. This filter takes an audio stream as an input and
  2419. outputs it unchanged.
  2420. At end of filtering it displays @code{track_gain} and @code{track_peak}.
  2421. @section resample
  2422. Convert the audio sample format, sample rate and channel layout. It is
  2423. not meant to be used directly.
  2424. @section rubberband
  2425. Apply time-stretching and pitch-shifting with librubberband.
  2426. The filter accepts the following options:
  2427. @table @option
  2428. @item tempo
  2429. Set tempo scale factor.
  2430. @item pitch
  2431. Set pitch scale factor.
  2432. @item transients
  2433. Set transients detector.
  2434. Possible values are:
  2435. @table @var
  2436. @item crisp
  2437. @item mixed
  2438. @item smooth
  2439. @end table
  2440. @item detector
  2441. Set detector.
  2442. Possible values are:
  2443. @table @var
  2444. @item compound
  2445. @item percussive
  2446. @item soft
  2447. @end table
  2448. @item phase
  2449. Set phase.
  2450. Possible values are:
  2451. @table @var
  2452. @item laminar
  2453. @item independent
  2454. @end table
  2455. @item window
  2456. Set processing window size.
  2457. Possible values are:
  2458. @table @var
  2459. @item standard
  2460. @item short
  2461. @item long
  2462. @end table
  2463. @item smoothing
  2464. Set smoothing.
  2465. Possible values are:
  2466. @table @var
  2467. @item off
  2468. @item on
  2469. @end table
  2470. @item formant
  2471. Enable formant preservation when shift pitching.
  2472. Possible values are:
  2473. @table @var
  2474. @item shifted
  2475. @item preserved
  2476. @end table
  2477. @item pitchq
  2478. Set pitch quality.
  2479. Possible values are:
  2480. @table @var
  2481. @item quality
  2482. @item speed
  2483. @item consistency
  2484. @end table
  2485. @item channels
  2486. Set channels.
  2487. Possible values are:
  2488. @table @var
  2489. @item apart
  2490. @item together
  2491. @end table
  2492. @end table
  2493. @section sidechaincompress
  2494. This filter acts like normal compressor but has the ability to compress
  2495. detected signal using second input signal.
  2496. It needs two input streams and returns one output stream.
  2497. First input stream will be processed depending on second stream signal.
  2498. The filtered signal then can be filtered with other filters in later stages of
  2499. processing. See @ref{pan} and @ref{amerge} filter.
  2500. The filter accepts the following options:
  2501. @table @option
  2502. @item level_in
  2503. Set input gain. Default is 1. Range is between 0.015625 and 64.
  2504. @item threshold
  2505. If a signal of second stream raises above this level it will affect the gain
  2506. reduction of first stream.
  2507. By default is 0.125. Range is between 0.00097563 and 1.
  2508. @item ratio
  2509. Set a ratio about which the signal is reduced. 1:2 means that if the level
  2510. raised 4dB above the threshold, it will be only 2dB above after the reduction.
  2511. Default is 2. Range is between 1 and 20.
  2512. @item attack
  2513. Amount of milliseconds the signal has to rise above the threshold before gain
  2514. reduction starts. Default is 20. Range is between 0.01 and 2000.
  2515. @item release
  2516. Amount of milliseconds the signal has to fall below the threshold before
  2517. reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
  2518. @item makeup
  2519. Set the amount by how much signal will be amplified after processing.
  2520. Default is 2. Range is from 1 and 64.
  2521. @item knee
  2522. Curve the sharp knee around the threshold to enter gain reduction more softly.
  2523. Default is 2.82843. Range is between 1 and 8.
  2524. @item link
  2525. Choose if the @code{average} level between all channels of side-chain stream
  2526. or the louder(@code{maximum}) channel of side-chain stream affects the
  2527. reduction. Default is @code{average}.
  2528. @item detection
  2529. Should the exact signal be taken in case of @code{peak} or an RMS one in case
  2530. of @code{rms}. Default is @code{rms} which is mainly smoother.
  2531. @item level_sc
  2532. Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
  2533. @item mix
  2534. How much to use compressed signal in output. Default is 1.
  2535. Range is between 0 and 1.
  2536. @end table
  2537. @subsection Examples
  2538. @itemize
  2539. @item
  2540. Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
  2541. depending on the signal of 2nd input and later compressed signal to be
  2542. merged with 2nd input:
  2543. @example
  2544. ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
  2545. @end example
  2546. @end itemize
  2547. @section sidechaingate
  2548. A sidechain gate acts like a normal (wideband) gate but has the ability to
  2549. filter the detected signal before sending it to the gain reduction stage.
  2550. Normally a gate uses the full range signal to detect a level above the
  2551. threshold.
  2552. For example: If you cut all lower frequencies from your sidechain signal
  2553. the gate will decrease the volume of your track only if not enough highs
  2554. appear. With this technique you are able to reduce the resonation of a
  2555. natural drum or remove "rumbling" of muted strokes from a heavily distorted
  2556. guitar.
  2557. It needs two input streams and returns one output stream.
  2558. First input stream will be processed depending on second stream signal.
  2559. The filter accepts the following options:
  2560. @table @option
  2561. @item level_in
  2562. Set input level before filtering.
  2563. Default is 1. Allowed range is from 0.015625 to 64.
  2564. @item range
  2565. Set the level of gain reduction when the signal is below the threshold.
  2566. Default is 0.06125. Allowed range is from 0 to 1.
  2567. @item threshold
  2568. If a signal rises above this level the gain reduction is released.
  2569. Default is 0.125. Allowed range is from 0 to 1.
  2570. @item ratio
  2571. Set a ratio about which the signal is reduced.
  2572. Default is 2. Allowed range is from 1 to 9000.
  2573. @item attack
  2574. Amount of milliseconds the signal has to rise above the threshold before gain
  2575. reduction stops.
  2576. Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
  2577. @item release
  2578. Amount of milliseconds the signal has to fall below the threshold before the
  2579. reduction is increased again. Default is 250 milliseconds.
  2580. Allowed range is from 0.01 to 9000.
  2581. @item makeup
  2582. Set amount of amplification of signal after processing.
  2583. Default is 1. Allowed range is from 1 to 64.
  2584. @item knee
  2585. Curve the sharp knee around the threshold to enter gain reduction more softly.
  2586. Default is 2.828427125. Allowed range is from 1 to 8.
  2587. @item detection
  2588. Choose if exact signal should be taken for detection or an RMS like one.
  2589. Default is rms. Can be peak or rms.
  2590. @item link
  2591. Choose if the average level between all channels or the louder channel affects
  2592. the reduction.
  2593. Default is average. Can be average or maximum.
  2594. @item level_sc
  2595. Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
  2596. @end table
  2597. @section silencedetect
  2598. Detect silence in an audio stream.
  2599. This filter logs a message when it detects that the input audio volume is less
  2600. or equal to a noise tolerance value for a duration greater or equal to the
  2601. minimum detected noise duration.
  2602. The printed times and duration are expressed in seconds.
  2603. The filter accepts the following options:
  2604. @table @option
  2605. @item duration, d
  2606. Set silence duration until notification (default is 2 seconds).
  2607. @item noise, n
  2608. Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
  2609. specified value) or amplitude ratio. Default is -60dB, or 0.001.
  2610. @end table
  2611. @subsection Examples
  2612. @itemize
  2613. @item
  2614. Detect 5 seconds of silence with -50dB noise tolerance:
  2615. @example
  2616. silencedetect=n=-50dB:d=5
  2617. @end example
  2618. @item
  2619. Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
  2620. tolerance in @file{silence.mp3}:
  2621. @example
  2622. ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
  2623. @end example
  2624. @end itemize
  2625. @section silenceremove
  2626. Remove silence from the beginning, middle or end of the audio.
  2627. The filter accepts the following options:
  2628. @table @option
  2629. @item start_periods
  2630. This value is used to indicate if audio should be trimmed at beginning of
  2631. the audio. A value of zero indicates no silence should be trimmed from the
  2632. beginning. When specifying a non-zero value, it trims audio up until it
  2633. finds non-silence. Normally, when trimming silence from beginning of audio
  2634. the @var{start_periods} will be @code{1} but it can be increased to higher
  2635. values to trim all audio up to specific count of non-silence periods.
  2636. Default value is @code{0}.
  2637. @item start_duration
  2638. Specify the amount of time that non-silence must be detected before it stops
  2639. trimming audio. By increasing the duration, bursts of noises can be treated
  2640. as silence and trimmed off. Default value is @code{0}.
  2641. @item start_threshold
  2642. This indicates what sample value should be treated as silence. For digital
  2643. audio, a value of @code{0} may be fine but for audio recorded from analog,
  2644. you may wish to increase the value to account for background noise.
  2645. Can be specified in dB (in case "dB" is appended to the specified value)
  2646. or amplitude ratio. Default value is @code{0}.
  2647. @item stop_periods
  2648. Set the count for trimming silence from the end of audio.
  2649. To remove silence from the middle of a file, specify a @var{stop_periods}
  2650. that is negative. This value is then treated as a positive value and is
  2651. used to indicate the effect should restart processing as specified by
  2652. @var{start_periods}, making it suitable for removing periods of silence
  2653. in the middle of the audio.
  2654. Default value is @code{0}.
  2655. @item stop_duration
  2656. Specify a duration of silence that must exist before audio is not copied any
  2657. more. By specifying a higher duration, silence that is wanted can be left in
  2658. the audio.
  2659. Default value is @code{0}.
  2660. @item stop_threshold
  2661. This is the same as @option{start_threshold} but for trimming silence from
  2662. the end of audio.
  2663. Can be specified in dB (in case "dB" is appended to the specified value)
  2664. or amplitude ratio. Default value is @code{0}.
  2665. @item leave_silence
  2666. This indicate that @var{stop_duration} length of audio should be left intact
  2667. at the beginning of each period of silence.
  2668. For example, if you want to remove long pauses between words but do not want
  2669. to remove the pauses completely. Default value is @code{0}.
  2670. @item detection
  2671. Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
  2672. and works better with digital silence which is exactly 0.
  2673. Default value is @code{rms}.
  2674. @item window
  2675. Set ratio used to calculate size of window for detecting silence.
  2676. Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
  2677. @end table
  2678. @subsection Examples
  2679. @itemize
  2680. @item
  2681. The following example shows how this filter can be used to start a recording
  2682. that does not contain the delay at the start which usually occurs between
  2683. pressing the record button and the start of the performance:
  2684. @example
  2685. silenceremove=1:5:0.02
  2686. @end example
  2687. @item
  2688. Trim all silence encountered from beginning to end where there is more than 1
  2689. second of silence in audio:
  2690. @example
  2691. silenceremove=0:0:0:-1:1:-90dB
  2692. @end example
  2693. @end itemize
  2694. @section sofalizer
  2695. SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
  2696. loudspeakers around the user for binaural listening via headphones (audio
  2697. formats up to 9 channels supported).
  2698. The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
  2699. SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
  2700. Austrian Academy of Sciences.
  2701. To enable compilation of this filter you need to configure FFmpeg with
  2702. @code{--enable-netcdf}.
  2703. The filter accepts the following options:
  2704. @table @option
  2705. @item sofa
  2706. Set the SOFA file used for rendering.
  2707. @item gain
  2708. Set gain applied to audio. Value is in dB. Default is 0.
  2709. @item rotation
  2710. Set rotation of virtual loudspeakers in deg. Default is 0.
  2711. @item elevation
  2712. Set elevation of virtual speakers in deg. Default is 0.
  2713. @item radius
  2714. Set distance in meters between loudspeakers and the listener with near-field
  2715. HRTFs. Default is 1.
  2716. @item type
  2717. Set processing type. Can be @var{time} or @var{freq}. @var{time} is
  2718. processing audio in time domain which is slow.
  2719. @var{freq} is processing audio in frequency domain which is fast.
  2720. Default is @var{freq}.
  2721. @item speakers
  2722. Set custom positions of virtual loudspeakers. Syntax for this option is:
  2723. <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
  2724. Each virtual loudspeaker is described with short channel name following with
  2725. azimuth and elevation in degreees.
  2726. Each virtual loudspeaker description is separated by '|'.
  2727. For example to override front left and front right channel positions use:
  2728. 'speakers=FL 45 15|FR 345 15'.
  2729. Descriptions with unrecognised channel names are ignored.
  2730. @end table
  2731. @subsection Examples
  2732. @itemize
  2733. @item
  2734. Using ClubFritz6 sofa file:
  2735. @example
  2736. sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
  2737. @end example
  2738. @item
  2739. Using ClubFritz12 sofa file and bigger radius with small rotation:
  2740. @example
  2741. sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
  2742. @end example
  2743. @item
  2744. Similar as above but with custom speaker positions for front left, front right, rear left and rear right
  2745. and also with custom gain:
  2746. @example
  2747. "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|RL 135|RR 225:gain=28"
  2748. @end example
  2749. @end itemize
  2750. @section stereotools
  2751. This filter has some handy utilities to manage stereo signals, for converting
  2752. M/S stereo recordings to L/R signal while having control over the parameters
  2753. or spreading the stereo image of master track.
  2754. The filter accepts the following options:
  2755. @table @option
  2756. @item level_in
  2757. Set input level before filtering for both channels. Defaults is 1.
  2758. Allowed range is from 0.015625 to 64.
  2759. @item level_out
  2760. Set output level after filtering for both channels. Defaults is 1.
  2761. Allowed range is from 0.015625 to 64.
  2762. @item balance_in
  2763. Set input balance between both channels. Default is 0.
  2764. Allowed range is from -1 to 1.
  2765. @item balance_out
  2766. Set output balance between both channels. Default is 0.
  2767. Allowed range is from -1 to 1.
  2768. @item softclip
  2769. Enable softclipping. Results in analog distortion instead of harsh digital 0dB
  2770. clipping. Disabled by default.
  2771. @item mutel
  2772. Mute the left channel. Disabled by default.
  2773. @item muter
  2774. Mute the right channel. Disabled by default.
  2775. @item phasel
  2776. Change the phase of the left channel. Disabled by default.
  2777. @item phaser
  2778. Change the phase of the right channel. Disabled by default.
  2779. @item mode
  2780. Set stereo mode. Available values are:
  2781. @table @samp
  2782. @item lr>lr
  2783. Left/Right to Left/Right, this is default.
  2784. @item lr>ms
  2785. Left/Right to Mid/Side.
  2786. @item ms>lr
  2787. Mid/Side to Left/Right.
  2788. @item lr>ll
  2789. Left/Right to Left/Left.
  2790. @item lr>rr
  2791. Left/Right to Right/Right.
  2792. @item lr>l+r
  2793. Left/Right to Left + Right.
  2794. @item lr>rl
  2795. Left/Right to Right/Left.
  2796. @end table
  2797. @item slev
  2798. Set level of side signal. Default is 1.
  2799. Allowed range is from 0.015625 to 64.
  2800. @item sbal
  2801. Set balance of side signal. Default is 0.
  2802. Allowed range is from -1 to 1.
  2803. @item mlev
  2804. Set level of the middle signal. Default is 1.
  2805. Allowed range is from 0.015625 to 64.
  2806. @item mpan
  2807. Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
  2808. @item base
  2809. Set stereo base between mono and inversed channels. Default is 0.
  2810. Allowed range is from -1 to 1.
  2811. @item delay
  2812. Set delay in milliseconds how much to delay left from right channel and
  2813. vice versa. Default is 0. Allowed range is from -20 to 20.
  2814. @item sclevel
  2815. Set S/C level. Default is 1. Allowed range is from 1 to 100.
  2816. @item phase
  2817. Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
  2818. @end table
  2819. @subsection Examples
  2820. @itemize
  2821. @item
  2822. Apply karaoke like effect:
  2823. @example
  2824. stereotools=mlev=0.015625
  2825. @end example
  2826. @item
  2827. Convert M/S signal to L/R:
  2828. @example
  2829. "stereotools=mode=ms>lr"
  2830. @end example
  2831. @end itemize
  2832. @section stereowiden
  2833. This filter enhance the stereo effect by suppressing signal common to both
  2834. channels and by delaying the signal of left into right and vice versa,
  2835. thereby widening the stereo effect.
  2836. The filter accepts the following options:
  2837. @table @option
  2838. @item delay
  2839. Time in milliseconds of the delay of left signal into right and vice versa.
  2840. Default is 20 milliseconds.
  2841. @item feedback
  2842. Amount of gain in delayed signal into right and vice versa. Gives a delay
  2843. effect of left signal in right output and vice versa which gives widening
  2844. effect. Default is 0.3.
  2845. @item crossfeed
  2846. Cross feed of left into right with inverted phase. This helps in suppressing
  2847. the mono. If the value is 1 it will cancel all the signal common to both
  2848. channels. Default is 0.3.
  2849. @item drymix
  2850. Set level of input signal of original channel. Default is 0.8.
  2851. @end table
  2852. @section treble
  2853. Boost or cut treble (upper) frequencies of the audio using a two-pole
  2854. shelving filter with a response similar to that of a standard
  2855. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  2856. The filter accepts the following options:
  2857. @table @option
  2858. @item gain, g
  2859. Give the gain at whichever is the lower of ~22 kHz and the
  2860. Nyquist frequency. Its useful range is about -20 (for a large cut)
  2861. to +20 (for a large boost). Beware of clipping when using a positive gain.
  2862. @item frequency, f
  2863. Set the filter's central frequency and so can be used
  2864. to extend or reduce the frequency range to be boosted or cut.
  2865. The default value is @code{3000} Hz.
  2866. @item width_type
  2867. Set method to specify band-width of filter.
  2868. @table @option
  2869. @item h
  2870. Hz
  2871. @item q
  2872. Q-Factor
  2873. @item o
  2874. octave
  2875. @item s
  2876. slope
  2877. @end table
  2878. @item width, w
  2879. Determine how steep is the filter's shelf transition.
  2880. @end table
  2881. @section tremolo
  2882. Sinusoidal amplitude modulation.
  2883. The filter accepts the following options:
  2884. @table @option
  2885. @item f
  2886. Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
  2887. (20 Hz or lower) will result in a tremolo effect.
  2888. This filter may also be used as a ring modulator by specifying
  2889. a modulation frequency higher than 20 Hz.
  2890. Range is 0.1 - 20000.0. Default value is 5.0 Hz.
  2891. @item d
  2892. Depth of modulation as a percentage. Range is 0.0 - 1.0.
  2893. Default value is 0.5.
  2894. @end table
  2895. @section vibrato
  2896. Sinusoidal phase modulation.
  2897. The filter accepts the following options:
  2898. @table @option
  2899. @item f
  2900. Modulation frequency in Hertz.
  2901. Range is 0.1 - 20000.0. Default value is 5.0 Hz.
  2902. @item d
  2903. Depth of modulation as a percentage. Range is 0.0 - 1.0.
  2904. Default value is 0.5.
  2905. @end table
  2906. @section volume
  2907. Adjust the input audio volume.
  2908. It accepts the following parameters:
  2909. @table @option
  2910. @item volume
  2911. Set audio volume expression.
  2912. Output values are clipped to the maximum value.
  2913. The output audio volume is given by the relation:
  2914. @example
  2915. @var{output_volume} = @var{volume} * @var{input_volume}
  2916. @end example
  2917. The default value for @var{volume} is "1.0".
  2918. @item precision
  2919. This parameter represents the mathematical precision.
  2920. It determines which input sample formats will be allowed, which affects the
  2921. precision of the volume scaling.
  2922. @table @option
  2923. @item fixed
  2924. 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
  2925. @item float
  2926. 32-bit floating-point; this limits input sample format to FLT. (default)
  2927. @item double
  2928. 64-bit floating-point; this limits input sample format to DBL.
  2929. @end table
  2930. @item replaygain
  2931. Choose the behaviour on encountering ReplayGain side data in input frames.
  2932. @table @option
  2933. @item drop
  2934. Remove ReplayGain side data, ignoring its contents (the default).
  2935. @item ignore
  2936. Ignore ReplayGain side data, but leave it in the frame.
  2937. @item track
  2938. Prefer the track gain, if present.
  2939. @item album
  2940. Prefer the album gain, if present.
  2941. @end table
  2942. @item replaygain_preamp
  2943. Pre-amplification gain in dB to apply to the selected replaygain gain.
  2944. Default value for @var{replaygain_preamp} is 0.0.
  2945. @item eval
  2946. Set when the volume expression is evaluated.
  2947. It accepts the following values:
  2948. @table @samp
  2949. @item once
  2950. only evaluate expression once during the filter initialization, or
  2951. when the @samp{volume} command is sent
  2952. @item frame
  2953. evaluate expression for each incoming frame
  2954. @end table
  2955. Default value is @samp{once}.
  2956. @end table
  2957. The volume expression can contain the following parameters.
  2958. @table @option
  2959. @item n
  2960. frame number (starting at zero)
  2961. @item nb_channels
  2962. number of channels
  2963. @item nb_consumed_samples
  2964. number of samples consumed by the filter
  2965. @item nb_samples
  2966. number of samples in the current frame
  2967. @item pos
  2968. original frame position in the file
  2969. @item pts
  2970. frame PTS
  2971. @item sample_rate
  2972. sample rate
  2973. @item startpts
  2974. PTS at start of stream
  2975. @item startt
  2976. time at start of stream
  2977. @item t
  2978. frame time
  2979. @item tb
  2980. timestamp timebase
  2981. @item volume
  2982. last set volume value
  2983. @end table
  2984. Note that when @option{eval} is set to @samp{once} only the
  2985. @var{sample_rate} and @var{tb} variables are available, all other
  2986. variables will evaluate to NAN.
  2987. @subsection Commands
  2988. This filter supports the following commands:
  2989. @table @option
  2990. @item volume
  2991. Modify the volume expression.
  2992. The command accepts the same syntax of the corresponding option.
  2993. If the specified expression is not valid, it is kept at its current
  2994. value.
  2995. @item replaygain_noclip
  2996. Prevent clipping by limiting the gain applied.
  2997. Default value for @var{replaygain_noclip} is 1.
  2998. @end table
  2999. @subsection Examples
  3000. @itemize
  3001. @item
  3002. Halve the input audio volume:
  3003. @example
  3004. volume=volume=0.5
  3005. volume=volume=1/2
  3006. volume=volume=-6.0206dB
  3007. @end example
  3008. In all the above example the named key for @option{volume} can be
  3009. omitted, for example like in:
  3010. @example
  3011. volume=0.5
  3012. @end example
  3013. @item
  3014. Increase input audio power by 6 decibels using fixed-point precision:
  3015. @example
  3016. volume=volume=6dB:precision=fixed
  3017. @end example
  3018. @item
  3019. Fade volume after time 10 with an annihilation period of 5 seconds:
  3020. @example
  3021. volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
  3022. @end example
  3023. @end itemize
  3024. @section volumedetect
  3025. Detect the volume of the input video.
  3026. The filter has no parameters. The input is not modified. Statistics about
  3027. the volume will be printed in the log when the input stream end is reached.
  3028. In particular it will show the mean volume (root mean square), maximum
  3029. volume (on a per-sample basis), and the beginning of a histogram of the
  3030. registered volume values (from the maximum value to a cumulated 1/1000 of
  3031. the samples).
  3032. All volumes are in decibels relative to the maximum PCM value.
  3033. @subsection Examples
  3034. Here is an excerpt of the output:
  3035. @example
  3036. [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
  3037. [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
  3038. [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
  3039. [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
  3040. [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
  3041. [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
  3042. [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
  3043. [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
  3044. [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
  3045. @end example
  3046. It means that:
  3047. @itemize
  3048. @item
  3049. The mean square energy is approximately -27 dB, or 10^-2.7.
  3050. @item
  3051. The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
  3052. @item
  3053. There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
  3054. @end itemize
  3055. In other words, raising the volume by +4 dB does not cause any clipping,
  3056. raising it by +5 dB causes clipping for 6 samples, etc.
  3057. @c man end AUDIO FILTERS
  3058. @chapter Audio Sources
  3059. @c man begin AUDIO SOURCES
  3060. Below is a description of the currently available audio sources.
  3061. @section abuffer
  3062. Buffer audio frames, and make them available to the filter chain.
  3063. This source is mainly intended for a programmatic use, in particular
  3064. through the interface defined in @file{libavfilter/asrc_abuffer.h}.
  3065. It accepts the following parameters:
  3066. @table @option
  3067. @item time_base
  3068. The timebase which will be used for timestamps of submitted frames. It must be
  3069. either a floating-point number or in @var{numerator}/@var{denominator} form.
  3070. @item sample_rate
  3071. The sample rate of the incoming audio buffers.
  3072. @item sample_fmt
  3073. The sample format of the incoming audio buffers.
  3074. Either a sample format name or its corresponding integer representation from
  3075. the enum AVSampleFormat in @file{libavutil/samplefmt.h}
  3076. @item channel_layout
  3077. The channel layout of the incoming audio buffers.
  3078. Either a channel layout name from channel_layout_map in
  3079. @file{libavutil/channel_layout.c} or its corresponding integer representation
  3080. from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
  3081. @item channels
  3082. The number of channels of the incoming audio buffers.
  3083. If both @var{channels} and @var{channel_layout} are specified, then they
  3084. must be consistent.
  3085. @end table
  3086. @subsection Examples
  3087. @example
  3088. abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
  3089. @end example
  3090. will instruct the source to accept planar 16bit signed stereo at 44100Hz.
  3091. Since the sample format with name "s16p" corresponds to the number
  3092. 6 and the "stereo" channel layout corresponds to the value 0x3, this is
  3093. equivalent to:
  3094. @example
  3095. abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
  3096. @end example
  3097. @section aevalsrc
  3098. Generate an audio signal specified by an expression.
  3099. This source accepts in input one or more expressions (one for each
  3100. channel), which are evaluated and used to generate a corresponding
  3101. audio signal.
  3102. This source accepts the following options:
  3103. @table @option
  3104. @item exprs
  3105. Set the '|'-separated expressions list for each separate channel. In case the
  3106. @option{channel_layout} option is not specified, the selected channel layout
  3107. depends on the number of provided expressions. Otherwise the last
  3108. specified expression is applied to the remaining output channels.
  3109. @item channel_layout, c
  3110. Set the channel layout. The number of channels in the specified layout
  3111. must be equal to the number of specified expressions.
  3112. @item duration, d
  3113. Set the minimum duration of the sourced audio. See
  3114. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  3115. for the accepted syntax.
  3116. Note that the resulting duration may be greater than the specified
  3117. duration, as the generated audio is always cut at the end of a
  3118. complete frame.
  3119. If not specified, or the expressed duration is negative, the audio is
  3120. supposed to be generated forever.
  3121. @item nb_samples, n
  3122. Set the number of samples per channel per each output frame,
  3123. default to 1024.
  3124. @item sample_rate, s
  3125. Specify the sample rate, default to 44100.
  3126. @end table
  3127. Each expression in @var{exprs} can contain the following constants:
  3128. @table @option
  3129. @item n
  3130. number of the evaluated sample, starting from 0
  3131. @item t
  3132. time of the evaluated sample expressed in seconds, starting from 0
  3133. @item s
  3134. sample rate
  3135. @end table
  3136. @subsection Examples
  3137. @itemize
  3138. @item
  3139. Generate silence:
  3140. @example
  3141. aevalsrc=0
  3142. @end example
  3143. @item
  3144. Generate a sin signal with frequency of 440 Hz, set sample rate to
  3145. 8000 Hz:
  3146. @example
  3147. aevalsrc="sin(440*2*PI*t):s=8000"
  3148. @end example
  3149. @item
  3150. Generate a two channels signal, specify the channel layout (Front
  3151. Center + Back Center) explicitly:
  3152. @example
  3153. aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
  3154. @end example
  3155. @item
  3156. Generate white noise:
  3157. @example
  3158. aevalsrc="-2+random(0)"
  3159. @end example
  3160. @item
  3161. Generate an amplitude modulated signal:
  3162. @example
  3163. aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
  3164. @end example
  3165. @item
  3166. Generate 2.5 Hz binaural beats on a 360 Hz carrier:
  3167. @example
  3168. aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
  3169. @end example
  3170. @end itemize
  3171. @section anullsrc
  3172. The null audio source, return unprocessed audio frames. It is mainly useful
  3173. as a template and to be employed in analysis / debugging tools, or as
  3174. the source for filters which ignore the input data (for example the sox
  3175. synth filter).
  3176. This source accepts the following options:
  3177. @table @option
  3178. @item channel_layout, cl
  3179. Specifies the channel layout, and can be either an integer or a string
  3180. representing a channel layout. The default value of @var{channel_layout}
  3181. is "stereo".
  3182. Check the channel_layout_map definition in
  3183. @file{libavutil/channel_layout.c} for the mapping between strings and
  3184. channel layout values.
  3185. @item sample_rate, r
  3186. Specifies the sample rate, and defaults to 44100.
  3187. @item nb_samples, n
  3188. Set the number of samples per requested frames.
  3189. @end table
  3190. @subsection Examples
  3191. @itemize
  3192. @item
  3193. Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
  3194. @example
  3195. anullsrc=r=48000:cl=4
  3196. @end example
  3197. @item
  3198. Do the same operation with a more obvious syntax:
  3199. @example
  3200. anullsrc=r=48000:cl=mono
  3201. @end example
  3202. @end itemize
  3203. All the parameters need to be explicitly defined.
  3204. @section flite
  3205. Synthesize a voice utterance using the libflite library.
  3206. To enable compilation of this filter you need to configure FFmpeg with
  3207. @code{--enable-libflite}.
  3208. Note that the flite library is not thread-safe.
  3209. The filter accepts the following options:
  3210. @table @option
  3211. @item list_voices
  3212. If set to 1, list the names of the available voices and exit
  3213. immediately. Default value is 0.
  3214. @item nb_samples, n
  3215. Set the maximum number of samples per frame. Default value is 512.
  3216. @item textfile
  3217. Set the filename containing the text to speak.
  3218. @item text
  3219. Set the text to speak.
  3220. @item voice, v
  3221. Set the voice to use for the speech synthesis. Default value is
  3222. @code{kal}. See also the @var{list_voices} option.
  3223. @end table
  3224. @subsection Examples
  3225. @itemize
  3226. @item
  3227. Read from file @file{speech.txt}, and synthesize the text using the
  3228. standard flite voice:
  3229. @example
  3230. flite=textfile=speech.txt
  3231. @end example
  3232. @item
  3233. Read the specified text selecting the @code{slt} voice:
  3234. @example
  3235. flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  3236. @end example
  3237. @item
  3238. Input text to ffmpeg:
  3239. @example
  3240. ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  3241. @end example
  3242. @item
  3243. Make @file{ffplay} speak the specified text, using @code{flite} and
  3244. the @code{lavfi} device:
  3245. @example
  3246. ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
  3247. @end example
  3248. @end itemize
  3249. For more information about libflite, check:
  3250. @url{http://www.speech.cs.cmu.edu/flite/}
  3251. @section anoisesrc
  3252. Generate a noise audio signal.
  3253. The filter accepts the following options:
  3254. @table @option
  3255. @item sample_rate, r
  3256. Specify the sample rate. Default value is 48000 Hz.
  3257. @item amplitude, a
  3258. Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
  3259. is 1.0.
  3260. @item duration, d
  3261. Specify the duration of the generated audio stream. Not specifying this option
  3262. results in noise with an infinite length.
  3263. @item color, colour, c
  3264. Specify the color of noise. Available noise colors are white, pink, and brown.
  3265. Default color is white.
  3266. @item seed, s
  3267. Specify a value used to seed the PRNG.
  3268. @item nb_samples, n
  3269. Set the number of samples per each output frame, default is 1024.
  3270. @end table
  3271. @subsection Examples
  3272. @itemize
  3273. @item
  3274. Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
  3275. @example
  3276. anoisesrc=d=60:c=pink:r=44100:a=0.5
  3277. @end example
  3278. @end itemize
  3279. @section sine
  3280. Generate an audio signal made of a sine wave with amplitude 1/8.
  3281. The audio signal is bit-exact.
  3282. The filter accepts the following options:
  3283. @table @option
  3284. @item frequency, f
  3285. Set the carrier frequency. Default is 440 Hz.
  3286. @item beep_factor, b
  3287. Enable a periodic beep every second with frequency @var{beep_factor} times
  3288. the carrier frequency. Default is 0, meaning the beep is disabled.
  3289. @item sample_rate, r
  3290. Specify the sample rate, default is 44100.
  3291. @item duration, d
  3292. Specify the duration of the generated audio stream.
  3293. @item samples_per_frame
  3294. Set the number of samples per output frame.
  3295. The expression can contain the following constants:
  3296. @table @option
  3297. @item n
  3298. The (sequential) number of the output audio frame, starting from 0.
  3299. @item pts
  3300. The PTS (Presentation TimeStamp) of the output audio frame,
  3301. expressed in @var{TB} units.
  3302. @item t
  3303. The PTS of the output audio frame, expressed in seconds.
  3304. @item TB
  3305. The timebase of the output audio frames.
  3306. @end table
  3307. Default is @code{1024}.
  3308. @end table
  3309. @subsection Examples
  3310. @itemize
  3311. @item
  3312. Generate a simple 440 Hz sine wave:
  3313. @example
  3314. sine
  3315. @end example
  3316. @item
  3317. Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
  3318. @example
  3319. sine=220:4:d=5
  3320. sine=f=220:b=4:d=5
  3321. sine=frequency=220:beep_factor=4:duration=5
  3322. @end example
  3323. @item
  3324. Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
  3325. pattern:
  3326. @example
  3327. sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
  3328. @end example
  3329. @end itemize
  3330. @c man end AUDIO SOURCES
  3331. @chapter Audio Sinks
  3332. @c man begin AUDIO SINKS
  3333. Below is a description of the currently available audio sinks.
  3334. @section abuffersink
  3335. Buffer audio frames, and make them available to the end of filter chain.
  3336. This sink is mainly intended for programmatic use, in particular
  3337. through the interface defined in @file{libavfilter/buffersink.h}
  3338. or the options system.
  3339. It accepts a pointer to an AVABufferSinkContext structure, which
  3340. defines the incoming buffers' formats, to be passed as the opaque
  3341. parameter to @code{avfilter_init_filter} for initialization.
  3342. @section anullsink
  3343. Null audio sink; do absolutely nothing with the input audio. It is
  3344. mainly useful as a template and for use in analysis / debugging
  3345. tools.
  3346. @c man end AUDIO SINKS
  3347. @chapter Video Filters
  3348. @c man begin VIDEO FILTERS
  3349. When you configure your FFmpeg build, you can disable any of the
  3350. existing filters using @code{--disable-filters}.
  3351. The configure output will show the video filters included in your
  3352. build.
  3353. Below is a description of the currently available video filters.
  3354. @section alphaextract
  3355. Extract the alpha component from the input as a grayscale video. This
  3356. is especially useful with the @var{alphamerge} filter.
  3357. @section alphamerge
  3358. Add or replace the alpha component of the primary input with the
  3359. grayscale value of a second input. This is intended for use with
  3360. @var{alphaextract} to allow the transmission or storage of frame
  3361. sequences that have alpha in a format that doesn't support an alpha
  3362. channel.
  3363. For example, to reconstruct full frames from a normal YUV-encoded video
  3364. and a separate video created with @var{alphaextract}, you might use:
  3365. @example
  3366. movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
  3367. @end example
  3368. Since this filter is designed for reconstruction, it operates on frame
  3369. sequences without considering timestamps, and terminates when either
  3370. input reaches end of stream. This will cause problems if your encoding
  3371. pipeline drops frames. If you're trying to apply an image as an
  3372. overlay to a video stream, consider the @var{overlay} filter instead.
  3373. @section ass
  3374. Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
  3375. and libavformat to work. On the other hand, it is limited to ASS (Advanced
  3376. Substation Alpha) subtitles files.
  3377. This filter accepts the following option in addition to the common options from
  3378. the @ref{subtitles} filter:
  3379. @table @option
  3380. @item shaping
  3381. Set the shaping engine
  3382. Available values are:
  3383. @table @samp
  3384. @item auto
  3385. The default libass shaping engine, which is the best available.
  3386. @item simple
  3387. Fast, font-agnostic shaper that can do only substitutions
  3388. @item complex
  3389. Slower shaper using OpenType for substitutions and positioning
  3390. @end table
  3391. The default is @code{auto}.
  3392. @end table
  3393. @section atadenoise
  3394. Apply an Adaptive Temporal Averaging Denoiser to the video input.
  3395. The filter accepts the following options:
  3396. @table @option
  3397. @item 0a
  3398. Set threshold A for 1st plane. Default is 0.02.
  3399. Valid range is 0 to 0.3.
  3400. @item 0b
  3401. Set threshold B for 1st plane. Default is 0.04.
  3402. Valid range is 0 to 5.
  3403. @item 1a
  3404. Set threshold A for 2nd plane. Default is 0.02.
  3405. Valid range is 0 to 0.3.
  3406. @item 1b
  3407. Set threshold B for 2nd plane. Default is 0.04.
  3408. Valid range is 0 to 5.
  3409. @item 2a
  3410. Set threshold A for 3rd plane. Default is 0.02.
  3411. Valid range is 0 to 0.3.
  3412. @item 2b
  3413. Set threshold B for 3rd plane. Default is 0.04.
  3414. Valid range is 0 to 5.
  3415. Threshold A is designed to react on abrupt changes in the input signal and
  3416. threshold B is designed to react on continuous changes in the input signal.
  3417. @item s
  3418. Set number of frames filter will use for averaging. Default is 33. Must be odd
  3419. number in range [5, 129].
  3420. @item p
  3421. Set what planes of frame filter will use for averaging. Default is all.
  3422. @end table
  3423. @section avgblur
  3424. Apply average blur filter.
  3425. The filter accepts the following options:
  3426. @table @option
  3427. @item sizeX
  3428. Set horizontal kernel size.
  3429. @item planes
  3430. Set which planes to filter. By default all planes are filtered.
  3431. @item sizeY
  3432. Set vertical kernel size, if zero it will be same as @code{sizeX}.
  3433. Default is @code{0}.
  3434. @end table
  3435. @section bbox
  3436. Compute the bounding box for the non-black pixels in the input frame
  3437. luminance plane.
  3438. This filter computes the bounding box containing all the pixels with a
  3439. luminance value greater than the minimum allowed value.
  3440. The parameters describing the bounding box are printed on the filter
  3441. log.
  3442. The filter accepts the following option:
  3443. @table @option
  3444. @item min_val
  3445. Set the minimal luminance value. Default is @code{16}.
  3446. @end table
  3447. @section bitplanenoise
  3448. Show and measure bit plane noise.
  3449. The filter accepts the following options:
  3450. @table @option
  3451. @item bitplane
  3452. Set which plane to analyze. Default is @code{1}.
  3453. @item filter
  3454. Filter out noisy pixels from @code{bitplane} set above.
  3455. Default is disabled.
  3456. @end table
  3457. @section blackdetect
  3458. Detect video intervals that are (almost) completely black. Can be
  3459. useful to detect chapter transitions, commercials, or invalid
  3460. recordings. Output lines contains the time for the start, end and
  3461. duration of the detected black interval expressed in seconds.
  3462. In order to display the output lines, you need to set the loglevel at
  3463. least to the AV_LOG_INFO value.
  3464. The filter accepts the following options:
  3465. @table @option
  3466. @item black_min_duration, d
  3467. Set the minimum detected black duration expressed in seconds. It must
  3468. be a non-negative floating point number.
  3469. Default value is 2.0.
  3470. @item picture_black_ratio_th, pic_th
  3471. Set the threshold for considering a picture "black".
  3472. Express the minimum value for the ratio:
  3473. @example
  3474. @var{nb_black_pixels} / @var{nb_pixels}
  3475. @end example
  3476. for which a picture is considered black.
  3477. Default value is 0.98.
  3478. @item pixel_black_th, pix_th
  3479. Set the threshold for considering a pixel "black".
  3480. The threshold expresses the maximum pixel luminance value for which a
  3481. pixel is considered "black". The provided value is scaled according to
  3482. the following equation:
  3483. @example
  3484. @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
  3485. @end example
  3486. @var{luminance_range_size} and @var{luminance_minimum_value} depend on
  3487. the input video format, the range is [0-255] for YUV full-range
  3488. formats and [16-235] for YUV non full-range formats.
  3489. Default value is 0.10.
  3490. @end table
  3491. The following example sets the maximum pixel threshold to the minimum
  3492. value, and detects only black intervals of 2 or more seconds:
  3493. @example
  3494. blackdetect=d=2:pix_th=0.00
  3495. @end example
  3496. @section blackframe
  3497. Detect frames that are (almost) completely black. Can be useful to
  3498. detect chapter transitions or commercials. Output lines consist of
  3499. the frame number of the detected frame, the percentage of blackness,
  3500. the position in the file if known or -1 and the timestamp in seconds.
  3501. In order to display the output lines, you need to set the loglevel at
  3502. least to the AV_LOG_INFO value.
  3503. It accepts the following parameters:
  3504. @table @option
  3505. @item amount
  3506. The percentage of the pixels that have to be below the threshold; it defaults to
  3507. @code{98}.
  3508. @item threshold, thresh
  3509. The threshold below which a pixel value is considered black; it defaults to
  3510. @code{32}.
  3511. @end table
  3512. @section blend, tblend
  3513. Blend two video frames into each other.
  3514. The @code{blend} filter takes two input streams and outputs one
  3515. stream, the first input is the "top" layer and second input is
  3516. "bottom" layer. By default, the output terminates when the longest input terminates.
  3517. The @code{tblend} (time blend) filter takes two consecutive frames
  3518. from one single stream, and outputs the result obtained by blending
  3519. the new frame on top of the old frame.
  3520. A description of the accepted options follows.
  3521. @table @option
  3522. @item c0_mode
  3523. @item c1_mode
  3524. @item c2_mode
  3525. @item c3_mode
  3526. @item all_mode
  3527. Set blend mode for specific pixel component or all pixel components in case
  3528. of @var{all_mode}. Default value is @code{normal}.
  3529. Available values for component modes are:
  3530. @table @samp
  3531. @item addition
  3532. @item addition128
  3533. @item and
  3534. @item average
  3535. @item burn
  3536. @item darken
  3537. @item difference
  3538. @item difference128
  3539. @item divide
  3540. @item dodge
  3541. @item freeze
  3542. @item exclusion
  3543. @item glow
  3544. @item hardlight
  3545. @item hardmix
  3546. @item heat
  3547. @item lighten
  3548. @item linearlight
  3549. @item multiply
  3550. @item multiply128
  3551. @item negation
  3552. @item normal
  3553. @item or
  3554. @item overlay
  3555. @item phoenix
  3556. @item pinlight
  3557. @item reflect
  3558. @item screen
  3559. @item softlight
  3560. @item subtract
  3561. @item vividlight
  3562. @item xor
  3563. @end table
  3564. @item c0_opacity
  3565. @item c1_opacity
  3566. @item c2_opacity
  3567. @item c3_opacity
  3568. @item all_opacity
  3569. Set blend opacity for specific pixel component or all pixel components in case
  3570. of @var{all_opacity}. Only used in combination with pixel component blend modes.
  3571. @item c0_expr
  3572. @item c1_expr
  3573. @item c2_expr
  3574. @item c3_expr
  3575. @item all_expr
  3576. Set blend expression for specific pixel component or all pixel components in case
  3577. of @var{all_expr}. Note that related mode options will be ignored if those are set.
  3578. The expressions can use the following variables:
  3579. @table @option
  3580. @item N
  3581. The sequential number of the filtered frame, starting from @code{0}.
  3582. @item X
  3583. @item Y
  3584. the coordinates of the current sample
  3585. @item W
  3586. @item H
  3587. the width and height of currently filtered plane
  3588. @item SW
  3589. @item SH
  3590. Width and height scale depending on the currently filtered plane. It is the
  3591. ratio between the corresponding luma plane number of pixels and the current
  3592. plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
  3593. @code{0.5,0.5} for chroma planes.
  3594. @item T
  3595. Time of the current frame, expressed in seconds.
  3596. @item TOP, A
  3597. Value of pixel component at current location for first video frame (top layer).
  3598. @item BOTTOM, B
  3599. Value of pixel component at current location for second video frame (bottom layer).
  3600. @end table
  3601. @item shortest
  3602. Force termination when the shortest input terminates. Default is
  3603. @code{0}. This option is only defined for the @code{blend} filter.
  3604. @item repeatlast
  3605. Continue applying the last bottom frame after the end of the stream. A value of
  3606. @code{0} disable the filter after the last frame of the bottom layer is reached.
  3607. Default is @code{1}. This option is only defined for the @code{blend} filter.
  3608. @end table
  3609. @subsection Examples
  3610. @itemize
  3611. @item
  3612. Apply transition from bottom layer to top layer in first 10 seconds:
  3613. @example
  3614. blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
  3615. @end example
  3616. @item
  3617. Apply 1x1 checkerboard effect:
  3618. @example
  3619. blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
  3620. @end example
  3621. @item
  3622. Apply uncover left effect:
  3623. @example
  3624. blend=all_expr='if(gte(N*SW+X,W),A,B)'
  3625. @end example
  3626. @item
  3627. Apply uncover down effect:
  3628. @example
  3629. blend=all_expr='if(gte(Y-N*SH,0),A,B)'
  3630. @end example
  3631. @item
  3632. Apply uncover up-left effect:
  3633. @example
  3634. blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
  3635. @end example
  3636. @item
  3637. Split diagonally video and shows top and bottom layer on each side:
  3638. @example
  3639. blend=all_expr=if(gt(X,Y*(W/H)),A,B)
  3640. @end example
  3641. @item
  3642. Display differences between the current and the previous frame:
  3643. @example
  3644. tblend=all_mode=difference128
  3645. @end example
  3646. @end itemize
  3647. @section boxblur
  3648. Apply a boxblur algorithm to the input video.
  3649. It accepts the following parameters:
  3650. @table @option
  3651. @item luma_radius, lr
  3652. @item luma_power, lp
  3653. @item chroma_radius, cr
  3654. @item chroma_power, cp
  3655. @item alpha_radius, ar
  3656. @item alpha_power, ap
  3657. @end table
  3658. A description of the accepted options follows.
  3659. @table @option
  3660. @item luma_radius, lr
  3661. @item chroma_radius, cr
  3662. @item alpha_radius, ar
  3663. Set an expression for the box radius in pixels used for blurring the
  3664. corresponding input plane.
  3665. The radius value must be a non-negative number, and must not be
  3666. greater than the value of the expression @code{min(w,h)/2} for the
  3667. luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
  3668. planes.
  3669. Default value for @option{luma_radius} is "2". If not specified,
  3670. @option{chroma_radius} and @option{alpha_radius} default to the
  3671. corresponding value set for @option{luma_radius}.
  3672. The expressions can contain the following constants:
  3673. @table @option
  3674. @item w
  3675. @item h
  3676. The input width and height in pixels.
  3677. @item cw
  3678. @item ch
  3679. The input chroma image width and height in pixels.
  3680. @item hsub
  3681. @item vsub
  3682. The horizontal and vertical chroma subsample values. For example, for the
  3683. pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
  3684. @end table
  3685. @item luma_power, lp
  3686. @item chroma_power, cp
  3687. @item alpha_power, ap
  3688. Specify how many times the boxblur filter is applied to the
  3689. corresponding plane.
  3690. Default value for @option{luma_power} is 2. If not specified,
  3691. @option{chroma_power} and @option{alpha_power} default to the
  3692. corresponding value set for @option{luma_power}.
  3693. A value of 0 will disable the effect.
  3694. @end table
  3695. @subsection Examples
  3696. @itemize
  3697. @item
  3698. Apply a boxblur filter with the luma, chroma, and alpha radii
  3699. set to 2:
  3700. @example
  3701. boxblur=luma_radius=2:luma_power=1
  3702. boxblur=2:1
  3703. @end example
  3704. @item
  3705. Set the luma radius to 2, and alpha and chroma radius to 0:
  3706. @example
  3707. boxblur=2:1:cr=0:ar=0
  3708. @end example
  3709. @item
  3710. Set the luma and chroma radii to a fraction of the video dimension:
  3711. @example
  3712. boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
  3713. @end example
  3714. @end itemize
  3715. @section bwdif
  3716. Deinterlace the input video ("bwdif" stands for "Bob Weaver
  3717. Deinterlacing Filter").
  3718. Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
  3719. interpolation algorithms.
  3720. It accepts the following parameters:
  3721. @table @option
  3722. @item mode
  3723. The interlacing mode to adopt. It accepts one of the following values:
  3724. @table @option
  3725. @item 0, send_frame
  3726. Output one frame for each frame.
  3727. @item 1, send_field
  3728. Output one frame for each field.
  3729. @end table
  3730. The default value is @code{send_field}.
  3731. @item parity
  3732. The picture field parity assumed for the input interlaced video. It accepts one
  3733. of the following values:
  3734. @table @option
  3735. @item 0, tff
  3736. Assume the top field is first.
  3737. @item 1, bff
  3738. Assume the bottom field is first.
  3739. @item -1, auto
  3740. Enable automatic detection of field parity.
  3741. @end table
  3742. The default value is @code{auto}.
  3743. If the interlacing is unknown or the decoder does not export this information,
  3744. top field first will be assumed.
  3745. @item deint
  3746. Specify which frames to deinterlace. Accept one of the following
  3747. values:
  3748. @table @option
  3749. @item 0, all
  3750. Deinterlace all frames.
  3751. @item 1, interlaced
  3752. Only deinterlace frames marked as interlaced.
  3753. @end table
  3754. The default value is @code{all}.
  3755. @end table
  3756. @section chromakey
  3757. YUV colorspace color/chroma keying.
  3758. The filter accepts the following options:
  3759. @table @option
  3760. @item color
  3761. The color which will be replaced with transparency.
  3762. @item similarity
  3763. Similarity percentage with the key color.
  3764. 0.01 matches only the exact key color, while 1.0 matches everything.
  3765. @item blend
  3766. Blend percentage.
  3767. 0.0 makes pixels either fully transparent, or not transparent at all.
  3768. Higher values result in semi-transparent pixels, with a higher transparency
  3769. the more similar the pixels color is to the key color.
  3770. @item yuv
  3771. Signals that the color passed is already in YUV instead of RGB.
  3772. Litteral colors like "green" or "red" don't make sense with this enabled anymore.
  3773. This can be used to pass exact YUV values as hexadecimal numbers.
  3774. @end table
  3775. @subsection Examples
  3776. @itemize
  3777. @item
  3778. Make every green pixel in the input image transparent:
  3779. @example
  3780. ffmpeg -i input.png -vf chromakey=green out.png
  3781. @end example
  3782. @item
  3783. Overlay a greenscreen-video on top of a static black background.
  3784. @example
  3785. ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
  3786. @end example
  3787. @end itemize
  3788. @section ciescope
  3789. Display CIE color diagram with pixels overlaid onto it.
  3790. The filter accepts the following options:
  3791. @table @option
  3792. @item system
  3793. Set color system.
  3794. @table @samp
  3795. @item ntsc, 470m
  3796. @item ebu, 470bg
  3797. @item smpte
  3798. @item 240m
  3799. @item apple
  3800. @item widergb
  3801. @item cie1931
  3802. @item rec709, hdtv
  3803. @item uhdtv, rec2020
  3804. @end table
  3805. @item cie
  3806. Set CIE system.
  3807. @table @samp
  3808. @item xyy
  3809. @item ucs
  3810. @item luv
  3811. @end table
  3812. @item gamuts
  3813. Set what gamuts to draw.
  3814. See @code{system} option for available values.
  3815. @item size, s
  3816. Set ciescope size, by default set to 512.
  3817. @item intensity, i
  3818. Set intensity used to map input pixel values to CIE diagram.
  3819. @item contrast
  3820. Set contrast used to draw tongue colors that are out of active color system gamut.
  3821. @item corrgamma
  3822. Correct gamma displayed on scope, by default enabled.
  3823. @item showwhite
  3824. Show white point on CIE diagram, by default disabled.
  3825. @item gamma
  3826. Set input gamma. Used only with XYZ input color space.
  3827. @end table
  3828. @section codecview
  3829. Visualize information exported by some codecs.
  3830. Some codecs can export information through frames using side-data or other
  3831. means. For example, some MPEG based codecs export motion vectors through the
  3832. @var{export_mvs} flag in the codec @option{flags2} option.
  3833. The filter accepts the following option:
  3834. @table @option
  3835. @item mv
  3836. Set motion vectors to visualize.
  3837. Available flags for @var{mv} are:
  3838. @table @samp
  3839. @item pf
  3840. forward predicted MVs of P-frames
  3841. @item bf
  3842. forward predicted MVs of B-frames
  3843. @item bb
  3844. backward predicted MVs of B-frames
  3845. @end table
  3846. @item qp
  3847. Display quantization parameters using the chroma planes.
  3848. @item mv_type, mvt
  3849. Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
  3850. Available flags for @var{mv_type} are:
  3851. @table @samp
  3852. @item fp
  3853. forward predicted MVs
  3854. @item bp
  3855. backward predicted MVs
  3856. @end table
  3857. @item frame_type, ft
  3858. Set frame type to visualize motion vectors of.
  3859. Available flags for @var{frame_type} are:
  3860. @table @samp
  3861. @item if
  3862. intra-coded frames (I-frames)
  3863. @item pf
  3864. predicted frames (P-frames)
  3865. @item bf
  3866. bi-directionally predicted frames (B-frames)
  3867. @end table
  3868. @end table
  3869. @subsection Examples
  3870. @itemize
  3871. @item
  3872. Visualize forward predicted MVs of all frames using @command{ffplay}:
  3873. @example
  3874. ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
  3875. @end example
  3876. @item
  3877. Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
  3878. @example
  3879. ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
  3880. @end example
  3881. @end itemize
  3882. @section colorbalance
  3883. Modify intensity of primary colors (red, green and blue) of input frames.
  3884. The filter allows an input frame to be adjusted in the shadows, midtones or highlights
  3885. regions for the red-cyan, green-magenta or blue-yellow balance.
  3886. A positive adjustment value shifts the balance towards the primary color, a negative
  3887. value towards the complementary color.
  3888. The filter accepts the following options:
  3889. @table @option
  3890. @item rs
  3891. @item gs
  3892. @item bs
  3893. Adjust red, green and blue shadows (darkest pixels).
  3894. @item rm
  3895. @item gm
  3896. @item bm
  3897. Adjust red, green and blue midtones (medium pixels).
  3898. @item rh
  3899. @item gh
  3900. @item bh
  3901. Adjust red, green and blue highlights (brightest pixels).
  3902. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  3903. @end table
  3904. @subsection Examples
  3905. @itemize
  3906. @item
  3907. Add red color cast to shadows:
  3908. @example
  3909. colorbalance=rs=.3
  3910. @end example
  3911. @end itemize
  3912. @section colorkey
  3913. RGB colorspace color keying.
  3914. The filter accepts the following options:
  3915. @table @option
  3916. @item color
  3917. The color which will be replaced with transparency.
  3918. @item similarity
  3919. Similarity percentage with the key color.
  3920. 0.01 matches only the exact key color, while 1.0 matches everything.
  3921. @item blend
  3922. Blend percentage.
  3923. 0.0 makes pixels either fully transparent, or not transparent at all.
  3924. Higher values result in semi-transparent pixels, with a higher transparency
  3925. the more similar the pixels color is to the key color.
  3926. @end table
  3927. @subsection Examples
  3928. @itemize
  3929. @item
  3930. Make every green pixel in the input image transparent:
  3931. @example
  3932. ffmpeg -i input.png -vf colorkey=green out.png
  3933. @end example
  3934. @item
  3935. Overlay a greenscreen-video on top of a static background image.
  3936. @example
  3937. ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv
  3938. @end example
  3939. @end itemize
  3940. @section colorlevels
  3941. Adjust video input frames using levels.
  3942. The filter accepts the following options:
  3943. @table @option
  3944. @item rimin
  3945. @item gimin
  3946. @item bimin
  3947. @item aimin
  3948. Adjust red, green, blue and alpha input black point.
  3949. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  3950. @item rimax
  3951. @item gimax
  3952. @item bimax
  3953. @item aimax
  3954. Adjust red, green, blue and alpha input white point.
  3955. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
  3956. Input levels are used to lighten highlights (bright tones), darken shadows
  3957. (dark tones), change the balance of bright and dark tones.
  3958. @item romin
  3959. @item gomin
  3960. @item bomin
  3961. @item aomin
  3962. Adjust red, green, blue and alpha output black point.
  3963. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
  3964. @item romax
  3965. @item gomax
  3966. @item bomax
  3967. @item aomax
  3968. Adjust red, green, blue and alpha output white point.
  3969. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
  3970. Output levels allows manual selection of a constrained output level range.
  3971. @end table
  3972. @subsection Examples
  3973. @itemize
  3974. @item
  3975. Make video output darker:
  3976. @example
  3977. colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
  3978. @end example
  3979. @item
  3980. Increase contrast:
  3981. @example
  3982. colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
  3983. @end example
  3984. @item
  3985. Make video output lighter:
  3986. @example
  3987. colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
  3988. @end example
  3989. @item
  3990. Increase brightness:
  3991. @example
  3992. colorlevels=romin=0.5:gomin=0.5:bomin=0.5
  3993. @end example
  3994. @end itemize
  3995. @section colorchannelmixer
  3996. Adjust video input frames by re-mixing color channels.
  3997. This filter modifies a color channel by adding the values associated to
  3998. the other channels of the same pixels. For example if the value to
  3999. modify is red, the output value will be:
  4000. @example
  4001. @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
  4002. @end example
  4003. The filter accepts the following options:
  4004. @table @option
  4005. @item rr
  4006. @item rg
  4007. @item rb
  4008. @item ra
  4009. Adjust contribution of input red, green, blue and alpha channels for output red channel.
  4010. Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
  4011. @item gr
  4012. @item gg
  4013. @item gb
  4014. @item ga
  4015. Adjust contribution of input red, green, blue and alpha channels for output green channel.
  4016. Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
  4017. @item br
  4018. @item bg
  4019. @item bb
  4020. @item ba
  4021. Adjust contribution of input red, green, blue and alpha channels for output blue channel.
  4022. Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
  4023. @item ar
  4024. @item ag
  4025. @item ab
  4026. @item aa
  4027. Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
  4028. Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
  4029. Allowed ranges for options are @code{[-2.0, 2.0]}.
  4030. @end table
  4031. @subsection Examples
  4032. @itemize
  4033. @item
  4034. Convert source to grayscale:
  4035. @example
  4036. colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
  4037. @end example
  4038. @item
  4039. Simulate sepia tones:
  4040. @example
  4041. colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
  4042. @end example
  4043. @end itemize
  4044. @section colormatrix
  4045. Convert color matrix.
  4046. The filter accepts the following options:
  4047. @table @option
  4048. @item src
  4049. @item dst
  4050. Specify the source and destination color matrix. Both values must be
  4051. specified.
  4052. The accepted values are:
  4053. @table @samp
  4054. @item bt709
  4055. BT.709
  4056. @item bt601
  4057. BT.601
  4058. @item smpte240m
  4059. SMPTE-240M
  4060. @item fcc
  4061. FCC
  4062. @item bt2020
  4063. BT.2020
  4064. @end table
  4065. @end table
  4066. For example to convert from BT.601 to SMPTE-240M, use the command:
  4067. @example
  4068. colormatrix=bt601:smpte240m
  4069. @end example
  4070. @section colorspace
  4071. Convert colorspace, transfer characteristics or color primaries.
  4072. The filter accepts the following options:
  4073. @table @option
  4074. @anchor{all}
  4075. @item all
  4076. Specify all color properties at once.
  4077. The accepted values are:
  4078. @table @samp
  4079. @item bt470m
  4080. BT.470M
  4081. @item bt470bg
  4082. BT.470BG
  4083. @item bt601-6-525
  4084. BT.601-6 525
  4085. @item bt601-6-625
  4086. BT.601-6 625
  4087. @item bt709
  4088. BT.709
  4089. @item smpte170m
  4090. SMPTE-170M
  4091. @item smpte240m
  4092. SMPTE-240M
  4093. @item bt2020
  4094. BT.2020
  4095. @end table
  4096. @anchor{space}
  4097. @item space
  4098. Specify output colorspace.
  4099. The accepted values are:
  4100. @table @samp
  4101. @item bt709
  4102. BT.709
  4103. @item fcc
  4104. FCC
  4105. @item bt470bg
  4106. BT.470BG or BT.601-6 625
  4107. @item smpte170m
  4108. SMPTE-170M or BT.601-6 525
  4109. @item smpte240m
  4110. SMPTE-240M
  4111. @item bt2020ncl
  4112. BT.2020 with non-constant luminance
  4113. @end table
  4114. @anchor{trc}
  4115. @item trc
  4116. Specify output transfer characteristics.
  4117. The accepted values are:
  4118. @table @samp
  4119. @item bt709
  4120. BT.709
  4121. @item gamma22
  4122. Constant gamma of 2.2
  4123. @item gamma28
  4124. Constant gamma of 2.8
  4125. @item smpte170m
  4126. SMPTE-170M, BT.601-6 625 or BT.601-6 525
  4127. @item smpte240m
  4128. SMPTE-240M
  4129. @item bt2020-10
  4130. BT.2020 for 10-bits content
  4131. @item bt2020-12
  4132. BT.2020 for 12-bits content
  4133. @end table
  4134. @anchor{primaries}
  4135. @item primaries
  4136. Specify output color primaries.
  4137. The accepted values are:
  4138. @table @samp
  4139. @item bt709
  4140. BT.709
  4141. @item bt470m
  4142. BT.470M
  4143. @item bt470bg
  4144. BT.470BG or BT.601-6 625
  4145. @item smpte170m
  4146. SMPTE-170M or BT.601-6 525
  4147. @item smpte240m
  4148. SMPTE-240M
  4149. @item bt2020
  4150. BT.2020
  4151. @end table
  4152. @anchor{range}
  4153. @item range
  4154. Specify output color range.
  4155. The accepted values are:
  4156. @table @samp
  4157. @item mpeg
  4158. MPEG (restricted) range
  4159. @item jpeg
  4160. JPEG (full) range
  4161. @end table
  4162. @item format
  4163. Specify output color format.
  4164. The accepted values are:
  4165. @table @samp
  4166. @item yuv420p
  4167. YUV 4:2:0 planar 8-bits
  4168. @item yuv420p10
  4169. YUV 4:2:0 planar 10-bits
  4170. @item yuv420p12
  4171. YUV 4:2:0 planar 12-bits
  4172. @item yuv422p
  4173. YUV 4:2:2 planar 8-bits
  4174. @item yuv422p10
  4175. YUV 4:2:2 planar 10-bits
  4176. @item yuv422p12
  4177. YUV 4:2:2 planar 12-bits
  4178. @item yuv444p
  4179. YUV 4:4:4 planar 8-bits
  4180. @item yuv444p10
  4181. YUV 4:4:4 planar 10-bits
  4182. @item yuv444p12
  4183. YUV 4:4:4 planar 12-bits
  4184. @end table
  4185. @item fast
  4186. Do a fast conversion, which skips gamma/primary correction. This will take
  4187. significantly less CPU, but will be mathematically incorrect. To get output
  4188. compatible with that produced by the colormatrix filter, use fast=1.
  4189. @item dither
  4190. Specify dithering mode.
  4191. The accepted values are:
  4192. @table @samp
  4193. @item none
  4194. No dithering
  4195. @item fsb
  4196. Floyd-Steinberg dithering
  4197. @end table
  4198. @item wpadapt
  4199. Whitepoint adaptation mode.
  4200. The accepted values are:
  4201. @table @samp
  4202. @item bradford
  4203. Bradford whitepoint adaptation
  4204. @item vonkries
  4205. von Kries whitepoint adaptation
  4206. @item identity
  4207. identity whitepoint adaptation (i.e. no whitepoint adaptation)
  4208. @end table
  4209. @item iall
  4210. Override all input properties at once. Same accepted values as @ref{all}.
  4211. @item ispace
  4212. Override input colorspace. Same accepted values as @ref{space}.
  4213. @item iprimaries
  4214. Override input color primaries. Same accepted values as @ref{primaries}.
  4215. @item itrc
  4216. Override input transfer characteristics. Same accepted values as @ref{trc}.
  4217. @item irange
  4218. Override input color range. Same accepted values as @ref{range}.
  4219. @end table
  4220. The filter converts the transfer characteristics, color space and color
  4221. primaries to the specified user values. The output value, if not specified,
  4222. is set to a default value based on the "all" property. If that property is
  4223. also not specified, the filter will log an error. The output color range and
  4224. format default to the same value as the input color range and format. The
  4225. input transfer characteristics, color space, color primaries and color range
  4226. should be set on the input data. If any of these are missing, the filter will
  4227. log an error and no conversion will take place.
  4228. For example to convert the input to SMPTE-240M, use the command:
  4229. @example
  4230. colorspace=smpte240m
  4231. @end example
  4232. @section convolution
  4233. Apply convolution 3x3 or 5x5 filter.
  4234. The filter accepts the following options:
  4235. @table @option
  4236. @item 0m
  4237. @item 1m
  4238. @item 2m
  4239. @item 3m
  4240. Set matrix for each plane.
  4241. Matrix is sequence of 9 or 25 signed integers.
  4242. @item 0rdiv
  4243. @item 1rdiv
  4244. @item 2rdiv
  4245. @item 3rdiv
  4246. Set multiplier for calculated value for each plane.
  4247. @item 0bias
  4248. @item 1bias
  4249. @item 2bias
  4250. @item 3bias
  4251. Set bias for each plane. This value is added to the result of the multiplication.
  4252. Useful for making the overall image brighter or darker. Default is 0.0.
  4253. @end table
  4254. @subsection Examples
  4255. @itemize
  4256. @item
  4257. Apply sharpen:
  4258. @example
  4259. convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
  4260. @end example
  4261. @item
  4262. Apply blur:
  4263. @example
  4264. convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
  4265. @end example
  4266. @item
  4267. Apply edge enhance:
  4268. @example
  4269. convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
  4270. @end example
  4271. @item
  4272. Apply edge detect:
  4273. @example
  4274. convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
  4275. @end example
  4276. @item
  4277. Apply emboss:
  4278. @example
  4279. convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
  4280. @end example
  4281. @end itemize
  4282. @section copy
  4283. Copy the input source unchanged to the output. This is mainly useful for
  4284. testing purposes.
  4285. @anchor{coreimage}
  4286. @section coreimage
  4287. Video filtering on GPU using Apple's CoreImage API on OSX.
  4288. Hardware acceleration is based on an OpenGL context. Usually, this means it is
  4289. processed by video hardware. However, software-based OpenGL implementations
  4290. exist which means there is no guarantee for hardware processing. It depends on
  4291. the respective OSX.
  4292. There are many filters and image generators provided by Apple that come with a
  4293. large variety of options. The filter has to be referenced by its name along
  4294. with its options.
  4295. The coreimage filter accepts the following options:
  4296. @table @option
  4297. @item list_filters
  4298. List all available filters and generators along with all their respective
  4299. options as well as possible minimum and maximum values along with the default
  4300. values.
  4301. @example
  4302. list_filters=true
  4303. @end example
  4304. @item filter
  4305. Specify all filters by their respective name and options.
  4306. Use @var{list_filters} to determine all valid filter names and options.
  4307. Numerical options are specified by a float value and are automatically clamped
  4308. to their respective value range. Vector and color options have to be specified
  4309. by a list of space separated float values. Character escaping has to be done.
  4310. A special option name @code{default} is available to use default options for a
  4311. filter.
  4312. It is required to specify either @code{default} or at least one of the filter options.
  4313. All omitted options are used with their default values.
  4314. The syntax of the filter string is as follows:
  4315. @example
  4316. filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
  4317. @end example
  4318. @item output_rect
  4319. Specify a rectangle where the output of the filter chain is copied into the
  4320. input image. It is given by a list of space separated float values:
  4321. @example
  4322. output_rect=x\ y\ width\ height
  4323. @end example
  4324. If not given, the output rectangle equals the dimensions of the input image.
  4325. The output rectangle is automatically cropped at the borders of the input
  4326. image. Negative values are valid for each component.
  4327. @example
  4328. output_rect=25\ 25\ 100\ 100
  4329. @end example
  4330. @end table
  4331. Several filters can be chained for successive processing without GPU-HOST
  4332. transfers allowing for fast processing of complex filter chains.
  4333. Currently, only filters with zero (generators) or exactly one (filters) input
  4334. image and one output image are supported. Also, transition filters are not yet
  4335. usable as intended.
  4336. Some filters generate output images with additional padding depending on the
  4337. respective filter kernel. The padding is automatically removed to ensure the
  4338. filter output has the same size as the input image.
  4339. For image generators, the size of the output image is determined by the
  4340. previous output image of the filter chain or the input image of the whole
  4341. filterchain, respectively. The generators do not use the pixel information of
  4342. this image to generate their output. However, the generated output is
  4343. blended onto this image, resulting in partial or complete coverage of the
  4344. output image.
  4345. The @ref{coreimagesrc} video source can be used for generating input images
  4346. which are directly fed into the filter chain. By using it, providing input
  4347. images by another video source or an input video is not required.
  4348. @subsection Examples
  4349. @itemize
  4350. @item
  4351. List all filters available:
  4352. @example
  4353. coreimage=list_filters=true
  4354. @end example
  4355. @item
  4356. Use the CIBoxBlur filter with default options to blur an image:
  4357. @example
  4358. coreimage=filter=CIBoxBlur@@default
  4359. @end example
  4360. @item
  4361. Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
  4362. its center at 100x100 and a radius of 50 pixels:
  4363. @example
  4364. coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
  4365. @end example
  4366. @item
  4367. Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
  4368. given as complete and escaped command-line for Apple's standard bash shell:
  4369. @example
  4370. ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
  4371. @end example
  4372. @end itemize
  4373. @section crop
  4374. Crop the input video to given dimensions.
  4375. It accepts the following parameters:
  4376. @table @option
  4377. @item w, out_w
  4378. The width of the output video. It defaults to @code{iw}.
  4379. This expression is evaluated only once during the filter
  4380. configuration, or when the @samp{w} or @samp{out_w} command is sent.
  4381. @item h, out_h
  4382. The height of the output video. It defaults to @code{ih}.
  4383. This expression is evaluated only once during the filter
  4384. configuration, or when the @samp{h} or @samp{out_h} command is sent.
  4385. @item x
  4386. The horizontal position, in the input video, of the left edge of the output
  4387. video. It defaults to @code{(in_w-out_w)/2}.
  4388. This expression is evaluated per-frame.
  4389. @item y
  4390. The vertical position, in the input video, of the top edge of the output video.
  4391. It defaults to @code{(in_h-out_h)/2}.
  4392. This expression is evaluated per-frame.
  4393. @item keep_aspect
  4394. If set to 1 will force the output display aspect ratio
  4395. to be the same of the input, by changing the output sample aspect
  4396. ratio. It defaults to 0.
  4397. @item exact
  4398. Enable exact cropping. If enabled, subsampled videos will be cropped at exact
  4399. width/height/x/y as specified and will not be rounded to nearest smaller value.
  4400. It defaults to 0.
  4401. @end table
  4402. The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
  4403. expressions containing the following constants:
  4404. @table @option
  4405. @item x
  4406. @item y
  4407. The computed values for @var{x} and @var{y}. They are evaluated for
  4408. each new frame.
  4409. @item in_w
  4410. @item in_h
  4411. The input width and height.
  4412. @item iw
  4413. @item ih
  4414. These are the same as @var{in_w} and @var{in_h}.
  4415. @item out_w
  4416. @item out_h
  4417. The output (cropped) width and height.
  4418. @item ow
  4419. @item oh
  4420. These are the same as @var{out_w} and @var{out_h}.
  4421. @item a
  4422. same as @var{iw} / @var{ih}
  4423. @item sar
  4424. input sample aspect ratio
  4425. @item dar
  4426. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  4427. @item hsub
  4428. @item vsub
  4429. horizontal and vertical chroma subsample values. For example for the
  4430. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  4431. @item n
  4432. The number of the input frame, starting from 0.
  4433. @item pos
  4434. the position in the file of the input frame, NAN if unknown
  4435. @item t
  4436. The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
  4437. @end table
  4438. The expression for @var{out_w} may depend on the value of @var{out_h},
  4439. and the expression for @var{out_h} may depend on @var{out_w}, but they
  4440. cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
  4441. evaluated after @var{out_w} and @var{out_h}.
  4442. The @var{x} and @var{y} parameters specify the expressions for the
  4443. position of the top-left corner of the output (non-cropped) area. They
  4444. are evaluated for each frame. If the evaluated value is not valid, it
  4445. is approximated to the nearest valid value.
  4446. The expression for @var{x} may depend on @var{y}, and the expression
  4447. for @var{y} may depend on @var{x}.
  4448. @subsection Examples
  4449. @itemize
  4450. @item
  4451. Crop area with size 100x100 at position (12,34).
  4452. @example
  4453. crop=100:100:12:34
  4454. @end example
  4455. Using named options, the example above becomes:
  4456. @example
  4457. crop=w=100:h=100:x=12:y=34
  4458. @end example
  4459. @item
  4460. Crop the central input area with size 100x100:
  4461. @example
  4462. crop=100:100
  4463. @end example
  4464. @item
  4465. Crop the central input area with size 2/3 of the input video:
  4466. @example
  4467. crop=2/3*in_w:2/3*in_h
  4468. @end example
  4469. @item
  4470. Crop the input video central square:
  4471. @example
  4472. crop=out_w=in_h
  4473. crop=in_h
  4474. @end example
  4475. @item
  4476. Delimit the rectangle with the top-left corner placed at position
  4477. 100:100 and the right-bottom corner corresponding to the right-bottom
  4478. corner of the input image.
  4479. @example
  4480. crop=in_w-100:in_h-100:100:100
  4481. @end example
  4482. @item
  4483. Crop 10 pixels from the left and right borders, and 20 pixels from
  4484. the top and bottom borders
  4485. @example
  4486. crop=in_w-2*10:in_h-2*20
  4487. @end example
  4488. @item
  4489. Keep only the bottom right quarter of the input image:
  4490. @example
  4491. crop=in_w/2:in_h/2:in_w/2:in_h/2
  4492. @end example
  4493. @item
  4494. Crop height for getting Greek harmony:
  4495. @example
  4496. crop=in_w:1/PHI*in_w
  4497. @end example
  4498. @item
  4499. Apply trembling effect:
  4500. @example
  4501. 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)
  4502. @end example
  4503. @item
  4504. Apply erratic camera effect depending on timestamp:
  4505. @example
  4506. 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)"
  4507. @end example
  4508. @item
  4509. Set x depending on the value of y:
  4510. @example
  4511. crop=in_w/2:in_h/2:y:10+10*sin(n/10)
  4512. @end example
  4513. @end itemize
  4514. @subsection Commands
  4515. This filter supports the following commands:
  4516. @table @option
  4517. @item w, out_w
  4518. @item h, out_h
  4519. @item x
  4520. @item y
  4521. Set width/height of the output video and the horizontal/vertical position
  4522. in the input video.
  4523. The command accepts the same syntax of the corresponding option.
  4524. If the specified expression is not valid, it is kept at its current
  4525. value.
  4526. @end table
  4527. @section cropdetect
  4528. Auto-detect the crop size.
  4529. It calculates the necessary cropping parameters and prints the
  4530. recommended parameters via the logging system. The detected dimensions
  4531. correspond to the non-black area of the input video.
  4532. It accepts the following parameters:
  4533. @table @option
  4534. @item limit
  4535. Set higher black value threshold, which can be optionally specified
  4536. from nothing (0) to everything (255 for 8-bit based formats). An intensity
  4537. value greater to the set value is considered non-black. It defaults to 24.
  4538. You can also specify a value between 0.0 and 1.0 which will be scaled depending
  4539. on the bitdepth of the pixel format.
  4540. @item round
  4541. The value which the width/height should be divisible by. It defaults to
  4542. 16. The offset is automatically adjusted to center the video. Use 2 to
  4543. get only even dimensions (needed for 4:2:2 video). 16 is best when
  4544. encoding to most video codecs.
  4545. @item reset_count, reset
  4546. Set the counter that determines after how many frames cropdetect will
  4547. reset the previously detected largest video area and start over to
  4548. detect the current optimal crop area. Default value is 0.
  4549. This can be useful when channel logos distort the video area. 0
  4550. indicates 'never reset', and returns the largest area encountered during
  4551. playback.
  4552. @end table
  4553. @anchor{curves}
  4554. @section curves
  4555. Apply color adjustments using curves.
  4556. This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
  4557. component (red, green and blue) has its values defined by @var{N} key points
  4558. tied from each other using a smooth curve. The x-axis represents the pixel
  4559. values from the input frame, and the y-axis the new pixel values to be set for
  4560. the output frame.
  4561. By default, a component curve is defined by the two points @var{(0;0)} and
  4562. @var{(1;1)}. This creates a straight line where each original pixel value is
  4563. "adjusted" to its own value, which means no change to the image.
  4564. The filter allows you to redefine these two points and add some more. A new
  4565. curve (using a natural cubic spline interpolation) will be define to pass
  4566. smoothly through all these new coordinates. The new defined points needs to be
  4567. strictly increasing over the x-axis, and their @var{x} and @var{y} values must
  4568. be in the @var{[0;1]} interval. If the computed curves happened to go outside
  4569. the vector spaces, the values will be clipped accordingly.
  4570. The filter accepts the following options:
  4571. @table @option
  4572. @item preset
  4573. Select one of the available color presets. This option can be used in addition
  4574. to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
  4575. options takes priority on the preset values.
  4576. Available presets are:
  4577. @table @samp
  4578. @item none
  4579. @item color_negative
  4580. @item cross_process
  4581. @item darker
  4582. @item increase_contrast
  4583. @item lighter
  4584. @item linear_contrast
  4585. @item medium_contrast
  4586. @item negative
  4587. @item strong_contrast
  4588. @item vintage
  4589. @end table
  4590. Default is @code{none}.
  4591. @item master, m
  4592. Set the master key points. These points will define a second pass mapping. It
  4593. is sometimes called a "luminance" or "value" mapping. It can be used with
  4594. @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
  4595. post-processing LUT.
  4596. @item red, r
  4597. Set the key points for the red component.
  4598. @item green, g
  4599. Set the key points for the green component.
  4600. @item blue, b
  4601. Set the key points for the blue component.
  4602. @item all
  4603. Set the key points for all components (not including master).
  4604. Can be used in addition to the other key points component
  4605. options. In this case, the unset component(s) will fallback on this
  4606. @option{all} setting.
  4607. @item psfile
  4608. Specify a Photoshop curves file (@code{.acv}) to import the settings from.
  4609. @item plot
  4610. Save Gnuplot script of the curves in specified file.
  4611. @end table
  4612. To avoid some filtergraph syntax conflicts, each key points list need to be
  4613. defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
  4614. @subsection Examples
  4615. @itemize
  4616. @item
  4617. Increase slightly the middle level of blue:
  4618. @example
  4619. curves=blue='0/0 0.5/0.58 1/1'
  4620. @end example
  4621. @item
  4622. Vintage effect:
  4623. @example
  4624. curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'
  4625. @end example
  4626. Here we obtain the following coordinates for each components:
  4627. @table @var
  4628. @item red
  4629. @code{(0;0.11) (0.42;0.51) (1;0.95)}
  4630. @item green
  4631. @code{(0;0) (0.50;0.48) (1;1)}
  4632. @item blue
  4633. @code{(0;0.22) (0.49;0.44) (1;0.80)}
  4634. @end table
  4635. @item
  4636. The previous example can also be achieved with the associated built-in preset:
  4637. @example
  4638. curves=preset=vintage
  4639. @end example
  4640. @item
  4641. Or simply:
  4642. @example
  4643. curves=vintage
  4644. @end example
  4645. @item
  4646. Use a Photoshop preset and redefine the points of the green component:
  4647. @example
  4648. curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
  4649. @end example
  4650. @item
  4651. Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
  4652. and @command{gnuplot}:
  4653. @example
  4654. ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
  4655. gnuplot -p /tmp/curves.plt
  4656. @end example
  4657. @end itemize
  4658. @section datascope
  4659. Video data analysis filter.
  4660. This filter shows hexadecimal pixel values of part of video.
  4661. The filter accepts the following options:
  4662. @table @option
  4663. @item size, s
  4664. Set output video size.
  4665. @item x
  4666. Set x offset from where to pick pixels.
  4667. @item y
  4668. Set y offset from where to pick pixels.
  4669. @item mode
  4670. Set scope mode, can be one of the following:
  4671. @table @samp
  4672. @item mono
  4673. Draw hexadecimal pixel values with white color on black background.
  4674. @item color
  4675. Draw hexadecimal pixel values with input video pixel color on black
  4676. background.
  4677. @item color2
  4678. Draw hexadecimal pixel values on color background picked from input video,
  4679. the text color is picked in such way so its always visible.
  4680. @end table
  4681. @item axis
  4682. Draw rows and columns numbers on left and top of video.
  4683. @item opacity
  4684. Set background opacity.
  4685. @end table
  4686. @section dctdnoiz
  4687. Denoise frames using 2D DCT (frequency domain filtering).
  4688. This filter is not designed for real time.
  4689. The filter accepts the following options:
  4690. @table @option
  4691. @item sigma, s
  4692. Set the noise sigma constant.
  4693. This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
  4694. coefficient (absolute value) below this threshold with be dropped.
  4695. If you need a more advanced filtering, see @option{expr}.
  4696. Default is @code{0}.
  4697. @item overlap
  4698. Set number overlapping pixels for each block. Since the filter can be slow, you
  4699. may want to reduce this value, at the cost of a less effective filter and the
  4700. risk of various artefacts.
  4701. If the overlapping value doesn't permit processing the whole input width or
  4702. height, a warning will be displayed and according borders won't be denoised.
  4703. Default value is @var{blocksize}-1, which is the best possible setting.
  4704. @item expr, e
  4705. Set the coefficient factor expression.
  4706. For each coefficient of a DCT block, this expression will be evaluated as a
  4707. multiplier value for the coefficient.
  4708. If this is option is set, the @option{sigma} option will be ignored.
  4709. The absolute value of the coefficient can be accessed through the @var{c}
  4710. variable.
  4711. @item n
  4712. Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
  4713. @var{blocksize}, which is the width and height of the processed blocks.
  4714. The default value is @var{3} (8x8) and can be raised to @var{4} for a
  4715. @var{blocksize} of 16x16. Note that changing this setting has huge consequences
  4716. on the speed processing. Also, a larger block size does not necessarily means a
  4717. better de-noising.
  4718. @end table
  4719. @subsection Examples
  4720. Apply a denoise with a @option{sigma} of @code{4.5}:
  4721. @example
  4722. dctdnoiz=4.5
  4723. @end example
  4724. The same operation can be achieved using the expression system:
  4725. @example
  4726. dctdnoiz=e='gte(c, 4.5*3)'
  4727. @end example
  4728. Violent denoise using a block size of @code{16x16}:
  4729. @example
  4730. dctdnoiz=15:n=4
  4731. @end example
  4732. @section deband
  4733. Remove banding artifacts from input video.
  4734. It works by replacing banded pixels with average value of referenced pixels.
  4735. The filter accepts the following options:
  4736. @table @option
  4737. @item 1thr
  4738. @item 2thr
  4739. @item 3thr
  4740. @item 4thr
  4741. Set banding detection threshold for each plane. Default is 0.02.
  4742. Valid range is 0.00003 to 0.5.
  4743. If difference between current pixel and reference pixel is less than threshold,
  4744. it will be considered as banded.
  4745. @item range, r
  4746. Banding detection range in pixels. Default is 16. If positive, random number
  4747. in range 0 to set value will be used. If negative, exact absolute value
  4748. will be used.
  4749. The range defines square of four pixels around current pixel.
  4750. @item direction, d
  4751. Set direction in radians from which four pixel will be compared. If positive,
  4752. random direction from 0 to set direction will be picked. If negative, exact of
  4753. absolute value will be picked. For example direction 0, -PI or -2*PI radians
  4754. will pick only pixels on same row and -PI/2 will pick only pixels on same
  4755. column.
  4756. @item blur
  4757. If enabled, current pixel is compared with average value of all four
  4758. surrounding pixels. The default is enabled. If disabled current pixel is
  4759. compared with all four surrounding pixels. The pixel is considered banded
  4760. if only all four differences with surrounding pixels are less than threshold.
  4761. @end table
  4762. @anchor{decimate}
  4763. @section decimate
  4764. Drop duplicated frames at regular intervals.
  4765. The filter accepts the following options:
  4766. @table @option
  4767. @item cycle
  4768. Set the number of frames from which one will be dropped. Setting this to
  4769. @var{N} means one frame in every batch of @var{N} frames will be dropped.
  4770. Default is @code{5}.
  4771. @item dupthresh
  4772. Set the threshold for duplicate detection. If the difference metric for a frame
  4773. is less than or equal to this value, then it is declared as duplicate. Default
  4774. is @code{1.1}
  4775. @item scthresh
  4776. Set scene change threshold. Default is @code{15}.
  4777. @item blockx
  4778. @item blocky
  4779. Set the size of the x and y-axis blocks used during metric calculations.
  4780. Larger blocks give better noise suppression, but also give worse detection of
  4781. small movements. Must be a power of two. Default is @code{32}.
  4782. @item ppsrc
  4783. Mark main input as a pre-processed input and activate clean source input
  4784. stream. This allows the input to be pre-processed with various filters to help
  4785. the metrics calculation while keeping the frame selection lossless. When set to
  4786. @code{1}, the first stream is for the pre-processed input, and the second
  4787. stream is the clean source from where the kept frames are chosen. Default is
  4788. @code{0}.
  4789. @item chroma
  4790. Set whether or not chroma is considered in the metric calculations. Default is
  4791. @code{1}.
  4792. @end table
  4793. @section deflate
  4794. Apply deflate effect to the video.
  4795. This filter replaces the pixel by the local(3x3) average by taking into account
  4796. only values lower than the pixel.
  4797. It accepts the following options:
  4798. @table @option
  4799. @item threshold0
  4800. @item threshold1
  4801. @item threshold2
  4802. @item threshold3
  4803. Limit the maximum change for each plane, default is 65535.
  4804. If 0, plane will remain unchanged.
  4805. @end table
  4806. @section dejudder
  4807. Remove judder produced by partially interlaced telecined content.
  4808. Judder can be introduced, for instance, by @ref{pullup} filter. If the original
  4809. source was partially telecined content then the output of @code{pullup,dejudder}
  4810. will have a variable frame rate. May change the recorded frame rate of the
  4811. container. Aside from that change, this filter will not affect constant frame
  4812. rate video.
  4813. The option available in this filter is:
  4814. @table @option
  4815. @item cycle
  4816. Specify the length of the window over which the judder repeats.
  4817. Accepts any integer greater than 1. Useful values are:
  4818. @table @samp
  4819. @item 4
  4820. If the original was telecined from 24 to 30 fps (Film to NTSC).
  4821. @item 5
  4822. If the original was telecined from 25 to 30 fps (PAL to NTSC).
  4823. @item 20
  4824. If a mixture of the two.
  4825. @end table
  4826. The default is @samp{4}.
  4827. @end table
  4828. @section delogo
  4829. Suppress a TV station logo by a simple interpolation of the surrounding
  4830. pixels. Just set a rectangle covering the logo and watch it disappear
  4831. (and sometimes something even uglier appear - your mileage may vary).
  4832. It accepts the following parameters:
  4833. @table @option
  4834. @item x
  4835. @item y
  4836. Specify the top left corner coordinates of the logo. They must be
  4837. specified.
  4838. @item w
  4839. @item h
  4840. Specify the width and height of the logo to clear. They must be
  4841. specified.
  4842. @item band, t
  4843. Specify the thickness of the fuzzy edge of the rectangle (added to
  4844. @var{w} and @var{h}). The default value is 1. This option is
  4845. deprecated, setting higher values should no longer be necessary and
  4846. is not recommended.
  4847. @item show
  4848. When set to 1, a green rectangle is drawn on the screen to simplify
  4849. finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
  4850. The default value is 0.
  4851. The rectangle is drawn on the outermost pixels which will be (partly)
  4852. replaced with interpolated values. The values of the next pixels
  4853. immediately outside this rectangle in each direction will be used to
  4854. compute the interpolated pixel values inside the rectangle.
  4855. @end table
  4856. @subsection Examples
  4857. @itemize
  4858. @item
  4859. Set a rectangle covering the area with top left corner coordinates 0,0
  4860. and size 100x77, and a band of size 10:
  4861. @example
  4862. delogo=x=0:y=0:w=100:h=77:band=10
  4863. @end example
  4864. @end itemize
  4865. @section deshake
  4866. Attempt to fix small changes in horizontal and/or vertical shift. This
  4867. filter helps remove camera shake from hand-holding a camera, bumping a
  4868. tripod, moving on a vehicle, etc.
  4869. The filter accepts the following options:
  4870. @table @option
  4871. @item x
  4872. @item y
  4873. @item w
  4874. @item h
  4875. Specify a rectangular area where to limit the search for motion
  4876. vectors.
  4877. If desired the search for motion vectors can be limited to a
  4878. rectangular area of the frame defined by its top left corner, width
  4879. and height. These parameters have the same meaning as the drawbox
  4880. filter which can be used to visualise the position of the bounding
  4881. box.
  4882. This is useful when simultaneous movement of subjects within the frame
  4883. might be confused for camera motion by the motion vector search.
  4884. If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
  4885. then the full frame is used. This allows later options to be set
  4886. without specifying the bounding box for the motion vector search.
  4887. Default - search the whole frame.
  4888. @item rx
  4889. @item ry
  4890. Specify the maximum extent of movement in x and y directions in the
  4891. range 0-64 pixels. Default 16.
  4892. @item edge
  4893. Specify how to generate pixels to fill blanks at the edge of the
  4894. frame. Available values are:
  4895. @table @samp
  4896. @item blank, 0
  4897. Fill zeroes at blank locations
  4898. @item original, 1
  4899. Original image at blank locations
  4900. @item clamp, 2
  4901. Extruded edge value at blank locations
  4902. @item mirror, 3
  4903. Mirrored edge at blank locations
  4904. @end table
  4905. Default value is @samp{mirror}.
  4906. @item blocksize
  4907. Specify the blocksize to use for motion search. Range 4-128 pixels,
  4908. default 8.
  4909. @item contrast
  4910. Specify the contrast threshold for blocks. Only blocks with more than
  4911. the specified contrast (difference between darkest and lightest
  4912. pixels) will be considered. Range 1-255, default 125.
  4913. @item search
  4914. Specify the search strategy. Available values are:
  4915. @table @samp
  4916. @item exhaustive, 0
  4917. Set exhaustive search
  4918. @item less, 1
  4919. Set less exhaustive search.
  4920. @end table
  4921. Default value is @samp{exhaustive}.
  4922. @item filename
  4923. If set then a detailed log of the motion search is written to the
  4924. specified file.
  4925. @item opencl
  4926. If set to 1, specify using OpenCL capabilities, only available if
  4927. FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
  4928. @end table
  4929. @section detelecine
  4930. Apply an exact inverse of the telecine operation. It requires a predefined
  4931. pattern specified using the pattern option which must be the same as that passed
  4932. to the telecine filter.
  4933. This filter accepts the following options:
  4934. @table @option
  4935. @item first_field
  4936. @table @samp
  4937. @item top, t
  4938. top field first
  4939. @item bottom, b
  4940. bottom field first
  4941. The default value is @code{top}.
  4942. @end table
  4943. @item pattern
  4944. A string of numbers representing the pulldown pattern you wish to apply.
  4945. The default value is @code{23}.
  4946. @item start_frame
  4947. A number representing position of the first frame with respect to the telecine
  4948. pattern. This is to be used if the stream is cut. The default value is @code{0}.
  4949. @end table
  4950. @section dilation
  4951. Apply dilation effect to the video.
  4952. This filter replaces the pixel by the local(3x3) maximum.
  4953. It accepts the following options:
  4954. @table @option
  4955. @item threshold0
  4956. @item threshold1
  4957. @item threshold2
  4958. @item threshold3
  4959. Limit the maximum change for each plane, default is 65535.
  4960. If 0, plane will remain unchanged.
  4961. @item coordinates
  4962. Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
  4963. pixels are used.
  4964. Flags to local 3x3 coordinates maps like this:
  4965. 1 2 3
  4966. 4 5
  4967. 6 7 8
  4968. @end table
  4969. @section displace
  4970. Displace pixels as indicated by second and third input stream.
  4971. It takes three input streams and outputs one stream, the first input is the
  4972. source, and second and third input are displacement maps.
  4973. The second input specifies how much to displace pixels along the
  4974. x-axis, while the third input specifies how much to displace pixels
  4975. along the y-axis.
  4976. If one of displacement map streams terminates, last frame from that
  4977. displacement map will be used.
  4978. Note that once generated, displacements maps can be reused over and over again.
  4979. A description of the accepted options follows.
  4980. @table @option
  4981. @item edge
  4982. Set displace behavior for pixels that are out of range.
  4983. Available values are:
  4984. @table @samp
  4985. @item blank
  4986. Missing pixels are replaced by black pixels.
  4987. @item smear
  4988. Adjacent pixels will spread out to replace missing pixels.
  4989. @item wrap
  4990. Out of range pixels are wrapped so they point to pixels of other side.
  4991. @end table
  4992. Default is @samp{smear}.
  4993. @end table
  4994. @subsection Examples
  4995. @itemize
  4996. @item
  4997. Add ripple effect to rgb input of video size hd720:
  4998. @example
  4999. ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT
  5000. @end example
  5001. @item
  5002. Add wave effect to rgb input of video size hd720:
  5003. @example
  5004. ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT
  5005. @end example
  5006. @end itemize
  5007. @section drawbox
  5008. Draw a colored box on the input image.
  5009. It accepts the following parameters:
  5010. @table @option
  5011. @item x
  5012. @item y
  5013. The expressions which specify the top left corner coordinates of the box. It defaults to 0.
  5014. @item width, w
  5015. @item height, h
  5016. The expressions which specify the width and height of the box; if 0 they are interpreted as
  5017. the input width and height. It defaults to 0.
  5018. @item color, c
  5019. Specify the color of the box to write. For the general syntax of this option,
  5020. check the "Color" section in the ffmpeg-utils manual. If the special
  5021. value @code{invert} is used, the box edge color is the same as the
  5022. video with inverted luma.
  5023. @item thickness, t
  5024. The expression which sets the thickness of the box edge. Default value is @code{3}.
  5025. See below for the list of accepted constants.
  5026. @end table
  5027. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  5028. following constants:
  5029. @table @option
  5030. @item dar
  5031. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  5032. @item hsub
  5033. @item vsub
  5034. horizontal and vertical chroma subsample values. For example for the
  5035. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5036. @item in_h, ih
  5037. @item in_w, iw
  5038. The input width and height.
  5039. @item sar
  5040. The input sample aspect ratio.
  5041. @item x
  5042. @item y
  5043. The x and y offset coordinates where the box is drawn.
  5044. @item w
  5045. @item h
  5046. The width and height of the drawn box.
  5047. @item t
  5048. The thickness of the drawn box.
  5049. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  5050. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  5051. @end table
  5052. @subsection Examples
  5053. @itemize
  5054. @item
  5055. Draw a black box around the edge of the input image:
  5056. @example
  5057. drawbox
  5058. @end example
  5059. @item
  5060. Draw a box with color red and an opacity of 50%:
  5061. @example
  5062. drawbox=10:20:200:60:red@@0.5
  5063. @end example
  5064. The previous example can be specified as:
  5065. @example
  5066. drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
  5067. @end example
  5068. @item
  5069. Fill the box with pink color:
  5070. @example
  5071. drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
  5072. @end example
  5073. @item
  5074. Draw a 2-pixel red 2.40:1 mask:
  5075. @example
  5076. 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
  5077. @end example
  5078. @end itemize
  5079. @section drawgrid
  5080. Draw a grid on the input image.
  5081. It accepts the following parameters:
  5082. @table @option
  5083. @item x
  5084. @item y
  5085. The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
  5086. @item width, w
  5087. @item height, h
  5088. The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
  5089. input width and height, respectively, minus @code{thickness}, so image gets
  5090. framed. Default to 0.
  5091. @item color, c
  5092. Specify the color of the grid. For the general syntax of this option,
  5093. check the "Color" section in the ffmpeg-utils manual. If the special
  5094. value @code{invert} is used, the grid color is the same as the
  5095. video with inverted luma.
  5096. @item thickness, t
  5097. The expression which sets the thickness of the grid line. Default value is @code{1}.
  5098. See below for the list of accepted constants.
  5099. @end table
  5100. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  5101. following constants:
  5102. @table @option
  5103. @item dar
  5104. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  5105. @item hsub
  5106. @item vsub
  5107. horizontal and vertical chroma subsample values. For example for the
  5108. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5109. @item in_h, ih
  5110. @item in_w, iw
  5111. The input grid cell width and height.
  5112. @item sar
  5113. The input sample aspect ratio.
  5114. @item x
  5115. @item y
  5116. The x and y coordinates of some point of grid intersection (meant to configure offset).
  5117. @item w
  5118. @item h
  5119. The width and height of the drawn cell.
  5120. @item t
  5121. The thickness of the drawn cell.
  5122. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  5123. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  5124. @end table
  5125. @subsection Examples
  5126. @itemize
  5127. @item
  5128. Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
  5129. @example
  5130. drawgrid=width=100:height=100:thickness=2:color=red@@0.5
  5131. @end example
  5132. @item
  5133. Draw a white 3x3 grid with an opacity of 50%:
  5134. @example
  5135. drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
  5136. @end example
  5137. @end itemize
  5138. @anchor{drawtext}
  5139. @section drawtext
  5140. Draw a text string or text from a specified file on top of a video, using the
  5141. libfreetype library.
  5142. To enable compilation of this filter, you need to configure FFmpeg with
  5143. @code{--enable-libfreetype}.
  5144. To enable default font fallback and the @var{font} option you need to
  5145. configure FFmpeg with @code{--enable-libfontconfig}.
  5146. To enable the @var{text_shaping} option, you need to configure FFmpeg with
  5147. @code{--enable-libfribidi}.
  5148. @subsection Syntax
  5149. It accepts the following parameters:
  5150. @table @option
  5151. @item box
  5152. Used to draw a box around text using the background color.
  5153. The value must be either 1 (enable) or 0 (disable).
  5154. The default value of @var{box} is 0.
  5155. @item boxborderw
  5156. Set the width of the border to be drawn around the box using @var{boxcolor}.
  5157. The default value of @var{boxborderw} is 0.
  5158. @item boxcolor
  5159. The color to be used for drawing box around text. For the syntax of this
  5160. option, check the "Color" section in the ffmpeg-utils manual.
  5161. The default value of @var{boxcolor} is "white".
  5162. @item borderw
  5163. Set the width of the border to be drawn around the text using @var{bordercolor}.
  5164. The default value of @var{borderw} is 0.
  5165. @item bordercolor
  5166. Set the color to be used for drawing border around text. For the syntax of this
  5167. option, check the "Color" section in the ffmpeg-utils manual.
  5168. The default value of @var{bordercolor} is "black".
  5169. @item expansion
  5170. Select how the @var{text} is expanded. Can be either @code{none},
  5171. @code{strftime} (deprecated) or
  5172. @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
  5173. below for details.
  5174. @item fix_bounds
  5175. If true, check and fix text coords to avoid clipping.
  5176. @item fontcolor
  5177. The color to be used for drawing fonts. For the syntax of this option, check
  5178. the "Color" section in the ffmpeg-utils manual.
  5179. The default value of @var{fontcolor} is "black".
  5180. @item fontcolor_expr
  5181. String which is expanded the same way as @var{text} to obtain dynamic
  5182. @var{fontcolor} value. By default this option has empty value and is not
  5183. processed. When this option is set, it overrides @var{fontcolor} option.
  5184. @item font
  5185. The font family to be used for drawing text. By default Sans.
  5186. @item fontfile
  5187. The font file to be used for drawing text. The path must be included.
  5188. This parameter is mandatory if the fontconfig support is disabled.
  5189. @item draw
  5190. This option does not exist, please see the timeline system
  5191. @item alpha
  5192. Draw the text applying alpha blending. The value can
  5193. be either a number between 0.0 and 1.0
  5194. The expression accepts the same variables @var{x, y} do.
  5195. The default value is 1.
  5196. Please see fontcolor_expr
  5197. @item fontsize
  5198. The font size to be used for drawing text.
  5199. The default value of @var{fontsize} is 16.
  5200. @item text_shaping
  5201. If set to 1, attempt to shape the text (for example, reverse the order of
  5202. right-to-left text and join Arabic characters) before drawing it.
  5203. Otherwise, just draw the text exactly as given.
  5204. By default 1 (if supported).
  5205. @item ft_load_flags
  5206. The flags to be used for loading the fonts.
  5207. The flags map the corresponding flags supported by libfreetype, and are
  5208. a combination of the following values:
  5209. @table @var
  5210. @item default
  5211. @item no_scale
  5212. @item no_hinting
  5213. @item render
  5214. @item no_bitmap
  5215. @item vertical_layout
  5216. @item force_autohint
  5217. @item crop_bitmap
  5218. @item pedantic
  5219. @item ignore_global_advance_width
  5220. @item no_recurse
  5221. @item ignore_transform
  5222. @item monochrome
  5223. @item linear_design
  5224. @item no_autohint
  5225. @end table
  5226. Default value is "default".
  5227. For more information consult the documentation for the FT_LOAD_*
  5228. libfreetype flags.
  5229. @item shadowcolor
  5230. The color to be used for drawing a shadow behind the drawn text. For the
  5231. syntax of this option, check the "Color" section in the ffmpeg-utils manual.
  5232. The default value of @var{shadowcolor} is "black".
  5233. @item shadowx
  5234. @item shadowy
  5235. The x and y offsets for the text shadow position with respect to the
  5236. position of the text. They can be either positive or negative
  5237. values. The default value for both is "0".
  5238. @item start_number
  5239. The starting frame number for the n/frame_num variable. The default value
  5240. is "0".
  5241. @item tabsize
  5242. The size in number of spaces to use for rendering the tab.
  5243. Default value is 4.
  5244. @item timecode
  5245. Set the initial timecode representation in "hh:mm:ss[:;.]ff"
  5246. format. It can be used with or without text parameter. @var{timecode_rate}
  5247. option must be specified.
  5248. @item timecode_rate, rate, r
  5249. Set the timecode frame rate (timecode only).
  5250. @item text
  5251. The text string to be drawn. The text must be a sequence of UTF-8
  5252. encoded characters.
  5253. This parameter is mandatory if no file is specified with the parameter
  5254. @var{textfile}.
  5255. @item textfile
  5256. A text file containing text to be drawn. The text must be a sequence
  5257. of UTF-8 encoded characters.
  5258. This parameter is mandatory if no text string is specified with the
  5259. parameter @var{text}.
  5260. If both @var{text} and @var{textfile} are specified, an error is thrown.
  5261. @item reload
  5262. If set to 1, the @var{textfile} will be reloaded before each frame.
  5263. Be sure to update it atomically, or it may be read partially, or even fail.
  5264. @item x
  5265. @item y
  5266. The expressions which specify the offsets where text will be drawn
  5267. within the video frame. They are relative to the top/left border of the
  5268. output image.
  5269. The default value of @var{x} and @var{y} is "0".
  5270. See below for the list of accepted constants and functions.
  5271. @end table
  5272. The parameters for @var{x} and @var{y} are expressions containing the
  5273. following constants and functions:
  5274. @table @option
  5275. @item dar
  5276. input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
  5277. @item hsub
  5278. @item vsub
  5279. horizontal and vertical chroma subsample values. For example for the
  5280. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5281. @item line_h, lh
  5282. the height of each text line
  5283. @item main_h, h, H
  5284. the input height
  5285. @item main_w, w, W
  5286. the input width
  5287. @item max_glyph_a, ascent
  5288. the maximum distance from the baseline to the highest/upper grid
  5289. coordinate used to place a glyph outline point, for all the rendered
  5290. glyphs.
  5291. It is a positive value, due to the grid's orientation with the Y axis
  5292. upwards.
  5293. @item max_glyph_d, descent
  5294. the maximum distance from the baseline to the lowest grid coordinate
  5295. used to place a glyph outline point, for all the rendered glyphs.
  5296. This is a negative value, due to the grid's orientation, with the Y axis
  5297. upwards.
  5298. @item max_glyph_h
  5299. maximum glyph height, that is the maximum height for all the glyphs
  5300. contained in the rendered text, it is equivalent to @var{ascent} -
  5301. @var{descent}.
  5302. @item max_glyph_w
  5303. maximum glyph width, that is the maximum width for all the glyphs
  5304. contained in the rendered text
  5305. @item n
  5306. the number of input frame, starting from 0
  5307. @item rand(min, max)
  5308. return a random number included between @var{min} and @var{max}
  5309. @item sar
  5310. The input sample aspect ratio.
  5311. @item t
  5312. timestamp expressed in seconds, NAN if the input timestamp is unknown
  5313. @item text_h, th
  5314. the height of the rendered text
  5315. @item text_w, tw
  5316. the width of the rendered text
  5317. @item x
  5318. @item y
  5319. the x and y offset coordinates where the text is drawn.
  5320. These parameters allow the @var{x} and @var{y} expressions to refer
  5321. each other, so you can for example specify @code{y=x/dar}.
  5322. @end table
  5323. @anchor{drawtext_expansion}
  5324. @subsection Text expansion
  5325. If @option{expansion} is set to @code{strftime},
  5326. the filter recognizes strftime() sequences in the provided text and
  5327. expands them accordingly. Check the documentation of strftime(). This
  5328. feature is deprecated.
  5329. If @option{expansion} is set to @code{none}, the text is printed verbatim.
  5330. If @option{expansion} is set to @code{normal} (which is the default),
  5331. the following expansion mechanism is used.
  5332. The backslash character @samp{\}, followed by any character, always expands to
  5333. the second character.
  5334. Sequence of the form @code{%@{...@}} are expanded. The text between the
  5335. braces is a function name, possibly followed by arguments separated by ':'.
  5336. If the arguments contain special characters or delimiters (':' or '@}'),
  5337. they should be escaped.
  5338. Note that they probably must also be escaped as the value for the
  5339. @option{text} option in the filter argument string and as the filter
  5340. argument in the filtergraph description, and possibly also for the shell,
  5341. that makes up to four levels of escaping; using a text file avoids these
  5342. problems.
  5343. The following functions are available:
  5344. @table @command
  5345. @item expr, e
  5346. The expression evaluation result.
  5347. It must take one argument specifying the expression to be evaluated,
  5348. which accepts the same constants and functions as the @var{x} and
  5349. @var{y} values. Note that not all constants should be used, for
  5350. example the text size is not known when evaluating the expression, so
  5351. the constants @var{text_w} and @var{text_h} will have an undefined
  5352. value.
  5353. @item expr_int_format, eif
  5354. Evaluate the expression's value and output as formatted integer.
  5355. The first argument is the expression to be evaluated, just as for the @var{expr} function.
  5356. The second argument specifies the output format. Allowed values are @samp{x},
  5357. @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
  5358. @code{printf} function.
  5359. The third parameter is optional and sets the number of positions taken by the output.
  5360. It can be used to add padding with zeros from the left.
  5361. @item gmtime
  5362. The time at which the filter is running, expressed in UTC.
  5363. It can accept an argument: a strftime() format string.
  5364. @item localtime
  5365. The time at which the filter is running, expressed in the local time zone.
  5366. It can accept an argument: a strftime() format string.
  5367. @item metadata
  5368. Frame metadata. Takes one or two arguments.
  5369. The first argument is mandatory and specifies the metadata key.
  5370. The second argument is optional and specifies a default value, used when the
  5371. metadata key is not found or empty.
  5372. @item n, frame_num
  5373. The frame number, starting from 0.
  5374. @item pict_type
  5375. A 1 character description of the current picture type.
  5376. @item pts
  5377. The timestamp of the current frame.
  5378. It can take up to three arguments.
  5379. The first argument is the format of the timestamp; it defaults to @code{flt}
  5380. for seconds as a decimal number with microsecond accuracy; @code{hms} stands
  5381. for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
  5382. @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
  5383. @code{localtime} stands for the timestamp of the frame formatted as
  5384. local time zone time.
  5385. The second argument is an offset added to the timestamp.
  5386. If the format is set to @code{localtime} or @code{gmtime},
  5387. a third argument may be supplied: a strftime() format string.
  5388. By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
  5389. @end table
  5390. @subsection Examples
  5391. @itemize
  5392. @item
  5393. Draw "Test Text" with font FreeSerif, using the default values for the
  5394. optional parameters.
  5395. @example
  5396. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
  5397. @end example
  5398. @item
  5399. Draw 'Test Text' with font FreeSerif of size 24 at position x=100
  5400. and y=50 (counting from the top-left corner of the screen), text is
  5401. yellow with a red box around it. Both the text and the box have an
  5402. opacity of 20%.
  5403. @example
  5404. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
  5405. x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
  5406. @end example
  5407. Note that the double quotes are not necessary if spaces are not used
  5408. within the parameter list.
  5409. @item
  5410. Show the text at the center of the video frame:
  5411. @example
  5412. drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
  5413. @end example
  5414. @item
  5415. Show the text at a random position, switching to a new position every 30 seconds:
  5416. @example
  5417. drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"
  5418. @end example
  5419. @item
  5420. Show a text line sliding from right to left in the last row of the video
  5421. frame. The file @file{LONG_LINE} is assumed to contain a single line
  5422. with no newlines.
  5423. @example
  5424. drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
  5425. @end example
  5426. @item
  5427. Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
  5428. @example
  5429. drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
  5430. @end example
  5431. @item
  5432. Draw a single green letter "g", at the center of the input video.
  5433. The glyph baseline is placed at half screen height.
  5434. @example
  5435. drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
  5436. @end example
  5437. @item
  5438. Show text for 1 second every 3 seconds:
  5439. @example
  5440. drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
  5441. @end example
  5442. @item
  5443. Use fontconfig to set the font. Note that the colons need to be escaped.
  5444. @example
  5445. drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
  5446. @end example
  5447. @item
  5448. Print the date of a real-time encoding (see strftime(3)):
  5449. @example
  5450. drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
  5451. @end example
  5452. @item
  5453. Show text fading in and out (appearing/disappearing):
  5454. @example
  5455. #!/bin/sh
  5456. DS=1.0 # display start
  5457. DE=10.0 # display end
  5458. FID=1.5 # fade in duration
  5459. FOD=5 # fade out duration
  5460. 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 @}"
  5461. @end example
  5462. @end itemize
  5463. For more information about libfreetype, check:
  5464. @url{http://www.freetype.org/}.
  5465. For more information about fontconfig, check:
  5466. @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
  5467. For more information about libfribidi, check:
  5468. @url{http://fribidi.org/}.
  5469. @section edgedetect
  5470. Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
  5471. The filter accepts the following options:
  5472. @table @option
  5473. @item low
  5474. @item high
  5475. Set low and high threshold values used by the Canny thresholding
  5476. algorithm.
  5477. The high threshold selects the "strong" edge pixels, which are then
  5478. connected through 8-connectivity with the "weak" edge pixels selected
  5479. by the low threshold.
  5480. @var{low} and @var{high} threshold values must be chosen in the range
  5481. [0,1], and @var{low} should be lesser or equal to @var{high}.
  5482. Default value for @var{low} is @code{20/255}, and default value for @var{high}
  5483. is @code{50/255}.
  5484. @item mode
  5485. Define the drawing mode.
  5486. @table @samp
  5487. @item wires
  5488. Draw white/gray wires on black background.
  5489. @item colormix
  5490. Mix the colors to create a paint/cartoon effect.
  5491. @end table
  5492. Default value is @var{wires}.
  5493. @end table
  5494. @subsection Examples
  5495. @itemize
  5496. @item
  5497. Standard edge detection with custom values for the hysteresis thresholding:
  5498. @example
  5499. edgedetect=low=0.1:high=0.4
  5500. @end example
  5501. @item
  5502. Painting effect without thresholding:
  5503. @example
  5504. edgedetect=mode=colormix:high=0
  5505. @end example
  5506. @end itemize
  5507. @section eq
  5508. Set brightness, contrast, saturation and approximate gamma adjustment.
  5509. The filter accepts the following options:
  5510. @table @option
  5511. @item contrast
  5512. Set the contrast expression. The value must be a float value in range
  5513. @code{-2.0} to @code{2.0}. The default value is "1".
  5514. @item brightness
  5515. Set the brightness expression. The value must be a float value in
  5516. range @code{-1.0} to @code{1.0}. The default value is "0".
  5517. @item saturation
  5518. Set the saturation expression. The value must be a float in
  5519. range @code{0.0} to @code{3.0}. The default value is "1".
  5520. @item gamma
  5521. Set the gamma expression. The value must be a float in range
  5522. @code{0.1} to @code{10.0}. The default value is "1".
  5523. @item gamma_r
  5524. Set the gamma expression for red. The value must be a float in
  5525. range @code{0.1} to @code{10.0}. The default value is "1".
  5526. @item gamma_g
  5527. Set the gamma expression for green. The value must be a float in range
  5528. @code{0.1} to @code{10.0}. The default value is "1".
  5529. @item gamma_b
  5530. Set the gamma expression for blue. The value must be a float in range
  5531. @code{0.1} to @code{10.0}. The default value is "1".
  5532. @item gamma_weight
  5533. Set the gamma weight expression. It can be used to reduce the effect
  5534. of a high gamma value on bright image areas, e.g. keep them from
  5535. getting overamplified and just plain white. The value must be a float
  5536. in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
  5537. gamma correction all the way down while @code{1.0} leaves it at its
  5538. full strength. Default is "1".
  5539. @item eval
  5540. Set when the expressions for brightness, contrast, saturation and
  5541. gamma expressions are evaluated.
  5542. It accepts the following values:
  5543. @table @samp
  5544. @item init
  5545. only evaluate expressions once during the filter initialization or
  5546. when a command is processed
  5547. @item frame
  5548. evaluate expressions for each incoming frame
  5549. @end table
  5550. Default value is @samp{init}.
  5551. @end table
  5552. The expressions accept the following parameters:
  5553. @table @option
  5554. @item n
  5555. frame count of the input frame starting from 0
  5556. @item pos
  5557. byte position of the corresponding packet in the input file, NAN if
  5558. unspecified
  5559. @item r
  5560. frame rate of the input video, NAN if the input frame rate is unknown
  5561. @item t
  5562. timestamp expressed in seconds, NAN if the input timestamp is unknown
  5563. @end table
  5564. @subsection Commands
  5565. The filter supports the following commands:
  5566. @table @option
  5567. @item contrast
  5568. Set the contrast expression.
  5569. @item brightness
  5570. Set the brightness expression.
  5571. @item saturation
  5572. Set the saturation expression.
  5573. @item gamma
  5574. Set the gamma expression.
  5575. @item gamma_r
  5576. Set the gamma_r expression.
  5577. @item gamma_g
  5578. Set gamma_g expression.
  5579. @item gamma_b
  5580. Set gamma_b expression.
  5581. @item gamma_weight
  5582. Set gamma_weight expression.
  5583. The command accepts the same syntax of the corresponding option.
  5584. If the specified expression is not valid, it is kept at its current
  5585. value.
  5586. @end table
  5587. @section erosion
  5588. Apply erosion effect to the video.
  5589. This filter replaces the pixel by the local(3x3) minimum.
  5590. It accepts the following options:
  5591. @table @option
  5592. @item threshold0
  5593. @item threshold1
  5594. @item threshold2
  5595. @item threshold3
  5596. Limit the maximum change for each plane, default is 65535.
  5597. If 0, plane will remain unchanged.
  5598. @item coordinates
  5599. Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
  5600. pixels are used.
  5601. Flags to local 3x3 coordinates maps like this:
  5602. 1 2 3
  5603. 4 5
  5604. 6 7 8
  5605. @end table
  5606. @section extractplanes
  5607. Extract color channel components from input video stream into
  5608. separate grayscale video streams.
  5609. The filter accepts the following option:
  5610. @table @option
  5611. @item planes
  5612. Set plane(s) to extract.
  5613. Available values for planes are:
  5614. @table @samp
  5615. @item y
  5616. @item u
  5617. @item v
  5618. @item a
  5619. @item r
  5620. @item g
  5621. @item b
  5622. @end table
  5623. Choosing planes not available in the input will result in an error.
  5624. That means you cannot select @code{r}, @code{g}, @code{b} planes
  5625. with @code{y}, @code{u}, @code{v} planes at same time.
  5626. @end table
  5627. @subsection Examples
  5628. @itemize
  5629. @item
  5630. Extract luma, u and v color channel component from input video frame
  5631. into 3 grayscale outputs:
  5632. @example
  5633. 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
  5634. @end example
  5635. @end itemize
  5636. @section elbg
  5637. Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
  5638. For each input image, the filter will compute the optimal mapping from
  5639. the input to the output given the codebook length, that is the number
  5640. of distinct output colors.
  5641. This filter accepts the following options.
  5642. @table @option
  5643. @item codebook_length, l
  5644. Set codebook length. The value must be a positive integer, and
  5645. represents the number of distinct output colors. Default value is 256.
  5646. @item nb_steps, n
  5647. Set the maximum number of iterations to apply for computing the optimal
  5648. mapping. The higher the value the better the result and the higher the
  5649. computation time. Default value is 1.
  5650. @item seed, s
  5651. Set a random seed, must be an integer included between 0 and
  5652. UINT32_MAX. If not specified, or if explicitly set to -1, the filter
  5653. will try to use a good random seed on a best effort basis.
  5654. @item pal8
  5655. Set pal8 output pixel format. This option does not work with codebook
  5656. length greater than 256.
  5657. @end table
  5658. @section fade
  5659. Apply a fade-in/out effect to the input video.
  5660. It accepts the following parameters:
  5661. @table @option
  5662. @item type, t
  5663. The effect type can be either "in" for a fade-in, or "out" for a fade-out
  5664. effect.
  5665. Default is @code{in}.
  5666. @item start_frame, s
  5667. Specify the number of the frame to start applying the fade
  5668. effect at. Default is 0.
  5669. @item nb_frames, n
  5670. The number of frames that the fade effect lasts. At the end of the
  5671. fade-in effect, the output video will have the same intensity as the input video.
  5672. At the end of the fade-out transition, the output video will be filled with the
  5673. selected @option{color}.
  5674. Default is 25.
  5675. @item alpha
  5676. If set to 1, fade only alpha channel, if one exists on the input.
  5677. Default value is 0.
  5678. @item start_time, st
  5679. Specify the timestamp (in seconds) of the frame to start to apply the fade
  5680. effect. If both start_frame and start_time are specified, the fade will start at
  5681. whichever comes last. Default is 0.
  5682. @item duration, d
  5683. The number of seconds for which the fade effect has to last. At the end of the
  5684. fade-in effect the output video will have the same intensity as the input video,
  5685. at the end of the fade-out transition the output video will be filled with the
  5686. selected @option{color}.
  5687. If both duration and nb_frames are specified, duration is used. Default is 0
  5688. (nb_frames is used by default).
  5689. @item color, c
  5690. Specify the color of the fade. Default is "black".
  5691. @end table
  5692. @subsection Examples
  5693. @itemize
  5694. @item
  5695. Fade in the first 30 frames of video:
  5696. @example
  5697. fade=in:0:30
  5698. @end example
  5699. The command above is equivalent to:
  5700. @example
  5701. fade=t=in:s=0:n=30
  5702. @end example
  5703. @item
  5704. Fade out the last 45 frames of a 200-frame video:
  5705. @example
  5706. fade=out:155:45
  5707. fade=type=out:start_frame=155:nb_frames=45
  5708. @end example
  5709. @item
  5710. Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
  5711. @example
  5712. fade=in:0:25, fade=out:975:25
  5713. @end example
  5714. @item
  5715. Make the first 5 frames yellow, then fade in from frame 5-24:
  5716. @example
  5717. fade=in:5:20:color=yellow
  5718. @end example
  5719. @item
  5720. Fade in alpha over first 25 frames of video:
  5721. @example
  5722. fade=in:0:25:alpha=1
  5723. @end example
  5724. @item
  5725. Make the first 5.5 seconds black, then fade in for 0.5 seconds:
  5726. @example
  5727. fade=t=in:st=5.5:d=0.5
  5728. @end example
  5729. @end itemize
  5730. @section fftfilt
  5731. Apply arbitrary expressions to samples in frequency domain
  5732. @table @option
  5733. @item dc_Y
  5734. Adjust the dc value (gain) of the luma plane of the image. The filter
  5735. accepts an integer value in range @code{0} to @code{1000}. The default
  5736. value is set to @code{0}.
  5737. @item dc_U
  5738. Adjust the dc value (gain) of the 1st chroma plane of the image. The
  5739. filter accepts an integer value in range @code{0} to @code{1000}. The
  5740. default value is set to @code{0}.
  5741. @item dc_V
  5742. Adjust the dc value (gain) of the 2nd chroma plane of the image. The
  5743. filter accepts an integer value in range @code{0} to @code{1000}. The
  5744. default value is set to @code{0}.
  5745. @item weight_Y
  5746. Set the frequency domain weight expression for the luma plane.
  5747. @item weight_U
  5748. Set the frequency domain weight expression for the 1st chroma plane.
  5749. @item weight_V
  5750. Set the frequency domain weight expression for the 2nd chroma plane.
  5751. The filter accepts the following variables:
  5752. @item X
  5753. @item Y
  5754. The coordinates of the current sample.
  5755. @item W
  5756. @item H
  5757. The width and height of the image.
  5758. @end table
  5759. @subsection Examples
  5760. @itemize
  5761. @item
  5762. High-pass:
  5763. @example
  5764. fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
  5765. @end example
  5766. @item
  5767. Low-pass:
  5768. @example
  5769. fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
  5770. @end example
  5771. @item
  5772. Sharpen:
  5773. @example
  5774. fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
  5775. @end example
  5776. @item
  5777. Blur:
  5778. @example
  5779. fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
  5780. @end example
  5781. @end itemize
  5782. @section field
  5783. Extract a single field from an interlaced image using stride
  5784. arithmetic to avoid wasting CPU time. The output frames are marked as
  5785. non-interlaced.
  5786. The filter accepts the following options:
  5787. @table @option
  5788. @item type
  5789. Specify whether to extract the top (if the value is @code{0} or
  5790. @code{top}) or the bottom field (if the value is @code{1} or
  5791. @code{bottom}).
  5792. @end table
  5793. @section fieldhint
  5794. Create new frames by copying the top and bottom fields from surrounding frames
  5795. supplied as numbers by the hint file.
  5796. @table @option
  5797. @item hint
  5798. Set file containing hints: absolute/relative frame numbers.
  5799. There must be one line for each frame in a clip. Each line must contain two
  5800. numbers separated by the comma, optionally followed by @code{-} or @code{+}.
  5801. Numbers supplied on each line of file can not be out of [N-1,N+1] where N
  5802. is current frame number for @code{absolute} mode or out of [-1, 1] range
  5803. for @code{relative} mode. First number tells from which frame to pick up top
  5804. field and second number tells from which frame to pick up bottom field.
  5805. If optionally followed by @code{+} output frame will be marked as interlaced,
  5806. else if followed by @code{-} output frame will be marked as progressive, else
  5807. it will be marked same as input frame.
  5808. If line starts with @code{#} or @code{;} that line is skipped.
  5809. @item mode
  5810. Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
  5811. @end table
  5812. Example of first several lines of @code{hint} file for @code{relative} mode:
  5813. @example
  5814. 0,0 - # first frame
  5815. 1,0 - # second frame, use third's frame top field and second's frame bottom field
  5816. 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
  5817. 1,0 -
  5818. 0,0 -
  5819. 0,0 -
  5820. 1,0 -
  5821. 1,0 -
  5822. 1,0 -
  5823. 0,0 -
  5824. 0,0 -
  5825. 1,0 -
  5826. 1,0 -
  5827. 1,0 -
  5828. 0,0 -
  5829. @end example
  5830. @section fieldmatch
  5831. Field matching filter for inverse telecine. It is meant to reconstruct the
  5832. progressive frames from a telecined stream. The filter does not drop duplicated
  5833. frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
  5834. followed by a decimation filter such as @ref{decimate} in the filtergraph.
  5835. The separation of the field matching and the decimation is notably motivated by
  5836. the possibility of inserting a de-interlacing filter fallback between the two.
  5837. If the source has mixed telecined and real interlaced content,
  5838. @code{fieldmatch} will not be able to match fields for the interlaced parts.
  5839. But these remaining combed frames will be marked as interlaced, and thus can be
  5840. de-interlaced by a later filter such as @ref{yadif} before decimation.
  5841. In addition to the various configuration options, @code{fieldmatch} can take an
  5842. optional second stream, activated through the @option{ppsrc} option. If
  5843. enabled, the frames reconstruction will be based on the fields and frames from
  5844. this second stream. This allows the first input to be pre-processed in order to
  5845. help the various algorithms of the filter, while keeping the output lossless
  5846. (assuming the fields are matched properly). Typically, a field-aware denoiser,
  5847. or brightness/contrast adjustments can help.
  5848. Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
  5849. and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
  5850. which @code{fieldmatch} is based on. While the semantic and usage are very
  5851. close, some behaviour and options names can differ.
  5852. The @ref{decimate} filter currently only works for constant frame rate input.
  5853. If your input has mixed telecined (30fps) and progressive content with a lower
  5854. framerate like 24fps use the following filterchain to produce the necessary cfr
  5855. stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
  5856. The filter accepts the following options:
  5857. @table @option
  5858. @item order
  5859. Specify the assumed field order of the input stream. Available values are:
  5860. @table @samp
  5861. @item auto
  5862. Auto detect parity (use FFmpeg's internal parity value).
  5863. @item bff
  5864. Assume bottom field first.
  5865. @item tff
  5866. Assume top field first.
  5867. @end table
  5868. Note that it is sometimes recommended not to trust the parity announced by the
  5869. stream.
  5870. Default value is @var{auto}.
  5871. @item mode
  5872. Set the matching mode or strategy to use. @option{pc} mode is the safest in the
  5873. sense that it won't risk creating jerkiness due to duplicate frames when
  5874. possible, but if there are bad edits or blended fields it will end up
  5875. outputting combed frames when a good match might actually exist. On the other
  5876. hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
  5877. but will almost always find a good frame if there is one. The other values are
  5878. all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
  5879. jerkiness and creating duplicate frames versus finding good matches in sections
  5880. with bad edits, orphaned fields, blended fields, etc.
  5881. More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
  5882. Available values are:
  5883. @table @samp
  5884. @item pc
  5885. 2-way matching (p/c)
  5886. @item pc_n
  5887. 2-way matching, and trying 3rd match if still combed (p/c + n)
  5888. @item pc_u
  5889. 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
  5890. @item pc_n_ub
  5891. 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
  5892. still combed (p/c + n + u/b)
  5893. @item pcn
  5894. 3-way matching (p/c/n)
  5895. @item pcn_ub
  5896. 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
  5897. detected as combed (p/c/n + u/b)
  5898. @end table
  5899. The parenthesis at the end indicate the matches that would be used for that
  5900. mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
  5901. @var{top}).
  5902. In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
  5903. the slowest.
  5904. Default value is @var{pc_n}.
  5905. @item ppsrc
  5906. Mark the main input stream as a pre-processed input, and enable the secondary
  5907. input stream as the clean source to pick the fields from. See the filter
  5908. introduction for more details. It is similar to the @option{clip2} feature from
  5909. VFM/TFM.
  5910. Default value is @code{0} (disabled).
  5911. @item field
  5912. Set the field to match from. It is recommended to set this to the same value as
  5913. @option{order} unless you experience matching failures with that setting. In
  5914. certain circumstances changing the field that is used to match from can have a
  5915. large impact on matching performance. Available values are:
  5916. @table @samp
  5917. @item auto
  5918. Automatic (same value as @option{order}).
  5919. @item bottom
  5920. Match from the bottom field.
  5921. @item top
  5922. Match from the top field.
  5923. @end table
  5924. Default value is @var{auto}.
  5925. @item mchroma
  5926. Set whether or not chroma is included during the match comparisons. In most
  5927. cases it is recommended to leave this enabled. You should set this to @code{0}
  5928. only if your clip has bad chroma problems such as heavy rainbowing or other
  5929. artifacts. Setting this to @code{0} could also be used to speed things up at
  5930. the cost of some accuracy.
  5931. Default value is @code{1}.
  5932. @item y0
  5933. @item y1
  5934. These define an exclusion band which excludes the lines between @option{y0} and
  5935. @option{y1} from being included in the field matching decision. An exclusion
  5936. band can be used to ignore subtitles, a logo, or other things that may
  5937. interfere with the matching. @option{y0} sets the starting scan line and
  5938. @option{y1} sets the ending line; all lines in between @option{y0} and
  5939. @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
  5940. @option{y0} and @option{y1} to the same value will disable the feature.
  5941. @option{y0} and @option{y1} defaults to @code{0}.
  5942. @item scthresh
  5943. Set the scene change detection threshold as a percentage of maximum change on
  5944. the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
  5945. detection is only relevant in case @option{combmatch}=@var{sc}. The range for
  5946. @option{scthresh} is @code{[0.0, 100.0]}.
  5947. Default value is @code{12.0}.
  5948. @item combmatch
  5949. When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
  5950. account the combed scores of matches when deciding what match to use as the
  5951. final match. Available values are:
  5952. @table @samp
  5953. @item none
  5954. No final matching based on combed scores.
  5955. @item sc
  5956. Combed scores are only used when a scene change is detected.
  5957. @item full
  5958. Use combed scores all the time.
  5959. @end table
  5960. Default is @var{sc}.
  5961. @item combdbg
  5962. Force @code{fieldmatch} to calculate the combed metrics for certain matches and
  5963. print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
  5964. Available values are:
  5965. @table @samp
  5966. @item none
  5967. No forced calculation.
  5968. @item pcn
  5969. Force p/c/n calculations.
  5970. @item pcnub
  5971. Force p/c/n/u/b calculations.
  5972. @end table
  5973. Default value is @var{none}.
  5974. @item cthresh
  5975. This is the area combing threshold used for combed frame detection. This
  5976. essentially controls how "strong" or "visible" combing must be to be detected.
  5977. Larger values mean combing must be more visible and smaller values mean combing
  5978. can be less visible or strong and still be detected. Valid settings are from
  5979. @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
  5980. be detected as combed). This is basically a pixel difference value. A good
  5981. range is @code{[8, 12]}.
  5982. Default value is @code{9}.
  5983. @item chroma
  5984. Sets whether or not chroma is considered in the combed frame decision. Only
  5985. disable this if your source has chroma problems (rainbowing, etc.) that are
  5986. causing problems for the combed frame detection with chroma enabled. Actually,
  5987. using @option{chroma}=@var{0} is usually more reliable, except for the case
  5988. where there is chroma only combing in the source.
  5989. Default value is @code{0}.
  5990. @item blockx
  5991. @item blocky
  5992. Respectively set the x-axis and y-axis size of the window used during combed
  5993. frame detection. This has to do with the size of the area in which
  5994. @option{combpel} pixels are required to be detected as combed for a frame to be
  5995. declared combed. See the @option{combpel} parameter description for more info.
  5996. Possible values are any number that is a power of 2 starting at 4 and going up
  5997. to 512.
  5998. Default value is @code{16}.
  5999. @item combpel
  6000. The number of combed pixels inside any of the @option{blocky} by
  6001. @option{blockx} size blocks on the frame for the frame to be detected as
  6002. combed. While @option{cthresh} controls how "visible" the combing must be, this
  6003. setting controls "how much" combing there must be in any localized area (a
  6004. window defined by the @option{blockx} and @option{blocky} settings) on the
  6005. frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
  6006. which point no frames will ever be detected as combed). This setting is known
  6007. as @option{MI} in TFM/VFM vocabulary.
  6008. Default value is @code{80}.
  6009. @end table
  6010. @anchor{p/c/n/u/b meaning}
  6011. @subsection p/c/n/u/b meaning
  6012. @subsubsection p/c/n
  6013. We assume the following telecined stream:
  6014. @example
  6015. Top fields: 1 2 2 3 4
  6016. Bottom fields: 1 2 3 4 4
  6017. @end example
  6018. The numbers correspond to the progressive frame the fields relate to. Here, the
  6019. first two frames are progressive, the 3rd and 4th are combed, and so on.
  6020. When @code{fieldmatch} is configured to run a matching from bottom
  6021. (@option{field}=@var{bottom}) this is how this input stream get transformed:
  6022. @example
  6023. Input stream:
  6024. T 1 2 2 3 4
  6025. B 1 2 3 4 4 <-- matching reference
  6026. Matches: c c n n c
  6027. Output stream:
  6028. T 1 2 3 4 4
  6029. B 1 2 3 4 4
  6030. @end example
  6031. As a result of the field matching, we can see that some frames get duplicated.
  6032. To perform a complete inverse telecine, you need to rely on a decimation filter
  6033. after this operation. See for instance the @ref{decimate} filter.
  6034. The same operation now matching from top fields (@option{field}=@var{top})
  6035. looks like this:
  6036. @example
  6037. Input stream:
  6038. T 1 2 2 3 4 <-- matching reference
  6039. B 1 2 3 4 4
  6040. Matches: c c p p c
  6041. Output stream:
  6042. T 1 2 2 3 4
  6043. B 1 2 2 3 4
  6044. @end example
  6045. In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
  6046. basically, they refer to the frame and field of the opposite parity:
  6047. @itemize
  6048. @item @var{p} matches the field of the opposite parity in the previous frame
  6049. @item @var{c} matches the field of the opposite parity in the current frame
  6050. @item @var{n} matches the field of the opposite parity in the next frame
  6051. @end itemize
  6052. @subsubsection u/b
  6053. The @var{u} and @var{b} matching are a bit special in the sense that they match
  6054. from the opposite parity flag. In the following examples, we assume that we are
  6055. currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
  6056. 'x' is placed above and below each matched fields.
  6057. With bottom matching (@option{field}=@var{bottom}):
  6058. @example
  6059. Match: c p n b u
  6060. x x x x x
  6061. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  6062. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  6063. x x x x x
  6064. Output frames:
  6065. 2 1 2 2 2
  6066. 2 2 2 1 3
  6067. @end example
  6068. With top matching (@option{field}=@var{top}):
  6069. @example
  6070. Match: c p n b u
  6071. x x x x x
  6072. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  6073. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  6074. x x x x x
  6075. Output frames:
  6076. 2 2 2 1 2
  6077. 2 1 3 2 2
  6078. @end example
  6079. @subsection Examples
  6080. Simple IVTC of a top field first telecined stream:
  6081. @example
  6082. fieldmatch=order=tff:combmatch=none, decimate
  6083. @end example
  6084. Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
  6085. @example
  6086. fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
  6087. @end example
  6088. @section fieldorder
  6089. Transform the field order of the input video.
  6090. It accepts the following parameters:
  6091. @table @option
  6092. @item order
  6093. The output field order. Valid values are @var{tff} for top field first or @var{bff}
  6094. for bottom field first.
  6095. @end table
  6096. The default value is @samp{tff}.
  6097. The transformation is done by shifting the picture content up or down
  6098. by one line, and filling the remaining line with appropriate picture content.
  6099. This method is consistent with most broadcast field order converters.
  6100. If the input video is not flagged as being interlaced, or it is already
  6101. flagged as being of the required output field order, then this filter does
  6102. not alter the incoming video.
  6103. It is very useful when converting to or from PAL DV material,
  6104. which is bottom field first.
  6105. For example:
  6106. @example
  6107. ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
  6108. @end example
  6109. @section fifo, afifo
  6110. Buffer input images and send them when they are requested.
  6111. It is mainly useful when auto-inserted by the libavfilter
  6112. framework.
  6113. It does not take parameters.
  6114. @section find_rect
  6115. Find a rectangular object
  6116. It accepts the following options:
  6117. @table @option
  6118. @item object
  6119. Filepath of the object image, needs to be in gray8.
  6120. @item threshold
  6121. Detection threshold, default is 0.5.
  6122. @item mipmaps
  6123. Number of mipmaps, default is 3.
  6124. @item xmin, ymin, xmax, ymax
  6125. Specifies the rectangle in which to search.
  6126. @end table
  6127. @subsection Examples
  6128. @itemize
  6129. @item
  6130. Generate a representative palette of a given video using @command{ffmpeg}:
  6131. @example
  6132. ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
  6133. @end example
  6134. @end itemize
  6135. @section cover_rect
  6136. Cover a rectangular object
  6137. It accepts the following options:
  6138. @table @option
  6139. @item cover
  6140. Filepath of the optional cover image, needs to be in yuv420.
  6141. @item mode
  6142. Set covering mode.
  6143. It accepts the following values:
  6144. @table @samp
  6145. @item cover
  6146. cover it by the supplied image
  6147. @item blur
  6148. cover it by interpolating the surrounding pixels
  6149. @end table
  6150. Default value is @var{blur}.
  6151. @end table
  6152. @subsection Examples
  6153. @itemize
  6154. @item
  6155. Generate a representative palette of a given video using @command{ffmpeg}:
  6156. @example
  6157. ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
  6158. @end example
  6159. @end itemize
  6160. @anchor{format}
  6161. @section format
  6162. Convert the input video to one of the specified pixel formats.
  6163. Libavfilter will try to pick one that is suitable as input to
  6164. the next filter.
  6165. It accepts the following parameters:
  6166. @table @option
  6167. @item pix_fmts
  6168. A '|'-separated list of pixel format names, such as
  6169. "pix_fmts=yuv420p|monow|rgb24".
  6170. @end table
  6171. @subsection Examples
  6172. @itemize
  6173. @item
  6174. Convert the input video to the @var{yuv420p} format
  6175. @example
  6176. format=pix_fmts=yuv420p
  6177. @end example
  6178. Convert the input video to any of the formats in the list
  6179. @example
  6180. format=pix_fmts=yuv420p|yuv444p|yuv410p
  6181. @end example
  6182. @end itemize
  6183. @anchor{fps}
  6184. @section fps
  6185. Convert the video to specified constant frame rate by duplicating or dropping
  6186. frames as necessary.
  6187. It accepts the following parameters:
  6188. @table @option
  6189. @item fps
  6190. The desired output frame rate. The default is @code{25}.
  6191. @item round
  6192. Rounding method.
  6193. Possible values are:
  6194. @table @option
  6195. @item zero
  6196. zero round towards 0
  6197. @item inf
  6198. round away from 0
  6199. @item down
  6200. round towards -infinity
  6201. @item up
  6202. round towards +infinity
  6203. @item near
  6204. round to nearest
  6205. @end table
  6206. The default is @code{near}.
  6207. @item start_time
  6208. Assume the first PTS should be the given value, in seconds. This allows for
  6209. padding/trimming at the start of stream. By default, no assumption is made
  6210. about the first frame's expected PTS, so no padding or trimming is done.
  6211. For example, this could be set to 0 to pad the beginning with duplicates of
  6212. the first frame if a video stream starts after the audio stream or to trim any
  6213. frames with a negative PTS.
  6214. @end table
  6215. Alternatively, the options can be specified as a flat string:
  6216. @var{fps}[:@var{round}].
  6217. See also the @ref{setpts} filter.
  6218. @subsection Examples
  6219. @itemize
  6220. @item
  6221. A typical usage in order to set the fps to 25:
  6222. @example
  6223. fps=fps=25
  6224. @end example
  6225. @item
  6226. Sets the fps to 24, using abbreviation and rounding method to round to nearest:
  6227. @example
  6228. fps=fps=film:round=near
  6229. @end example
  6230. @end itemize
  6231. @section framepack
  6232. Pack two different video streams into a stereoscopic video, setting proper
  6233. metadata on supported codecs. The two views should have the same size and
  6234. framerate and processing will stop when the shorter video ends. Please note
  6235. that you may conveniently adjust view properties with the @ref{scale} and
  6236. @ref{fps} filters.
  6237. It accepts the following parameters:
  6238. @table @option
  6239. @item format
  6240. The desired packing format. Supported values are:
  6241. @table @option
  6242. @item sbs
  6243. The views are next to each other (default).
  6244. @item tab
  6245. The views are on top of each other.
  6246. @item lines
  6247. The views are packed by line.
  6248. @item columns
  6249. The views are packed by column.
  6250. @item frameseq
  6251. The views are temporally interleaved.
  6252. @end table
  6253. @end table
  6254. Some examples:
  6255. @example
  6256. # Convert left and right views into a frame-sequential video
  6257. ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
  6258. # Convert views into a side-by-side video with the same output resolution as the input
  6259. 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
  6260. @end example
  6261. @section framerate
  6262. Change the frame rate by interpolating new video output frames from the source
  6263. frames.
  6264. This filter is not designed to function correctly with interlaced media. If
  6265. you wish to change the frame rate of interlaced media then you are required
  6266. to deinterlace before this filter and re-interlace after this filter.
  6267. A description of the accepted options follows.
  6268. @table @option
  6269. @item fps
  6270. Specify the output frames per second. This option can also be specified
  6271. as a value alone. The default is @code{50}.
  6272. @item interp_start
  6273. Specify the start of a range where the output frame will be created as a
  6274. linear interpolation of two frames. The range is [@code{0}-@code{255}],
  6275. the default is @code{15}.
  6276. @item interp_end
  6277. Specify the end of a range where the output frame will be created as a
  6278. linear interpolation of two frames. The range is [@code{0}-@code{255}],
  6279. the default is @code{240}.
  6280. @item scene
  6281. Specify the level at which a scene change is detected as a value between
  6282. 0 and 100 to indicate a new scene; a low value reflects a low
  6283. probability for the current frame to introduce a new scene, while a higher
  6284. value means the current frame is more likely to be one.
  6285. The default is @code{7}.
  6286. @item flags
  6287. Specify flags influencing the filter process.
  6288. Available value for @var{flags} is:
  6289. @table @option
  6290. @item scene_change_detect, scd
  6291. Enable scene change detection using the value of the option @var{scene}.
  6292. This flag is enabled by default.
  6293. @end table
  6294. @end table
  6295. @section framestep
  6296. Select one frame every N-th frame.
  6297. This filter accepts the following option:
  6298. @table @option
  6299. @item step
  6300. Select frame after every @code{step} frames.
  6301. Allowed values are positive integers higher than 0. Default value is @code{1}.
  6302. @end table
  6303. @anchor{frei0r}
  6304. @section frei0r
  6305. Apply a frei0r effect to the input video.
  6306. To enable the compilation of this filter, you need to install the frei0r
  6307. header and configure FFmpeg with @code{--enable-frei0r}.
  6308. It accepts the following parameters:
  6309. @table @option
  6310. @item filter_name
  6311. The name of the frei0r effect to load. If the environment variable
  6312. @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
  6313. directories specified by the colon-separated list in @env{FREIOR_PATH}.
  6314. Otherwise, the standard frei0r paths are searched, in this order:
  6315. @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
  6316. @file{/usr/lib/frei0r-1/}.
  6317. @item filter_params
  6318. A '|'-separated list of parameters to pass to the frei0r effect.
  6319. @end table
  6320. A frei0r effect parameter can be a boolean (its value is either
  6321. "y" or "n"), a double, a color (specified as
  6322. @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
  6323. numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color"
  6324. section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where
  6325. @var{X} and @var{Y} are floating point numbers) and/or a string.
  6326. The number and types of parameters depend on the loaded effect. If an
  6327. effect parameter is not specified, the default value is set.
  6328. @subsection Examples
  6329. @itemize
  6330. @item
  6331. Apply the distort0r effect, setting the first two double parameters:
  6332. @example
  6333. frei0r=filter_name=distort0r:filter_params=0.5|0.01
  6334. @end example
  6335. @item
  6336. Apply the colordistance effect, taking a color as the first parameter:
  6337. @example
  6338. frei0r=colordistance:0.2/0.3/0.4
  6339. frei0r=colordistance:violet
  6340. frei0r=colordistance:0x112233
  6341. @end example
  6342. @item
  6343. Apply the perspective effect, specifying the top left and top right image
  6344. positions:
  6345. @example
  6346. frei0r=perspective:0.2/0.2|0.8/0.2
  6347. @end example
  6348. @end itemize
  6349. For more information, see
  6350. @url{http://frei0r.dyne.org}
  6351. @section fspp
  6352. Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
  6353. It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
  6354. processing filter, one of them is performed once per block, not per pixel.
  6355. This allows for much higher speed.
  6356. The filter accepts the following options:
  6357. @table @option
  6358. @item quality
  6359. Set quality. This option defines the number of levels for averaging. It accepts
  6360. an integer in the range 4-5. Default value is @code{4}.
  6361. @item qp
  6362. Force a constant quantization parameter. It accepts an integer in range 0-63.
  6363. If not set, the filter will use the QP from the video stream (if available).
  6364. @item strength
  6365. Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
  6366. more details but also more artifacts, while higher values make the image smoother
  6367. but also blurrier. Default value is @code{0} − PSNR optimal.
  6368. @item use_bframe_qp
  6369. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  6370. option may cause flicker since the B-Frames have often larger QP. Default is
  6371. @code{0} (not enabled).
  6372. @end table
  6373. @section gblur
  6374. Apply Gaussian blur filter.
  6375. The filter accepts the following options:
  6376. @table @option
  6377. @item sigma
  6378. Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
  6379. @item steps
  6380. Set number of steps for Gaussian approximation. Defauls is @code{1}.
  6381. @item planes
  6382. Set which planes to filter. By default all planes are filtered.
  6383. @item sigmaV
  6384. Set vertical sigma, if negative it will be same as @code{sigma}.
  6385. Default is @code{-1}.
  6386. @end table
  6387. @section geq
  6388. The filter accepts the following options:
  6389. @table @option
  6390. @item lum_expr, lum
  6391. Set the luminance expression.
  6392. @item cb_expr, cb
  6393. Set the chrominance blue expression.
  6394. @item cr_expr, cr
  6395. Set the chrominance red expression.
  6396. @item alpha_expr, a
  6397. Set the alpha expression.
  6398. @item red_expr, r
  6399. Set the red expression.
  6400. @item green_expr, g
  6401. Set the green expression.
  6402. @item blue_expr, b
  6403. Set the blue expression.
  6404. @end table
  6405. The colorspace is selected according to the specified options. If one
  6406. of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
  6407. options is specified, the filter will automatically select a YCbCr
  6408. colorspace. If one of the @option{red_expr}, @option{green_expr}, or
  6409. @option{blue_expr} options is specified, it will select an RGB
  6410. colorspace.
  6411. If one of the chrominance expression is not defined, it falls back on the other
  6412. one. If no alpha expression is specified it will evaluate to opaque value.
  6413. If none of chrominance expressions are specified, they will evaluate
  6414. to the luminance expression.
  6415. The expressions can use the following variables and functions:
  6416. @table @option
  6417. @item N
  6418. The sequential number of the filtered frame, starting from @code{0}.
  6419. @item X
  6420. @item Y
  6421. The coordinates of the current sample.
  6422. @item W
  6423. @item H
  6424. The width and height of the image.
  6425. @item SW
  6426. @item SH
  6427. Width and height scale depending on the currently filtered plane. It is the
  6428. ratio between the corresponding luma plane number of pixels and the current
  6429. plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
  6430. @code{0.5,0.5} for chroma planes.
  6431. @item T
  6432. Time of the current frame, expressed in seconds.
  6433. @item p(x, y)
  6434. Return the value of the pixel at location (@var{x},@var{y}) of the current
  6435. plane.
  6436. @item lum(x, y)
  6437. Return the value of the pixel at location (@var{x},@var{y}) of the luminance
  6438. plane.
  6439. @item cb(x, y)
  6440. Return the value of the pixel at location (@var{x},@var{y}) of the
  6441. blue-difference chroma plane. Return 0 if there is no such plane.
  6442. @item cr(x, y)
  6443. Return the value of the pixel at location (@var{x},@var{y}) of the
  6444. red-difference chroma plane. Return 0 if there is no such plane.
  6445. @item r(x, y)
  6446. @item g(x, y)
  6447. @item b(x, y)
  6448. Return the value of the pixel at location (@var{x},@var{y}) of the
  6449. red/green/blue component. Return 0 if there is no such component.
  6450. @item alpha(x, y)
  6451. Return the value of the pixel at location (@var{x},@var{y}) of the alpha
  6452. plane. Return 0 if there is no such plane.
  6453. @end table
  6454. For functions, if @var{x} and @var{y} are outside the area, the value will be
  6455. automatically clipped to the closer edge.
  6456. @subsection Examples
  6457. @itemize
  6458. @item
  6459. Flip the image horizontally:
  6460. @example
  6461. geq=p(W-X\,Y)
  6462. @end example
  6463. @item
  6464. Generate a bidimensional sine wave, with angle @code{PI/3} and a
  6465. wavelength of 100 pixels:
  6466. @example
  6467. geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
  6468. @end example
  6469. @item
  6470. Generate a fancy enigmatic moving light:
  6471. @example
  6472. 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
  6473. @end example
  6474. @item
  6475. Generate a quick emboss effect:
  6476. @example
  6477. format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
  6478. @end example
  6479. @item
  6480. Modify RGB components depending on pixel position:
  6481. @example
  6482. geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
  6483. @end example
  6484. @item
  6485. Create a radial gradient that is the same size as the input (also see
  6486. the @ref{vignette} filter):
  6487. @example
  6488. geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
  6489. @end example
  6490. @end itemize
  6491. @section gradfun
  6492. Fix the banding artifacts that are sometimes introduced into nearly flat
  6493. regions by truncation to 8-bit color depth.
  6494. Interpolate the gradients that should go where the bands are, and
  6495. dither them.
  6496. It is designed for playback only. Do not use it prior to
  6497. lossy compression, because compression tends to lose the dither and
  6498. bring back the bands.
  6499. It accepts the following parameters:
  6500. @table @option
  6501. @item strength
  6502. The maximum amount by which the filter will change any one pixel. This is also
  6503. the threshold for detecting nearly flat regions. Acceptable values range from
  6504. .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
  6505. valid range.
  6506. @item radius
  6507. The neighborhood to fit the gradient to. A larger radius makes for smoother
  6508. gradients, but also prevents the filter from modifying the pixels near detailed
  6509. regions. Acceptable values are 8-32; the default value is 16. Out-of-range
  6510. values will be clipped to the valid range.
  6511. @end table
  6512. Alternatively, the options can be specified as a flat string:
  6513. @var{strength}[:@var{radius}]
  6514. @subsection Examples
  6515. @itemize
  6516. @item
  6517. Apply the filter with a @code{3.5} strength and radius of @code{8}:
  6518. @example
  6519. gradfun=3.5:8
  6520. @end example
  6521. @item
  6522. Specify radius, omitting the strength (which will fall-back to the default
  6523. value):
  6524. @example
  6525. gradfun=radius=8
  6526. @end example
  6527. @end itemize
  6528. @anchor{haldclut}
  6529. @section haldclut
  6530. Apply a Hald CLUT to a video stream.
  6531. First input is the video stream to process, and second one is the Hald CLUT.
  6532. The Hald CLUT input can be a simple picture or a complete video stream.
  6533. The filter accepts the following options:
  6534. @table @option
  6535. @item shortest
  6536. Force termination when the shortest input terminates. Default is @code{0}.
  6537. @item repeatlast
  6538. Continue applying the last CLUT after the end of the stream. A value of
  6539. @code{0} disable the filter after the last frame of the CLUT is reached.
  6540. Default is @code{1}.
  6541. @end table
  6542. @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
  6543. filters share the same internals).
  6544. More information about the Hald CLUT can be found on Eskil Steenberg's website
  6545. (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
  6546. @subsection Workflow examples
  6547. @subsubsection Hald CLUT video stream
  6548. Generate an identity Hald CLUT stream altered with various effects:
  6549. @example
  6550. 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
  6551. @end example
  6552. Note: make sure you use a lossless codec.
  6553. Then use it with @code{haldclut} to apply it on some random stream:
  6554. @example
  6555. ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
  6556. @end example
  6557. The Hald CLUT will be applied to the 10 first seconds (duration of
  6558. @file{clut.nut}), then the latest picture of that CLUT stream will be applied
  6559. to the remaining frames of the @code{mandelbrot} stream.
  6560. @subsubsection Hald CLUT with preview
  6561. A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
  6562. @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
  6563. biggest possible square starting at the top left of the picture. The remaining
  6564. padding pixels (bottom or right) will be ignored. This area can be used to add
  6565. a preview of the Hald CLUT.
  6566. Typically, the following generated Hald CLUT will be supported by the
  6567. @code{haldclut} filter:
  6568. @example
  6569. ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
  6570. pad=iw+320 [padded_clut];
  6571. smptebars=s=320x256, split [a][b];
  6572. [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
  6573. [main][b] overlay=W-320" -frames:v 1 clut.png
  6574. @end example
  6575. It contains the original and a preview of the effect of the CLUT: SMPTE color
  6576. bars are displayed on the right-top, and below the same color bars processed by
  6577. the color changes.
  6578. Then, the effect of this Hald CLUT can be visualized with:
  6579. @example
  6580. ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
  6581. @end example
  6582. @section hflip
  6583. Flip the input video horizontally.
  6584. For example, to horizontally flip the input video with @command{ffmpeg}:
  6585. @example
  6586. ffmpeg -i in.avi -vf "hflip" out.avi
  6587. @end example
  6588. @section histeq
  6589. This filter applies a global color histogram equalization on a
  6590. per-frame basis.
  6591. It can be used to correct video that has a compressed range of pixel
  6592. intensities. The filter redistributes the pixel intensities to
  6593. equalize their distribution across the intensity range. It may be
  6594. viewed as an "automatically adjusting contrast filter". This filter is
  6595. useful only for correcting degraded or poorly captured source
  6596. video.
  6597. The filter accepts the following options:
  6598. @table @option
  6599. @item strength
  6600. Determine the amount of equalization to be applied. As the strength
  6601. is reduced, the distribution of pixel intensities more-and-more
  6602. approaches that of the input frame. The value must be a float number
  6603. in the range [0,1] and defaults to 0.200.
  6604. @item intensity
  6605. Set the maximum intensity that can generated and scale the output
  6606. values appropriately. The strength should be set as desired and then
  6607. the intensity can be limited if needed to avoid washing-out. The value
  6608. must be a float number in the range [0,1] and defaults to 0.210.
  6609. @item antibanding
  6610. Set the antibanding level. If enabled the filter will randomly vary
  6611. the luminance of output pixels by a small amount to avoid banding of
  6612. the histogram. Possible values are @code{none}, @code{weak} or
  6613. @code{strong}. It defaults to @code{none}.
  6614. @end table
  6615. @section histogram
  6616. Compute and draw a color distribution histogram for the input video.
  6617. The computed histogram is a representation of the color component
  6618. distribution in an image.
  6619. Standard histogram displays the color components distribution in an image.
  6620. Displays color graph for each color component. Shows distribution of
  6621. the Y, U, V, A or R, G, B components, depending on input format, in the
  6622. current frame. Below each graph a color component scale meter is shown.
  6623. The filter accepts the following options:
  6624. @table @option
  6625. @item level_height
  6626. Set height of level. Default value is @code{200}.
  6627. Allowed range is [50, 2048].
  6628. @item scale_height
  6629. Set height of color scale. Default value is @code{12}.
  6630. Allowed range is [0, 40].
  6631. @item display_mode
  6632. Set display mode.
  6633. It accepts the following values:
  6634. @table @samp
  6635. @item parade
  6636. Per color component graphs are placed below each other.
  6637. @item overlay
  6638. Presents information identical to that in the @code{parade}, except
  6639. that the graphs representing color components are superimposed directly
  6640. over one another.
  6641. @end table
  6642. Default is @code{parade}.
  6643. @item levels_mode
  6644. Set mode. Can be either @code{linear}, or @code{logarithmic}.
  6645. Default is @code{linear}.
  6646. @item components
  6647. Set what color components to display.
  6648. Default is @code{7}.
  6649. @item fgopacity
  6650. Set foreground opacity. Default is @code{0.7}.
  6651. @item bgopacity
  6652. Set background opacity. Default is @code{0.5}.
  6653. @end table
  6654. @subsection Examples
  6655. @itemize
  6656. @item
  6657. Calculate and draw histogram:
  6658. @example
  6659. ffplay -i input -vf histogram
  6660. @end example
  6661. @end itemize
  6662. @anchor{hqdn3d}
  6663. @section hqdn3d
  6664. This is a high precision/quality 3d denoise filter. It aims to reduce
  6665. image noise, producing smooth images and making still images really
  6666. still. It should enhance compressibility.
  6667. It accepts the following optional parameters:
  6668. @table @option
  6669. @item luma_spatial
  6670. A non-negative floating point number which specifies spatial luma strength.
  6671. It defaults to 4.0.
  6672. @item chroma_spatial
  6673. A non-negative floating point number which specifies spatial chroma strength.
  6674. It defaults to 3.0*@var{luma_spatial}/4.0.
  6675. @item luma_tmp
  6676. A floating point number which specifies luma temporal strength. It defaults to
  6677. 6.0*@var{luma_spatial}/4.0.
  6678. @item chroma_tmp
  6679. A floating point number which specifies chroma temporal strength. It defaults to
  6680. @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
  6681. @end table
  6682. @anchor{hwupload_cuda}
  6683. @section hwupload_cuda
  6684. Upload system memory frames to a CUDA device.
  6685. It accepts the following optional parameters:
  6686. @table @option
  6687. @item device
  6688. The number of the CUDA device to use
  6689. @end table
  6690. @section hqx
  6691. Apply a high-quality magnification filter designed for pixel art. This filter
  6692. was originally created by Maxim Stepin.
  6693. It accepts the following option:
  6694. @table @option
  6695. @item n
  6696. Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
  6697. @code{hq3x} and @code{4} for @code{hq4x}.
  6698. Default is @code{3}.
  6699. @end table
  6700. @section hstack
  6701. Stack input videos horizontally.
  6702. All streams must be of same pixel format and of same height.
  6703. Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
  6704. to create same output.
  6705. The filter accept the following option:
  6706. @table @option
  6707. @item inputs
  6708. Set number of input streams. Default is 2.
  6709. @item shortest
  6710. If set to 1, force the output to terminate when the shortest input
  6711. terminates. Default value is 0.
  6712. @end table
  6713. @section hue
  6714. Modify the hue and/or the saturation of the input.
  6715. It accepts the following parameters:
  6716. @table @option
  6717. @item h
  6718. Specify the hue angle as a number of degrees. It accepts an expression,
  6719. and defaults to "0".
  6720. @item s
  6721. Specify the saturation in the [-10,10] range. It accepts an expression and
  6722. defaults to "1".
  6723. @item H
  6724. Specify the hue angle as a number of radians. It accepts an
  6725. expression, and defaults to "0".
  6726. @item b
  6727. Specify the brightness in the [-10,10] range. It accepts an expression and
  6728. defaults to "0".
  6729. @end table
  6730. @option{h} and @option{H} are mutually exclusive, and can't be
  6731. specified at the same time.
  6732. The @option{b}, @option{h}, @option{H} and @option{s} option values are
  6733. expressions containing the following constants:
  6734. @table @option
  6735. @item n
  6736. frame count of the input frame starting from 0
  6737. @item pts
  6738. presentation timestamp of the input frame expressed in time base units
  6739. @item r
  6740. frame rate of the input video, NAN if the input frame rate is unknown
  6741. @item t
  6742. timestamp expressed in seconds, NAN if the input timestamp is unknown
  6743. @item tb
  6744. time base of the input video
  6745. @end table
  6746. @subsection Examples
  6747. @itemize
  6748. @item
  6749. Set the hue to 90 degrees and the saturation to 1.0:
  6750. @example
  6751. hue=h=90:s=1
  6752. @end example
  6753. @item
  6754. Same command but expressing the hue in radians:
  6755. @example
  6756. hue=H=PI/2:s=1
  6757. @end example
  6758. @item
  6759. Rotate hue and make the saturation swing between 0
  6760. and 2 over a period of 1 second:
  6761. @example
  6762. hue="H=2*PI*t: s=sin(2*PI*t)+1"
  6763. @end example
  6764. @item
  6765. Apply a 3 seconds saturation fade-in effect starting at 0:
  6766. @example
  6767. hue="s=min(t/3\,1)"
  6768. @end example
  6769. The general fade-in expression can be written as:
  6770. @example
  6771. hue="s=min(0\, max((t-START)/DURATION\, 1))"
  6772. @end example
  6773. @item
  6774. Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
  6775. @example
  6776. hue="s=max(0\, min(1\, (8-t)/3))"
  6777. @end example
  6778. The general fade-out expression can be written as:
  6779. @example
  6780. hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
  6781. @end example
  6782. @end itemize
  6783. @subsection Commands
  6784. This filter supports the following commands:
  6785. @table @option
  6786. @item b
  6787. @item s
  6788. @item h
  6789. @item H
  6790. Modify the hue and/or the saturation and/or brightness of the input video.
  6791. The command accepts the same syntax of the corresponding option.
  6792. If the specified expression is not valid, it is kept at its current
  6793. value.
  6794. @end table
  6795. @section hysteresis
  6796. Grow first stream into second stream by connecting components.
  6797. This allows to build more robust edge masks.
  6798. This filter accepts the following options:
  6799. @table @option
  6800. @item planes
  6801. Set which planes will be processed as bitmap, unprocessed planes will be
  6802. copied from first stream.
  6803. By default value 0xf, all planes will be processed.
  6804. @item threshold
  6805. Set threshold which is used in filtering. If pixel component value is higher than
  6806. this value filter algorithm for connecting components is activated.
  6807. By default value is 0.
  6808. @end table
  6809. @section idet
  6810. Detect video interlacing type.
  6811. This filter tries to detect if the input frames as interlaced, progressive,
  6812. top or bottom field first. It will also try and detect fields that are
  6813. repeated between adjacent frames (a sign of telecine).
  6814. Single frame detection considers only immediately adjacent frames when classifying each frame.
  6815. Multiple frame detection incorporates the classification history of previous frames.
  6816. The filter will log these metadata values:
  6817. @table @option
  6818. @item single.current_frame
  6819. Detected type of current frame using single-frame detection. One of:
  6820. ``tff'' (top field first), ``bff'' (bottom field first),
  6821. ``progressive'', or ``undetermined''
  6822. @item single.tff
  6823. Cumulative number of frames detected as top field first using single-frame detection.
  6824. @item multiple.tff
  6825. Cumulative number of frames detected as top field first using multiple-frame detection.
  6826. @item single.bff
  6827. Cumulative number of frames detected as bottom field first using single-frame detection.
  6828. @item multiple.current_frame
  6829. Detected type of current frame using multiple-frame detection. One of:
  6830. ``tff'' (top field first), ``bff'' (bottom field first),
  6831. ``progressive'', or ``undetermined''
  6832. @item multiple.bff
  6833. Cumulative number of frames detected as bottom field first using multiple-frame detection.
  6834. @item single.progressive
  6835. Cumulative number of frames detected as progressive using single-frame detection.
  6836. @item multiple.progressive
  6837. Cumulative number of frames detected as progressive using multiple-frame detection.
  6838. @item single.undetermined
  6839. Cumulative number of frames that could not be classified using single-frame detection.
  6840. @item multiple.undetermined
  6841. Cumulative number of frames that could not be classified using multiple-frame detection.
  6842. @item repeated.current_frame
  6843. Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
  6844. @item repeated.neither
  6845. Cumulative number of frames with no repeated field.
  6846. @item repeated.top
  6847. Cumulative number of frames with the top field repeated from the previous frame's top field.
  6848. @item repeated.bottom
  6849. Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
  6850. @end table
  6851. The filter accepts the following options:
  6852. @table @option
  6853. @item intl_thres
  6854. Set interlacing threshold.
  6855. @item prog_thres
  6856. Set progressive threshold.
  6857. @item rep_thres
  6858. Threshold for repeated field detection.
  6859. @item half_life
  6860. Number of frames after which a given frame's contribution to the
  6861. statistics is halved (i.e., it contributes only 0.5 to it's
  6862. classification). The default of 0 means that all frames seen are given
  6863. full weight of 1.0 forever.
  6864. @item analyze_interlaced_flag
  6865. When this is not 0 then idet will use the specified number of frames to determine
  6866. if the interlaced flag is accurate, it will not count undetermined frames.
  6867. If the flag is found to be accurate it will be used without any further
  6868. computations, if it is found to be inaccurate it will be cleared without any
  6869. further computations. This allows inserting the idet filter as a low computational
  6870. method to clean up the interlaced flag
  6871. @end table
  6872. @section il
  6873. Deinterleave or interleave fields.
  6874. This filter allows one to process interlaced images fields without
  6875. deinterlacing them. Deinterleaving splits the input frame into 2
  6876. fields (so called half pictures). Odd lines are moved to the top
  6877. half of the output image, even lines to the bottom half.
  6878. You can process (filter) them independently and then re-interleave them.
  6879. The filter accepts the following options:
  6880. @table @option
  6881. @item luma_mode, l
  6882. @item chroma_mode, c
  6883. @item alpha_mode, a
  6884. Available values for @var{luma_mode}, @var{chroma_mode} and
  6885. @var{alpha_mode} are:
  6886. @table @samp
  6887. @item none
  6888. Do nothing.
  6889. @item deinterleave, d
  6890. Deinterleave fields, placing one above the other.
  6891. @item interleave, i
  6892. Interleave fields. Reverse the effect of deinterleaving.
  6893. @end table
  6894. Default value is @code{none}.
  6895. @item luma_swap, ls
  6896. @item chroma_swap, cs
  6897. @item alpha_swap, as
  6898. Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
  6899. @end table
  6900. @section inflate
  6901. Apply inflate effect to the video.
  6902. This filter replaces the pixel by the local(3x3) average by taking into account
  6903. only values higher than the pixel.
  6904. It accepts the following options:
  6905. @table @option
  6906. @item threshold0
  6907. @item threshold1
  6908. @item threshold2
  6909. @item threshold3
  6910. Limit the maximum change for each plane, default is 65535.
  6911. If 0, plane will remain unchanged.
  6912. @end table
  6913. @section interlace
  6914. Simple interlacing filter from progressive contents. This interleaves upper (or
  6915. lower) lines from odd frames with lower (or upper) lines from even frames,
  6916. halving the frame rate and preserving image height.
  6917. @example
  6918. Original Original New Frame
  6919. Frame 'j' Frame 'j+1' (tff)
  6920. ========== =========== ==================
  6921. Line 0 --------------------> Frame 'j' Line 0
  6922. Line 1 Line 1 ----> Frame 'j+1' Line 1
  6923. Line 2 ---------------------> Frame 'j' Line 2
  6924. Line 3 Line 3 ----> Frame 'j+1' Line 3
  6925. ... ... ...
  6926. New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
  6927. @end example
  6928. It accepts the following optional parameters:
  6929. @table @option
  6930. @item scan
  6931. This determines whether the interlaced frame is taken from the even
  6932. (tff - default) or odd (bff) lines of the progressive frame.
  6933. @item lowpass
  6934. Enable (default) or disable the vertical lowpass filter to avoid twitter
  6935. interlacing and reduce moire patterns.
  6936. @end table
  6937. @section kerndeint
  6938. Deinterlace input video by applying Donald Graft's adaptive kernel
  6939. deinterling. Work on interlaced parts of a video to produce
  6940. progressive frames.
  6941. The description of the accepted parameters follows.
  6942. @table @option
  6943. @item thresh
  6944. Set the threshold which affects the filter's tolerance when
  6945. determining if a pixel line must be processed. It must be an integer
  6946. in the range [0,255] and defaults to 10. A value of 0 will result in
  6947. applying the process on every pixels.
  6948. @item map
  6949. Paint pixels exceeding the threshold value to white if set to 1.
  6950. Default is 0.
  6951. @item order
  6952. Set the fields order. Swap fields if set to 1, leave fields alone if
  6953. 0. Default is 0.
  6954. @item sharp
  6955. Enable additional sharpening if set to 1. Default is 0.
  6956. @item twoway
  6957. Enable twoway sharpening if set to 1. Default is 0.
  6958. @end table
  6959. @subsection Examples
  6960. @itemize
  6961. @item
  6962. Apply default values:
  6963. @example
  6964. kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
  6965. @end example
  6966. @item
  6967. Enable additional sharpening:
  6968. @example
  6969. kerndeint=sharp=1
  6970. @end example
  6971. @item
  6972. Paint processed pixels in white:
  6973. @example
  6974. kerndeint=map=1
  6975. @end example
  6976. @end itemize
  6977. @section lenscorrection
  6978. Correct radial lens distortion
  6979. This filter can be used to correct for radial distortion as can result from the use
  6980. of wide angle lenses, and thereby re-rectify the image. To find the right parameters
  6981. one can use tools available for example as part of opencv or simply trial-and-error.
  6982. To use opencv use the calibration sample (under samples/cpp) from the opencv sources
  6983. and extract the k1 and k2 coefficients from the resulting matrix.
  6984. Note that effectively the same filter is available in the open-source tools Krita and
  6985. Digikam from the KDE project.
  6986. In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
  6987. this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
  6988. brightness distribution, so you may want to use both filters together in certain
  6989. cases, though you will have to take care of ordering, i.e. whether vignetting should
  6990. be applied before or after lens correction.
  6991. @subsection Options
  6992. The filter accepts the following options:
  6993. @table @option
  6994. @item cx
  6995. Relative x-coordinate of the focal point of the image, and thereby the center of the
  6996. distortion. This value has a range [0,1] and is expressed as fractions of the image
  6997. width.
  6998. @item cy
  6999. Relative y-coordinate of the focal point of the image, and thereby the center of the
  7000. distortion. This value has a range [0,1] and is expressed as fractions of the image
  7001. height.
  7002. @item k1
  7003. Coefficient of the quadratic correction term. 0.5 means no correction.
  7004. @item k2
  7005. Coefficient of the double quadratic correction term. 0.5 means no correction.
  7006. @end table
  7007. The formula that generates the correction is:
  7008. @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)
  7009. where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
  7010. distances from the focal point in the source and target images, respectively.
  7011. @section loop
  7012. Loop video frames.
  7013. The filter accepts the following options:
  7014. @table @option
  7015. @item loop
  7016. Set the number of loops.
  7017. @item size
  7018. Set maximal size in number of frames.
  7019. @item start
  7020. Set first frame of loop.
  7021. @end table
  7022. @anchor{lut3d}
  7023. @section lut3d
  7024. Apply a 3D LUT to an input video.
  7025. The filter accepts the following options:
  7026. @table @option
  7027. @item file
  7028. Set the 3D LUT file name.
  7029. Currently supported formats:
  7030. @table @samp
  7031. @item 3dl
  7032. AfterEffects
  7033. @item cube
  7034. Iridas
  7035. @item dat
  7036. DaVinci
  7037. @item m3d
  7038. Pandora
  7039. @end table
  7040. @item interp
  7041. Select interpolation mode.
  7042. Available values are:
  7043. @table @samp
  7044. @item nearest
  7045. Use values from the nearest defined point.
  7046. @item trilinear
  7047. Interpolate values using the 8 points defining a cube.
  7048. @item tetrahedral
  7049. Interpolate values using a tetrahedron.
  7050. @end table
  7051. @end table
  7052. @section lut, lutrgb, lutyuv
  7053. Compute a look-up table for binding each pixel component input value
  7054. to an output value, and apply it to the input video.
  7055. @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
  7056. to an RGB input video.
  7057. These filters accept the following parameters:
  7058. @table @option
  7059. @item c0
  7060. set first pixel component expression
  7061. @item c1
  7062. set second pixel component expression
  7063. @item c2
  7064. set third pixel component expression
  7065. @item c3
  7066. set fourth pixel component expression, corresponds to the alpha component
  7067. @item r
  7068. set red component expression
  7069. @item g
  7070. set green component expression
  7071. @item b
  7072. set blue component expression
  7073. @item a
  7074. alpha component expression
  7075. @item y
  7076. set Y/luminance component expression
  7077. @item u
  7078. set U/Cb component expression
  7079. @item v
  7080. set V/Cr component expression
  7081. @end table
  7082. Each of them specifies the expression to use for computing the lookup table for
  7083. the corresponding pixel component values.
  7084. The exact component associated to each of the @var{c*} options depends on the
  7085. format in input.
  7086. The @var{lut} filter requires either YUV or RGB pixel formats in input,
  7087. @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
  7088. The expressions can contain the following constants and functions:
  7089. @table @option
  7090. @item w
  7091. @item h
  7092. The input width and height.
  7093. @item val
  7094. The input value for the pixel component.
  7095. @item clipval
  7096. The input value, clipped to the @var{minval}-@var{maxval} range.
  7097. @item maxval
  7098. The maximum value for the pixel component.
  7099. @item minval
  7100. The minimum value for the pixel component.
  7101. @item negval
  7102. The negated value for the pixel component value, clipped to the
  7103. @var{minval}-@var{maxval} range; it corresponds to the expression
  7104. "maxval-clipval+minval".
  7105. @item clip(val)
  7106. The computed value in @var{val}, clipped to the
  7107. @var{minval}-@var{maxval} range.
  7108. @item gammaval(gamma)
  7109. The computed gamma correction value of the pixel component value,
  7110. clipped to the @var{minval}-@var{maxval} range. It corresponds to the
  7111. expression
  7112. "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
  7113. @end table
  7114. All expressions default to "val".
  7115. @subsection Examples
  7116. @itemize
  7117. @item
  7118. Negate input video:
  7119. @example
  7120. lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
  7121. lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
  7122. @end example
  7123. The above is the same as:
  7124. @example
  7125. lutrgb="r=negval:g=negval:b=negval"
  7126. lutyuv="y=negval:u=negval:v=negval"
  7127. @end example
  7128. @item
  7129. Negate luminance:
  7130. @example
  7131. lutyuv=y=negval
  7132. @end example
  7133. @item
  7134. Remove chroma components, turning the video into a graytone image:
  7135. @example
  7136. lutyuv="u=128:v=128"
  7137. @end example
  7138. @item
  7139. Apply a luma burning effect:
  7140. @example
  7141. lutyuv="y=2*val"
  7142. @end example
  7143. @item
  7144. Remove green and blue components:
  7145. @example
  7146. lutrgb="g=0:b=0"
  7147. @end example
  7148. @item
  7149. Set a constant alpha channel value on input:
  7150. @example
  7151. format=rgba,lutrgb=a="maxval-minval/2"
  7152. @end example
  7153. @item
  7154. Correct luminance gamma by a factor of 0.5:
  7155. @example
  7156. lutyuv=y=gammaval(0.5)
  7157. @end example
  7158. @item
  7159. Discard least significant bits of luma:
  7160. @example
  7161. lutyuv=y='bitand(val, 128+64+32)'
  7162. @end example
  7163. @item
  7164. Technicolor like effect:
  7165. @example
  7166. lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
  7167. @end example
  7168. @end itemize
  7169. @section lut2
  7170. Compute and apply a lookup table from two video inputs.
  7171. This filter accepts the following parameters:
  7172. @table @option
  7173. @item c0
  7174. set first pixel component expression
  7175. @item c1
  7176. set second pixel component expression
  7177. @item c2
  7178. set third pixel component expression
  7179. @item c3
  7180. set fourth pixel component expression, corresponds to the alpha component
  7181. @end table
  7182. Each of them specifies the expression to use for computing the lookup table for
  7183. the corresponding pixel component values.
  7184. The exact component associated to each of the @var{c*} options depends on the
  7185. format in inputs.
  7186. The expressions can contain the following constants:
  7187. @table @option
  7188. @item w
  7189. @item h
  7190. The input width and height.
  7191. @item x
  7192. The first input value for the pixel component.
  7193. @item y
  7194. The second input value for the pixel component.
  7195. @item bdx
  7196. The first input video bit depth.
  7197. @item bdy
  7198. The second input video bit depth.
  7199. @end table
  7200. All expressions default to "x".
  7201. @subsection Examples
  7202. @itemize
  7203. @item
  7204. Highlight differences between two RGB video streams:
  7205. @example
  7206. lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'
  7207. @end example
  7208. @item
  7209. Highlight differences between two YUV video streams:
  7210. @example
  7211. lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'
  7212. @end example
  7213. @end itemize
  7214. @section maskedclamp
  7215. Clamp the first input stream with the second input and third input stream.
  7216. Returns the value of first stream to be between second input
  7217. stream - @code{undershoot} and third input stream + @code{overshoot}.
  7218. This filter accepts the following options:
  7219. @table @option
  7220. @item undershoot
  7221. Default value is @code{0}.
  7222. @item overshoot
  7223. Default value is @code{0}.
  7224. @item planes
  7225. Set which planes will be processed as bitmap, unprocessed planes will be
  7226. copied from first stream.
  7227. By default value 0xf, all planes will be processed.
  7228. @end table
  7229. @section maskedmerge
  7230. Merge the first input stream with the second input stream using per pixel
  7231. weights in the third input stream.
  7232. A value of 0 in the third stream pixel component means that pixel component
  7233. from first stream is returned unchanged, while maximum value (eg. 255 for
  7234. 8-bit videos) means that pixel component from second stream is returned
  7235. unchanged. Intermediate values define the amount of merging between both
  7236. input stream's pixel components.
  7237. This filter accepts the following options:
  7238. @table @option
  7239. @item planes
  7240. Set which planes will be processed as bitmap, unprocessed planes will be
  7241. copied from first stream.
  7242. By default value 0xf, all planes will be processed.
  7243. @end table
  7244. @section mcdeint
  7245. Apply motion-compensation deinterlacing.
  7246. It needs one field per frame as input and must thus be used together
  7247. with yadif=1/3 or equivalent.
  7248. This filter accepts the following options:
  7249. @table @option
  7250. @item mode
  7251. Set the deinterlacing mode.
  7252. It accepts one of the following values:
  7253. @table @samp
  7254. @item fast
  7255. @item medium
  7256. @item slow
  7257. use iterative motion estimation
  7258. @item extra_slow
  7259. like @samp{slow}, but use multiple reference frames.
  7260. @end table
  7261. Default value is @samp{fast}.
  7262. @item parity
  7263. Set the picture field parity assumed for the input video. It must be
  7264. one of the following values:
  7265. @table @samp
  7266. @item 0, tff
  7267. assume top field first
  7268. @item 1, bff
  7269. assume bottom field first
  7270. @end table
  7271. Default value is @samp{bff}.
  7272. @item qp
  7273. Set per-block quantization parameter (QP) used by the internal
  7274. encoder.
  7275. Higher values should result in a smoother motion vector field but less
  7276. optimal individual vectors. Default value is 1.
  7277. @end table
  7278. @section mergeplanes
  7279. Merge color channel components from several video streams.
  7280. The filter accepts up to 4 input streams, and merge selected input
  7281. planes to the output video.
  7282. This filter accepts the following options:
  7283. @table @option
  7284. @item mapping
  7285. Set input to output plane mapping. Default is @code{0}.
  7286. The mappings is specified as a bitmap. It should be specified as a
  7287. hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
  7288. mapping for the first plane of the output stream. 'A' sets the number of
  7289. the input stream to use (from 0 to 3), and 'a' the plane number of the
  7290. corresponding input to use (from 0 to 3). The rest of the mappings is
  7291. similar, 'Bb' describes the mapping for the output stream second
  7292. plane, 'Cc' describes the mapping for the output stream third plane and
  7293. 'Dd' describes the mapping for the output stream fourth plane.
  7294. @item format
  7295. Set output pixel format. Default is @code{yuva444p}.
  7296. @end table
  7297. @subsection Examples
  7298. @itemize
  7299. @item
  7300. Merge three gray video streams of same width and height into single video stream:
  7301. @example
  7302. [a0][a1][a2]mergeplanes=0x001020:yuv444p
  7303. @end example
  7304. @item
  7305. Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
  7306. @example
  7307. [a0][a1]mergeplanes=0x00010210:yuva444p
  7308. @end example
  7309. @item
  7310. Swap Y and A plane in yuva444p stream:
  7311. @example
  7312. format=yuva444p,mergeplanes=0x03010200:yuva444p
  7313. @end example
  7314. @item
  7315. Swap U and V plane in yuv420p stream:
  7316. @example
  7317. format=yuv420p,mergeplanes=0x000201:yuv420p
  7318. @end example
  7319. @item
  7320. Cast a rgb24 clip to yuv444p:
  7321. @example
  7322. format=rgb24,mergeplanes=0x000102:yuv444p
  7323. @end example
  7324. @end itemize
  7325. @section mestimate
  7326. Estimate and export motion vectors using block matching algorithms.
  7327. Motion vectors are stored in frame side data to be used by other filters.
  7328. This filter accepts the following options:
  7329. @table @option
  7330. @item method
  7331. Specify the motion estimation method. Accepts one of the following values:
  7332. @table @samp
  7333. @item esa
  7334. Exhaustive search algorithm.
  7335. @item tss
  7336. Three step search algorithm.
  7337. @item tdls
  7338. Two dimensional logarithmic search algorithm.
  7339. @item ntss
  7340. New three step search algorithm.
  7341. @item fss
  7342. Four step search algorithm.
  7343. @item ds
  7344. Diamond search algorithm.
  7345. @item hexbs
  7346. Hexagon-based search algorithm.
  7347. @item epzs
  7348. Enhanced predictive zonal search algorithm.
  7349. @item umh
  7350. Uneven multi-hexagon search algorithm.
  7351. @end table
  7352. Default value is @samp{esa}.
  7353. @item mb_size
  7354. Macroblock size. Default @code{16}.
  7355. @item search_param
  7356. Search parameter. Default @code{7}.
  7357. @end table
  7358. @section minterpolate
  7359. Convert the video to specified frame rate using motion interpolation.
  7360. This filter accepts the following options:
  7361. @table @option
  7362. @item fps
  7363. Specify the output frame rate. This can be rational e.g. @code{60000/1001}. Frames are dropped if @var{fps} is lower than source fps. Default @code{60}.
  7364. @item mi_mode
  7365. Motion interpolation mode. Following values are accepted:
  7366. @table @samp
  7367. @item dup
  7368. Duplicate previous or next frame for interpolating new ones.
  7369. @item blend
  7370. Blend source frames. Interpolated frame is mean of previous and next frames.
  7371. @item mci
  7372. Motion compensated interpolation. Following options are effective when this mode is selected:
  7373. @table @samp
  7374. @item mc_mode
  7375. Motion compensation mode. Following values are accepted:
  7376. @table @samp
  7377. @item obmc
  7378. Overlapped block motion compensation.
  7379. @item aobmc
  7380. Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
  7381. @end table
  7382. Default mode is @samp{obmc}.
  7383. @item me_mode
  7384. Motion estimation mode. Following values are accepted:
  7385. @table @samp
  7386. @item bidir
  7387. Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
  7388. @item bilat
  7389. Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
  7390. @end table
  7391. Default mode is @samp{bilat}.
  7392. @item me
  7393. The algorithm to be used for motion estimation. Following values are accepted:
  7394. @table @samp
  7395. @item esa
  7396. Exhaustive search algorithm.
  7397. @item tss
  7398. Three step search algorithm.
  7399. @item tdls
  7400. Two dimensional logarithmic search algorithm.
  7401. @item ntss
  7402. New three step search algorithm.
  7403. @item fss
  7404. Four step search algorithm.
  7405. @item ds
  7406. Diamond search algorithm.
  7407. @item hexbs
  7408. Hexagon-based search algorithm.
  7409. @item epzs
  7410. Enhanced predictive zonal search algorithm.
  7411. @item umh
  7412. Uneven multi-hexagon search algorithm.
  7413. @end table
  7414. Default algorithm is @samp{epzs}.
  7415. @item mb_size
  7416. Macroblock size. Default @code{16}.
  7417. @item search_param
  7418. Motion estimation search parameter. Default @code{32}.
  7419. @item vsmbc
  7420. Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make the them less blur. Default is @code{0} (disabled).
  7421. @end table
  7422. @end table
  7423. @item scd
  7424. Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted:
  7425. @table @samp
  7426. @item none
  7427. Disable scene change detection.
  7428. @item fdiff
  7429. Frame difference. Corresponding pixel values are compared and if it statisfies @var{scd_threshold} scene change is detected.
  7430. @end table
  7431. Default method is @samp{fdiff}.
  7432. @item scd_threshold
  7433. Scene change detection threshold. Default is @code{5.0}.
  7434. @end table
  7435. @section mpdecimate
  7436. Drop frames that do not differ greatly from the previous frame in
  7437. order to reduce frame rate.
  7438. The main use of this filter is for very-low-bitrate encoding
  7439. (e.g. streaming over dialup modem), but it could in theory be used for
  7440. fixing movies that were inverse-telecined incorrectly.
  7441. A description of the accepted options follows.
  7442. @table @option
  7443. @item max
  7444. Set the maximum number of consecutive frames which can be dropped (if
  7445. positive), or the minimum interval between dropped frames (if
  7446. negative). If the value is 0, the frame is dropped unregarding the
  7447. number of previous sequentially dropped frames.
  7448. Default value is 0.
  7449. @item hi
  7450. @item lo
  7451. @item frac
  7452. Set the dropping threshold values.
  7453. Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
  7454. represent actual pixel value differences, so a threshold of 64
  7455. corresponds to 1 unit of difference for each pixel, or the same spread
  7456. out differently over the block.
  7457. A frame is a candidate for dropping if no 8x8 blocks differ by more
  7458. than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
  7459. meaning the whole image) differ by more than a threshold of @option{lo}.
  7460. Default value for @option{hi} is 64*12, default value for @option{lo} is
  7461. 64*5, and default value for @option{frac} is 0.33.
  7462. @end table
  7463. @section negate
  7464. Negate input video.
  7465. It accepts an integer in input; if non-zero it negates the
  7466. alpha component (if available). The default value in input is 0.
  7467. @section nlmeans
  7468. Denoise frames using Non-Local Means algorithm.
  7469. Each pixel is adjusted by looking for other pixels with similar contexts. This
  7470. context similarity is defined by comparing their surrounding patches of size
  7471. @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
  7472. around the pixel.
  7473. Note that the research area defines centers for patches, which means some
  7474. patches will be made of pixels outside that research area.
  7475. The filter accepts the following options.
  7476. @table @option
  7477. @item s
  7478. Set denoising strength.
  7479. @item p
  7480. Set patch size.
  7481. @item pc
  7482. Same as @option{p} but for chroma planes.
  7483. The default value is @var{0} and means automatic.
  7484. @item r
  7485. Set research size.
  7486. @item rc
  7487. Same as @option{r} but for chroma planes.
  7488. The default value is @var{0} and means automatic.
  7489. @end table
  7490. @section nnedi
  7491. Deinterlace video using neural network edge directed interpolation.
  7492. This filter accepts the following options:
  7493. @table @option
  7494. @item weights
  7495. Mandatory option, without binary file filter can not work.
  7496. Currently file can be found here:
  7497. https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
  7498. @item deint
  7499. Set which frames to deinterlace, by default it is @code{all}.
  7500. Can be @code{all} or @code{interlaced}.
  7501. @item field
  7502. Set mode of operation.
  7503. Can be one of the following:
  7504. @table @samp
  7505. @item af
  7506. Use frame flags, both fields.
  7507. @item a
  7508. Use frame flags, single field.
  7509. @item t
  7510. Use top field only.
  7511. @item b
  7512. Use bottom field only.
  7513. @item tf
  7514. Use both fields, top first.
  7515. @item bf
  7516. Use both fields, bottom first.
  7517. @end table
  7518. @item planes
  7519. Set which planes to process, by default filter process all frames.
  7520. @item nsize
  7521. Set size of local neighborhood around each pixel, used by the predictor neural
  7522. network.
  7523. Can be one of the following:
  7524. @table @samp
  7525. @item s8x6
  7526. @item s16x6
  7527. @item s32x6
  7528. @item s48x6
  7529. @item s8x4
  7530. @item s16x4
  7531. @item s32x4
  7532. @end table
  7533. @item nns
  7534. Set the number of neurons in predicctor neural network.
  7535. Can be one of the following:
  7536. @table @samp
  7537. @item n16
  7538. @item n32
  7539. @item n64
  7540. @item n128
  7541. @item n256
  7542. @end table
  7543. @item qual
  7544. Controls the number of different neural network predictions that are blended
  7545. together to compute the final output value. Can be @code{fast}, default or
  7546. @code{slow}.
  7547. @item etype
  7548. Set which set of weights to use in the predictor.
  7549. Can be one of the following:
  7550. @table @samp
  7551. @item a
  7552. weights trained to minimize absolute error
  7553. @item s
  7554. weights trained to minimize squared error
  7555. @end table
  7556. @item pscrn
  7557. Controls whether or not the prescreener neural network is used to decide
  7558. which pixels should be processed by the predictor neural network and which
  7559. can be handled by simple cubic interpolation.
  7560. The prescreener is trained to know whether cubic interpolation will be
  7561. sufficient for a pixel or whether it should be predicted by the predictor nn.
  7562. The computational complexity of the prescreener nn is much less than that of
  7563. the predictor nn. Since most pixels can be handled by cubic interpolation,
  7564. using the prescreener generally results in much faster processing.
  7565. The prescreener is pretty accurate, so the difference between using it and not
  7566. using it is almost always unnoticeable.
  7567. Can be one of the following:
  7568. @table @samp
  7569. @item none
  7570. @item original
  7571. @item new
  7572. @end table
  7573. Default is @code{new}.
  7574. @item fapprox
  7575. Set various debugging flags.
  7576. @end table
  7577. @section noformat
  7578. Force libavfilter not to use any of the specified pixel formats for the
  7579. input to the next filter.
  7580. It accepts the following parameters:
  7581. @table @option
  7582. @item pix_fmts
  7583. A '|'-separated list of pixel format names, such as
  7584. apix_fmts=yuv420p|monow|rgb24".
  7585. @end table
  7586. @subsection Examples
  7587. @itemize
  7588. @item
  7589. Force libavfilter to use a format different from @var{yuv420p} for the
  7590. input to the vflip filter:
  7591. @example
  7592. noformat=pix_fmts=yuv420p,vflip
  7593. @end example
  7594. @item
  7595. Convert the input video to any of the formats not contained in the list:
  7596. @example
  7597. noformat=yuv420p|yuv444p|yuv410p
  7598. @end example
  7599. @end itemize
  7600. @section noise
  7601. Add noise on video input frame.
  7602. The filter accepts the following options:
  7603. @table @option
  7604. @item all_seed
  7605. @item c0_seed
  7606. @item c1_seed
  7607. @item c2_seed
  7608. @item c3_seed
  7609. Set noise seed for specific pixel component or all pixel components in case
  7610. of @var{all_seed}. Default value is @code{123457}.
  7611. @item all_strength, alls
  7612. @item c0_strength, c0s
  7613. @item c1_strength, c1s
  7614. @item c2_strength, c2s
  7615. @item c3_strength, c3s
  7616. Set noise strength for specific pixel component or all pixel components in case
  7617. @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
  7618. @item all_flags, allf
  7619. @item c0_flags, c0f
  7620. @item c1_flags, c1f
  7621. @item c2_flags, c2f
  7622. @item c3_flags, c3f
  7623. Set pixel component flags or set flags for all components if @var{all_flags}.
  7624. Available values for component flags are:
  7625. @table @samp
  7626. @item a
  7627. averaged temporal noise (smoother)
  7628. @item p
  7629. mix random noise with a (semi)regular pattern
  7630. @item t
  7631. temporal noise (noise pattern changes between frames)
  7632. @item u
  7633. uniform noise (gaussian otherwise)
  7634. @end table
  7635. @end table
  7636. @subsection Examples
  7637. Add temporal and uniform noise to input video:
  7638. @example
  7639. noise=alls=20:allf=t+u
  7640. @end example
  7641. @section null
  7642. Pass the video source unchanged to the output.
  7643. @section ocr
  7644. Optical Character Recognition
  7645. This filter uses Tesseract for optical character recognition.
  7646. It accepts the following options:
  7647. @table @option
  7648. @item datapath
  7649. Set datapath to tesseract data. Default is to use whatever was
  7650. set at installation.
  7651. @item language
  7652. Set language, default is "eng".
  7653. @item whitelist
  7654. Set character whitelist.
  7655. @item blacklist
  7656. Set character blacklist.
  7657. @end table
  7658. The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
  7659. @section ocv
  7660. Apply a video transform using libopencv.
  7661. To enable this filter, install the libopencv library and headers and
  7662. configure FFmpeg with @code{--enable-libopencv}.
  7663. It accepts the following parameters:
  7664. @table @option
  7665. @item filter_name
  7666. The name of the libopencv filter to apply.
  7667. @item filter_params
  7668. The parameters to pass to the libopencv filter. If not specified, the default
  7669. values are assumed.
  7670. @end table
  7671. Refer to the official libopencv documentation for more precise
  7672. information:
  7673. @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
  7674. Several libopencv filters are supported; see the following subsections.
  7675. @anchor{dilate}
  7676. @subsection dilate
  7677. Dilate an image by using a specific structuring element.
  7678. It corresponds to the libopencv function @code{cvDilate}.
  7679. It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
  7680. @var{struct_el} represents a structuring element, and has the syntax:
  7681. @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
  7682. @var{cols} and @var{rows} represent the number of columns and rows of
  7683. the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
  7684. point, and @var{shape} the shape for the structuring element. @var{shape}
  7685. must be "rect", "cross", "ellipse", or "custom".
  7686. If the value for @var{shape} is "custom", it must be followed by a
  7687. string of the form "=@var{filename}". The file with name
  7688. @var{filename} is assumed to represent a binary image, with each
  7689. printable character corresponding to a bright pixel. When a custom
  7690. @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
  7691. or columns and rows of the read file are assumed instead.
  7692. The default value for @var{struct_el} is "3x3+0x0/rect".
  7693. @var{nb_iterations} specifies the number of times the transform is
  7694. applied to the image, and defaults to 1.
  7695. Some examples:
  7696. @example
  7697. # Use the default values
  7698. ocv=dilate
  7699. # Dilate using a structuring element with a 5x5 cross, iterating two times
  7700. ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
  7701. # Read the shape from the file diamond.shape, iterating two times.
  7702. # The file diamond.shape may contain a pattern of characters like this
  7703. # *
  7704. # ***
  7705. # *****
  7706. # ***
  7707. # *
  7708. # The specified columns and rows are ignored
  7709. # but the anchor point coordinates are not
  7710. ocv=dilate:0x0+2x2/custom=diamond.shape|2
  7711. @end example
  7712. @subsection erode
  7713. Erode an image by using a specific structuring element.
  7714. It corresponds to the libopencv function @code{cvErode}.
  7715. It accepts the parameters: @var{struct_el}:@var{nb_iterations},
  7716. with the same syntax and semantics as the @ref{dilate} filter.
  7717. @subsection smooth
  7718. Smooth the input video.
  7719. The filter takes the following parameters:
  7720. @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
  7721. @var{type} is the type of smooth filter to apply, and must be one of
  7722. the following values: "blur", "blur_no_scale", "median", "gaussian",
  7723. or "bilateral". The default value is "gaussian".
  7724. The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
  7725. depend on the smooth type. @var{param1} and
  7726. @var{param2} accept integer positive values or 0. @var{param3} and
  7727. @var{param4} accept floating point values.
  7728. The default value for @var{param1} is 3. The default value for the
  7729. other parameters is 0.
  7730. These parameters correspond to the parameters assigned to the
  7731. libopencv function @code{cvSmooth}.
  7732. @anchor{overlay}
  7733. @section overlay
  7734. Overlay one video on top of another.
  7735. It takes two inputs and has one output. The first input is the "main"
  7736. video on which the second input is overlaid.
  7737. It accepts the following parameters:
  7738. A description of the accepted options follows.
  7739. @table @option
  7740. @item x
  7741. @item y
  7742. Set the expression for the x and y coordinates of the overlaid video
  7743. on the main video. Default value is "0" for both expressions. In case
  7744. the expression is invalid, it is set to a huge value (meaning that the
  7745. overlay will not be displayed within the output visible area).
  7746. @item eof_action
  7747. The action to take when EOF is encountered on the secondary input; it accepts
  7748. one of the following values:
  7749. @table @option
  7750. @item repeat
  7751. Repeat the last frame (the default).
  7752. @item endall
  7753. End both streams.
  7754. @item pass
  7755. Pass the main input through.
  7756. @end table
  7757. @item eval
  7758. Set when the expressions for @option{x}, and @option{y} are evaluated.
  7759. It accepts the following values:
  7760. @table @samp
  7761. @item init
  7762. only evaluate expressions once during the filter initialization or
  7763. when a command is processed
  7764. @item frame
  7765. evaluate expressions for each incoming frame
  7766. @end table
  7767. Default value is @samp{frame}.
  7768. @item shortest
  7769. If set to 1, force the output to terminate when the shortest input
  7770. terminates. Default value is 0.
  7771. @item format
  7772. Set the format for the output video.
  7773. It accepts the following values:
  7774. @table @samp
  7775. @item yuv420
  7776. force YUV420 output
  7777. @item yuv422
  7778. force YUV422 output
  7779. @item yuv444
  7780. force YUV444 output
  7781. @item rgb
  7782. force RGB output
  7783. @end table
  7784. Default value is @samp{yuv420}.
  7785. @item rgb @emph{(deprecated)}
  7786. If set to 1, force the filter to accept inputs in the RGB
  7787. color space. Default value is 0. This option is deprecated, use
  7788. @option{format} instead.
  7789. @item repeatlast
  7790. If set to 1, force the filter to draw the last overlay frame over the
  7791. main input until the end of the stream. A value of 0 disables this
  7792. behavior. Default value is 1.
  7793. @end table
  7794. The @option{x}, and @option{y} expressions can contain the following
  7795. parameters.
  7796. @table @option
  7797. @item main_w, W
  7798. @item main_h, H
  7799. The main input width and height.
  7800. @item overlay_w, w
  7801. @item overlay_h, h
  7802. The overlay input width and height.
  7803. @item x
  7804. @item y
  7805. The computed values for @var{x} and @var{y}. They are evaluated for
  7806. each new frame.
  7807. @item hsub
  7808. @item vsub
  7809. horizontal and vertical chroma subsample values of the output
  7810. format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
  7811. @var{vsub} is 1.
  7812. @item n
  7813. the number of input frame, starting from 0
  7814. @item pos
  7815. the position in the file of the input frame, NAN if unknown
  7816. @item t
  7817. The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
  7818. @end table
  7819. Note that the @var{n}, @var{pos}, @var{t} variables are available only
  7820. when evaluation is done @emph{per frame}, and will evaluate to NAN
  7821. when @option{eval} is set to @samp{init}.
  7822. Be aware that frames are taken from each input video in timestamp
  7823. order, hence, if their initial timestamps differ, it is a good idea
  7824. to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
  7825. have them begin in the same zero timestamp, as the example for
  7826. the @var{movie} filter does.
  7827. You can chain together more overlays but you should test the
  7828. efficiency of such approach.
  7829. @subsection Commands
  7830. This filter supports the following commands:
  7831. @table @option
  7832. @item x
  7833. @item y
  7834. Modify the x and y of the overlay input.
  7835. The command accepts the same syntax of the corresponding option.
  7836. If the specified expression is not valid, it is kept at its current
  7837. value.
  7838. @end table
  7839. @subsection Examples
  7840. @itemize
  7841. @item
  7842. Draw the overlay at 10 pixels from the bottom right corner of the main
  7843. video:
  7844. @example
  7845. overlay=main_w-overlay_w-10:main_h-overlay_h-10
  7846. @end example
  7847. Using named options the example above becomes:
  7848. @example
  7849. overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
  7850. @end example
  7851. @item
  7852. Insert a transparent PNG logo in the bottom left corner of the input,
  7853. using the @command{ffmpeg} tool with the @code{-filter_complex} option:
  7854. @example
  7855. ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
  7856. @end example
  7857. @item
  7858. Insert 2 different transparent PNG logos (second logo on bottom
  7859. right corner) using the @command{ffmpeg} tool:
  7860. @example
  7861. 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
  7862. @end example
  7863. @item
  7864. Add a transparent color layer on top of the main video; @code{WxH}
  7865. must specify the size of the main input to the overlay filter:
  7866. @example
  7867. color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
  7868. @end example
  7869. @item
  7870. Play an original video and a filtered version (here with the deshake
  7871. filter) side by side using the @command{ffplay} tool:
  7872. @example
  7873. ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
  7874. @end example
  7875. The above command is the same as:
  7876. @example
  7877. ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
  7878. @end example
  7879. @item
  7880. Make a sliding overlay appearing from the left to the right top part of the
  7881. screen starting since time 2:
  7882. @example
  7883. overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
  7884. @end example
  7885. @item
  7886. Compose output by putting two input videos side to side:
  7887. @example
  7888. ffmpeg -i left.avi -i right.avi -filter_complex "
  7889. nullsrc=size=200x100 [background];
  7890. [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
  7891. [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
  7892. [background][left] overlay=shortest=1 [background+left];
  7893. [background+left][right] overlay=shortest=1:x=100 [left+right]
  7894. "
  7895. @end example
  7896. @item
  7897. Mask 10-20 seconds of a video by applying the delogo filter to a section
  7898. @example
  7899. ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
  7900. -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]'
  7901. masked.avi
  7902. @end example
  7903. @item
  7904. Chain several overlays in cascade:
  7905. @example
  7906. nullsrc=s=200x200 [bg];
  7907. testsrc=s=100x100, split=4 [in0][in1][in2][in3];
  7908. [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
  7909. [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
  7910. [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
  7911. [in3] null, [mid2] overlay=100:100 [out0]
  7912. @end example
  7913. @end itemize
  7914. @section owdenoise
  7915. Apply Overcomplete Wavelet denoiser.
  7916. The filter accepts the following options:
  7917. @table @option
  7918. @item depth
  7919. Set depth.
  7920. Larger depth values will denoise lower frequency components more, but
  7921. slow down filtering.
  7922. Must be an int in the range 8-16, default is @code{8}.
  7923. @item luma_strength, ls
  7924. Set luma strength.
  7925. Must be a double value in the range 0-1000, default is @code{1.0}.
  7926. @item chroma_strength, cs
  7927. Set chroma strength.
  7928. Must be a double value in the range 0-1000, default is @code{1.0}.
  7929. @end table
  7930. @anchor{pad}
  7931. @section pad
  7932. Add paddings to the input image, and place the original input at the
  7933. provided @var{x}, @var{y} coordinates.
  7934. It accepts the following parameters:
  7935. @table @option
  7936. @item width, w
  7937. @item height, h
  7938. Specify an expression for the size of the output image with the
  7939. paddings added. If the value for @var{width} or @var{height} is 0, the
  7940. corresponding input size is used for the output.
  7941. The @var{width} expression can reference the value set by the
  7942. @var{height} expression, and vice versa.
  7943. The default value of @var{width} and @var{height} is 0.
  7944. @item x
  7945. @item y
  7946. Specify the offsets to place the input image at within the padded area,
  7947. with respect to the top/left border of the output image.
  7948. The @var{x} expression can reference the value set by the @var{y}
  7949. expression, and vice versa.
  7950. The default value of @var{x} and @var{y} is 0.
  7951. @item color
  7952. Specify the color of the padded area. For the syntax of this option,
  7953. check the "Color" section in the ffmpeg-utils manual.
  7954. The default value of @var{color} is "black".
  7955. @end table
  7956. The value for the @var{width}, @var{height}, @var{x}, and @var{y}
  7957. options are expressions containing the following constants:
  7958. @table @option
  7959. @item in_w
  7960. @item in_h
  7961. The input video width and height.
  7962. @item iw
  7963. @item ih
  7964. These are the same as @var{in_w} and @var{in_h}.
  7965. @item out_w
  7966. @item out_h
  7967. The output width and height (the size of the padded area), as
  7968. specified by the @var{width} and @var{height} expressions.
  7969. @item ow
  7970. @item oh
  7971. These are the same as @var{out_w} and @var{out_h}.
  7972. @item x
  7973. @item y
  7974. The x and y offsets as specified by the @var{x} and @var{y}
  7975. expressions, or NAN if not yet specified.
  7976. @item a
  7977. same as @var{iw} / @var{ih}
  7978. @item sar
  7979. input sample aspect ratio
  7980. @item dar
  7981. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  7982. @item hsub
  7983. @item vsub
  7984. The horizontal and vertical chroma subsample values. For example for the
  7985. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  7986. @end table
  7987. @subsection Examples
  7988. @itemize
  7989. @item
  7990. Add paddings with the color "violet" to the input video. The output video
  7991. size is 640x480, and the top-left corner of the input video is placed at
  7992. column 0, row 40
  7993. @example
  7994. pad=640:480:0:40:violet
  7995. @end example
  7996. The example above is equivalent to the following command:
  7997. @example
  7998. pad=width=640:height=480:x=0:y=40:color=violet
  7999. @end example
  8000. @item
  8001. Pad the input to get an output with dimensions increased by 3/2,
  8002. and put the input video at the center of the padded area:
  8003. @example
  8004. pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
  8005. @end example
  8006. @item
  8007. Pad the input to get a squared output with size equal to the maximum
  8008. value between the input width and height, and put the input video at
  8009. the center of the padded area:
  8010. @example
  8011. pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
  8012. @end example
  8013. @item
  8014. Pad the input to get a final w/h ratio of 16:9:
  8015. @example
  8016. pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
  8017. @end example
  8018. @item
  8019. In case of anamorphic video, in order to set the output display aspect
  8020. correctly, it is necessary to use @var{sar} in the expression,
  8021. according to the relation:
  8022. @example
  8023. (ih * X / ih) * sar = output_dar
  8024. X = output_dar / sar
  8025. @end example
  8026. Thus the previous example needs to be modified to:
  8027. @example
  8028. pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
  8029. @end example
  8030. @item
  8031. Double the output size and put the input video in the bottom-right
  8032. corner of the output padded area:
  8033. @example
  8034. pad="2*iw:2*ih:ow-iw:oh-ih"
  8035. @end example
  8036. @end itemize
  8037. @anchor{palettegen}
  8038. @section palettegen
  8039. Generate one palette for a whole video stream.
  8040. It accepts the following options:
  8041. @table @option
  8042. @item max_colors
  8043. Set the maximum number of colors to quantize in the palette.
  8044. Note: the palette will still contain 256 colors; the unused palette entries
  8045. will be black.
  8046. @item reserve_transparent
  8047. Create a palette of 255 colors maximum and reserve the last one for
  8048. transparency. Reserving the transparency color is useful for GIF optimization.
  8049. If not set, the maximum of colors in the palette will be 256. You probably want
  8050. to disable this option for a standalone image.
  8051. Set by default.
  8052. @item stats_mode
  8053. Set statistics mode.
  8054. It accepts the following values:
  8055. @table @samp
  8056. @item full
  8057. Compute full frame histograms.
  8058. @item diff
  8059. Compute histograms only for the part that differs from previous frame. This
  8060. might be relevant to give more importance to the moving part of your input if
  8061. the background is static.
  8062. @item single
  8063. Compute new histogram for each frame.
  8064. @end table
  8065. Default value is @var{full}.
  8066. @end table
  8067. The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
  8068. (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
  8069. color quantization of the palette. This information is also visible at
  8070. @var{info} logging level.
  8071. @subsection Examples
  8072. @itemize
  8073. @item
  8074. Generate a representative palette of a given video using @command{ffmpeg}:
  8075. @example
  8076. ffmpeg -i input.mkv -vf palettegen palette.png
  8077. @end example
  8078. @end itemize
  8079. @section paletteuse
  8080. Use a palette to downsample an input video stream.
  8081. The filter takes two inputs: one video stream and a palette. The palette must
  8082. be a 256 pixels image.
  8083. It accepts the following options:
  8084. @table @option
  8085. @item dither
  8086. Select dithering mode. Available algorithms are:
  8087. @table @samp
  8088. @item bayer
  8089. Ordered 8x8 bayer dithering (deterministic)
  8090. @item heckbert
  8091. Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
  8092. Note: this dithering is sometimes considered "wrong" and is included as a
  8093. reference.
  8094. @item floyd_steinberg
  8095. Floyd and Steingberg dithering (error diffusion)
  8096. @item sierra2
  8097. Frankie Sierra dithering v2 (error diffusion)
  8098. @item sierra2_4a
  8099. Frankie Sierra dithering v2 "Lite" (error diffusion)
  8100. @end table
  8101. Default is @var{sierra2_4a}.
  8102. @item bayer_scale
  8103. When @var{bayer} dithering is selected, this option defines the scale of the
  8104. pattern (how much the crosshatch pattern is visible). A low value means more
  8105. visible pattern for less banding, and higher value means less visible pattern
  8106. at the cost of more banding.
  8107. The option must be an integer value in the range [0,5]. Default is @var{2}.
  8108. @item diff_mode
  8109. If set, define the zone to process
  8110. @table @samp
  8111. @item rectangle
  8112. Only the changing rectangle will be reprocessed. This is similar to GIF
  8113. cropping/offsetting compression mechanism. This option can be useful for speed
  8114. if only a part of the image is changing, and has use cases such as limiting the
  8115. scope of the error diffusal @option{dither} to the rectangle that bounds the
  8116. moving scene (it leads to more deterministic output if the scene doesn't change
  8117. much, and as a result less moving noise and better GIF compression).
  8118. @end table
  8119. Default is @var{none}.
  8120. @item new
  8121. Take new palette for each output frame.
  8122. @end table
  8123. @subsection Examples
  8124. @itemize
  8125. @item
  8126. Use a palette (generated for example with @ref{palettegen}) to encode a GIF
  8127. using @command{ffmpeg}:
  8128. @example
  8129. ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
  8130. @end example
  8131. @end itemize
  8132. @section perspective
  8133. Correct perspective of video not recorded perpendicular to the screen.
  8134. A description of the accepted parameters follows.
  8135. @table @option
  8136. @item x0
  8137. @item y0
  8138. @item x1
  8139. @item y1
  8140. @item x2
  8141. @item y2
  8142. @item x3
  8143. @item y3
  8144. Set coordinates expression for top left, top right, bottom left and bottom right corners.
  8145. Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
  8146. If the @code{sense} option is set to @code{source}, then the specified points will be sent
  8147. to the corners of the destination. If the @code{sense} option is set to @code{destination},
  8148. then the corners of the source will be sent to the specified coordinates.
  8149. The expressions can use the following variables:
  8150. @table @option
  8151. @item W
  8152. @item H
  8153. the width and height of video frame.
  8154. @item in
  8155. Input frame count.
  8156. @item on
  8157. Output frame count.
  8158. @end table
  8159. @item interpolation
  8160. Set interpolation for perspective correction.
  8161. It accepts the following values:
  8162. @table @samp
  8163. @item linear
  8164. @item cubic
  8165. @end table
  8166. Default value is @samp{linear}.
  8167. @item sense
  8168. Set interpretation of coordinate options.
  8169. It accepts the following values:
  8170. @table @samp
  8171. @item 0, source
  8172. Send point in the source specified by the given coordinates to
  8173. the corners of the destination.
  8174. @item 1, destination
  8175. Send the corners of the source to the point in the destination specified
  8176. by the given coordinates.
  8177. Default value is @samp{source}.
  8178. @end table
  8179. @item eval
  8180. Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
  8181. It accepts the following values:
  8182. @table @samp
  8183. @item init
  8184. only evaluate expressions once during the filter initialization or
  8185. when a command is processed
  8186. @item frame
  8187. evaluate expressions for each incoming frame
  8188. @end table
  8189. Default value is @samp{init}.
  8190. @end table
  8191. @section phase
  8192. Delay interlaced video by one field time so that the field order changes.
  8193. The intended use is to fix PAL movies that have been captured with the
  8194. opposite field order to the film-to-video transfer.
  8195. A description of the accepted parameters follows.
  8196. @table @option
  8197. @item mode
  8198. Set phase mode.
  8199. It accepts the following values:
  8200. @table @samp
  8201. @item t
  8202. Capture field order top-first, transfer bottom-first.
  8203. Filter will delay the bottom field.
  8204. @item b
  8205. Capture field order bottom-first, transfer top-first.
  8206. Filter will delay the top field.
  8207. @item p
  8208. Capture and transfer with the same field order. This mode only exists
  8209. for the documentation of the other options to refer to, but if you
  8210. actually select it, the filter will faithfully do nothing.
  8211. @item a
  8212. Capture field order determined automatically by field flags, transfer
  8213. opposite.
  8214. Filter selects among @samp{t} and @samp{b} modes on a frame by frame
  8215. basis using field flags. If no field information is available,
  8216. then this works just like @samp{u}.
  8217. @item u
  8218. Capture unknown or varying, transfer opposite.
  8219. Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
  8220. analyzing the images and selecting the alternative that produces best
  8221. match between the fields.
  8222. @item T
  8223. Capture top-first, transfer unknown or varying.
  8224. Filter selects among @samp{t} and @samp{p} using image analysis.
  8225. @item B
  8226. Capture bottom-first, transfer unknown or varying.
  8227. Filter selects among @samp{b} and @samp{p} using image analysis.
  8228. @item A
  8229. Capture determined by field flags, transfer unknown or varying.
  8230. Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
  8231. image analysis. If no field information is available, then this works just
  8232. like @samp{U}. This is the default mode.
  8233. @item U
  8234. Both capture and transfer unknown or varying.
  8235. Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
  8236. @end table
  8237. @end table
  8238. @section pixdesctest
  8239. Pixel format descriptor test filter, mainly useful for internal
  8240. testing. The output video should be equal to the input video.
  8241. For example:
  8242. @example
  8243. format=monow, pixdesctest
  8244. @end example
  8245. can be used to test the monowhite pixel format descriptor definition.
  8246. @section pp
  8247. Enable the specified chain of postprocessing subfilters using libpostproc. This
  8248. library should be automatically selected with a GPL build (@code{--enable-gpl}).
  8249. Subfilters must be separated by '/' and can be disabled by prepending a '-'.
  8250. Each subfilter and some options have a short and a long name that can be used
  8251. interchangeably, i.e. dr/dering are the same.
  8252. The filters accept the following options:
  8253. @table @option
  8254. @item subfilters
  8255. Set postprocessing subfilters string.
  8256. @end table
  8257. All subfilters share common options to determine their scope:
  8258. @table @option
  8259. @item a/autoq
  8260. Honor the quality commands for this subfilter.
  8261. @item c/chrom
  8262. Do chrominance filtering, too (default).
  8263. @item y/nochrom
  8264. Do luminance filtering only (no chrominance).
  8265. @item n/noluma
  8266. Do chrominance filtering only (no luminance).
  8267. @end table
  8268. These options can be appended after the subfilter name, separated by a '|'.
  8269. Available subfilters are:
  8270. @table @option
  8271. @item hb/hdeblock[|difference[|flatness]]
  8272. Horizontal deblocking filter
  8273. @table @option
  8274. @item difference
  8275. Difference factor where higher values mean more deblocking (default: @code{32}).
  8276. @item flatness
  8277. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  8278. @end table
  8279. @item vb/vdeblock[|difference[|flatness]]
  8280. Vertical deblocking filter
  8281. @table @option
  8282. @item difference
  8283. Difference factor where higher values mean more deblocking (default: @code{32}).
  8284. @item flatness
  8285. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  8286. @end table
  8287. @item ha/hadeblock[|difference[|flatness]]
  8288. Accurate horizontal deblocking filter
  8289. @table @option
  8290. @item difference
  8291. Difference factor where higher values mean more deblocking (default: @code{32}).
  8292. @item flatness
  8293. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  8294. @end table
  8295. @item va/vadeblock[|difference[|flatness]]
  8296. Accurate vertical deblocking filter
  8297. @table @option
  8298. @item difference
  8299. Difference factor where higher values mean more deblocking (default: @code{32}).
  8300. @item flatness
  8301. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  8302. @end table
  8303. @end table
  8304. The horizontal and vertical deblocking filters share the difference and
  8305. flatness values so you cannot set different horizontal and vertical
  8306. thresholds.
  8307. @table @option
  8308. @item h1/x1hdeblock
  8309. Experimental horizontal deblocking filter
  8310. @item v1/x1vdeblock
  8311. Experimental vertical deblocking filter
  8312. @item dr/dering
  8313. Deringing filter
  8314. @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
  8315. @table @option
  8316. @item threshold1
  8317. larger -> stronger filtering
  8318. @item threshold2
  8319. larger -> stronger filtering
  8320. @item threshold3
  8321. larger -> stronger filtering
  8322. @end table
  8323. @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
  8324. @table @option
  8325. @item f/fullyrange
  8326. Stretch luminance to @code{0-255}.
  8327. @end table
  8328. @item lb/linblenddeint
  8329. Linear blend deinterlacing filter that deinterlaces the given block by
  8330. filtering all lines with a @code{(1 2 1)} filter.
  8331. @item li/linipoldeint
  8332. Linear interpolating deinterlacing filter that deinterlaces the given block by
  8333. linearly interpolating every second line.
  8334. @item ci/cubicipoldeint
  8335. Cubic interpolating deinterlacing filter deinterlaces the given block by
  8336. cubically interpolating every second line.
  8337. @item md/mediandeint
  8338. Median deinterlacing filter that deinterlaces the given block by applying a
  8339. median filter to every second line.
  8340. @item fd/ffmpegdeint
  8341. FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
  8342. second line with a @code{(-1 4 2 4 -1)} filter.
  8343. @item l5/lowpass5
  8344. Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
  8345. block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
  8346. @item fq/forceQuant[|quantizer]
  8347. Overrides the quantizer table from the input with the constant quantizer you
  8348. specify.
  8349. @table @option
  8350. @item quantizer
  8351. Quantizer to use
  8352. @end table
  8353. @item de/default
  8354. Default pp filter combination (@code{hb|a,vb|a,dr|a})
  8355. @item fa/fast
  8356. Fast pp filter combination (@code{h1|a,v1|a,dr|a})
  8357. @item ac
  8358. High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
  8359. @end table
  8360. @subsection Examples
  8361. @itemize
  8362. @item
  8363. Apply horizontal and vertical deblocking, deringing and automatic
  8364. brightness/contrast:
  8365. @example
  8366. pp=hb/vb/dr/al
  8367. @end example
  8368. @item
  8369. Apply default filters without brightness/contrast correction:
  8370. @example
  8371. pp=de/-al
  8372. @end example
  8373. @item
  8374. Apply default filters and temporal denoiser:
  8375. @example
  8376. pp=default/tmpnoise|1|2|3
  8377. @end example
  8378. @item
  8379. Apply deblocking on luminance only, and switch vertical deblocking on or off
  8380. automatically depending on available CPU time:
  8381. @example
  8382. pp=hb|y/vb|a
  8383. @end example
  8384. @end itemize
  8385. @section pp7
  8386. Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
  8387. similar to spp = 6 with 7 point DCT, where only the center sample is
  8388. used after IDCT.
  8389. The filter accepts the following options:
  8390. @table @option
  8391. @item qp
  8392. Force a constant quantization parameter. It accepts an integer in range
  8393. 0 to 63. If not set, the filter will use the QP from the video stream
  8394. (if available).
  8395. @item mode
  8396. Set thresholding mode. Available modes are:
  8397. @table @samp
  8398. @item hard
  8399. Set hard thresholding.
  8400. @item soft
  8401. Set soft thresholding (better de-ringing effect, but likely blurrier).
  8402. @item medium
  8403. Set medium thresholding (good results, default).
  8404. @end table
  8405. @end table
  8406. @section prewitt
  8407. Apply prewitt operator to input video stream.
  8408. The filter accepts the following option:
  8409. @table @option
  8410. @item planes
  8411. Set which planes will be processed, unprocessed planes will be copied.
  8412. By default value 0xf, all planes will be processed.
  8413. @item scale
  8414. Set value which will be multiplied with filtered result.
  8415. @item delta
  8416. Set value which will be added to filtered result.
  8417. @end table
  8418. @section psnr
  8419. Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
  8420. Ratio) between two input videos.
  8421. This filter takes in input two input videos, the first input is
  8422. considered the "main" source and is passed unchanged to the
  8423. output. The second input is used as a "reference" video for computing
  8424. the PSNR.
  8425. Both video inputs must have the same resolution and pixel format for
  8426. this filter to work correctly. Also it assumes that both inputs
  8427. have the same number of frames, which are compared one by one.
  8428. The obtained average PSNR is printed through the logging system.
  8429. The filter stores the accumulated MSE (mean squared error) of each
  8430. frame, and at the end of the processing it is averaged across all frames
  8431. equally, and the following formula is applied to obtain the PSNR:
  8432. @example
  8433. PSNR = 10*log10(MAX^2/MSE)
  8434. @end example
  8435. Where MAX is the average of the maximum values of each component of the
  8436. image.
  8437. The description of the accepted parameters follows.
  8438. @table @option
  8439. @item stats_file, f
  8440. If specified the filter will use the named file to save the PSNR of
  8441. each individual frame. When filename equals "-" the data is sent to
  8442. standard output.
  8443. @item stats_version
  8444. Specifies which version of the stats file format to use. Details of
  8445. each format are written below.
  8446. Default value is 1.
  8447. @item stats_add_max
  8448. Determines whether the max value is output to the stats log.
  8449. Default value is 0.
  8450. Requires stats_version >= 2. If this is set and stats_version < 2,
  8451. the filter will return an error.
  8452. @end table
  8453. The file printed if @var{stats_file} is selected, contains a sequence of
  8454. key/value pairs of the form @var{key}:@var{value} for each compared
  8455. couple of frames.
  8456. If a @var{stats_version} greater than 1 is specified, a header line precedes
  8457. the list of per-frame-pair stats, with key value pairs following the frame
  8458. format with the following parameters:
  8459. @table @option
  8460. @item psnr_log_version
  8461. The version of the log file format. Will match @var{stats_version}.
  8462. @item fields
  8463. A comma separated list of the per-frame-pair parameters included in
  8464. the log.
  8465. @end table
  8466. A description of each shown per-frame-pair parameter follows:
  8467. @table @option
  8468. @item n
  8469. sequential number of the input frame, starting from 1
  8470. @item mse_avg
  8471. Mean Square Error pixel-by-pixel average difference of the compared
  8472. frames, averaged over all the image components.
  8473. @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a
  8474. Mean Square Error pixel-by-pixel average difference of the compared
  8475. frames for the component specified by the suffix.
  8476. @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
  8477. Peak Signal to Noise ratio of the compared frames for the component
  8478. specified by the suffix.
  8479. @item max_avg, max_y, max_u, max_v
  8480. Maximum allowed value for each channel, and average over all
  8481. channels.
  8482. @end table
  8483. For example:
  8484. @example
  8485. movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
  8486. [main][ref] psnr="stats_file=stats.log" [out]
  8487. @end example
  8488. On this example the input file being processed is compared with the
  8489. reference file @file{ref_movie.mpg}. The PSNR of each individual frame
  8490. is stored in @file{stats.log}.
  8491. @anchor{pullup}
  8492. @section pullup
  8493. Pulldown reversal (inverse telecine) filter, capable of handling mixed
  8494. hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
  8495. content.
  8496. The pullup filter is designed to take advantage of future context in making
  8497. its decisions. This filter is stateless in the sense that it does not lock
  8498. onto a pattern to follow, but it instead looks forward to the following
  8499. fields in order to identify matches and rebuild progressive frames.
  8500. To produce content with an even framerate, insert the fps filter after
  8501. pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
  8502. @code{fps=24} for 30fps and the (rare) telecined 25fps input.
  8503. The filter accepts the following options:
  8504. @table @option
  8505. @item jl
  8506. @item jr
  8507. @item jt
  8508. @item jb
  8509. These options set the amount of "junk" to ignore at the left, right, top, and
  8510. bottom of the image, respectively. Left and right are in units of 8 pixels,
  8511. while top and bottom are in units of 2 lines.
  8512. The default is 8 pixels on each side.
  8513. @item sb
  8514. Set the strict breaks. Setting this option to 1 will reduce the chances of
  8515. filter generating an occasional mismatched frame, but it may also cause an
  8516. excessive number of frames to be dropped during high motion sequences.
  8517. Conversely, setting it to -1 will make filter match fields more easily.
  8518. This may help processing of video where there is slight blurring between
  8519. the fields, but may also cause there to be interlaced frames in the output.
  8520. Default value is @code{0}.
  8521. @item mp
  8522. Set the metric plane to use. It accepts the following values:
  8523. @table @samp
  8524. @item l
  8525. Use luma plane.
  8526. @item u
  8527. Use chroma blue plane.
  8528. @item v
  8529. Use chroma red plane.
  8530. @end table
  8531. This option may be set to use chroma plane instead of the default luma plane
  8532. for doing filter's computations. This may improve accuracy on very clean
  8533. source material, but more likely will decrease accuracy, especially if there
  8534. is chroma noise (rainbow effect) or any grayscale video.
  8535. The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
  8536. load and make pullup usable in realtime on slow machines.
  8537. @end table
  8538. For best results (without duplicated frames in the output file) it is
  8539. necessary to change the output frame rate. For example, to inverse
  8540. telecine NTSC input:
  8541. @example
  8542. ffmpeg -i input -vf pullup -r 24000/1001 ...
  8543. @end example
  8544. @section qp
  8545. Change video quantization parameters (QP).
  8546. The filter accepts the following option:
  8547. @table @option
  8548. @item qp
  8549. Set expression for quantization parameter.
  8550. @end table
  8551. The expression is evaluated through the eval API and can contain, among others,
  8552. the following constants:
  8553. @table @var
  8554. @item known
  8555. 1 if index is not 129, 0 otherwise.
  8556. @item qp
  8557. Sequentional index starting from -129 to 128.
  8558. @end table
  8559. @subsection Examples
  8560. @itemize
  8561. @item
  8562. Some equation like:
  8563. @example
  8564. qp=2+2*sin(PI*qp)
  8565. @end example
  8566. @end itemize
  8567. @section random
  8568. Flush video frames from internal cache of frames into a random order.
  8569. No frame is discarded.
  8570. Inspired by @ref{frei0r} nervous filter.
  8571. @table @option
  8572. @item frames
  8573. Set size in number of frames of internal cache, in range from @code{2} to
  8574. @code{512}. Default is @code{30}.
  8575. @item seed
  8576. Set seed for random number generator, must be an integer included between
  8577. @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
  8578. less than @code{0}, the filter will try to use a good random seed on a
  8579. best effort basis.
  8580. @end table
  8581. @section readvitc
  8582. Read vertical interval timecode (VITC) information from the top lines of a
  8583. video frame.
  8584. The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
  8585. timecode value, if a valid timecode has been detected. Further metadata key
  8586. @code{lavfi.readvitc.found} is set to 0/1 depending on whether
  8587. timecode data has been found or not.
  8588. This filter accepts the following options:
  8589. @table @option
  8590. @item scan_max
  8591. Set the maximum number of lines to scan for VITC data. If the value is set to
  8592. @code{-1} the full video frame is scanned. Default is @code{45}.
  8593. @item thr_b
  8594. Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
  8595. default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
  8596. @item thr_w
  8597. Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
  8598. default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
  8599. @end table
  8600. @subsection Examples
  8601. @itemize
  8602. @item
  8603. Detect and draw VITC data onto the video frame; if no valid VITC is detected,
  8604. draw @code{--:--:--:--} as a placeholder:
  8605. @example
  8606. ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
  8607. @end example
  8608. @end itemize
  8609. @section remap
  8610. Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
  8611. Destination pixel at position (X, Y) will be picked from source (x, y) position
  8612. where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
  8613. value for pixel will be used for destination pixel.
  8614. Xmap and Ymap input video streams must be of same dimensions. Output video stream
  8615. will have Xmap/Ymap video stream dimensions.
  8616. Xmap and Ymap input video streams are 16bit depth, single channel.
  8617. @section removegrain
  8618. The removegrain filter is a spatial denoiser for progressive video.
  8619. @table @option
  8620. @item m0
  8621. Set mode for the first plane.
  8622. @item m1
  8623. Set mode for the second plane.
  8624. @item m2
  8625. Set mode for the third plane.
  8626. @item m3
  8627. Set mode for the fourth plane.
  8628. @end table
  8629. Range of mode is from 0 to 24. Description of each mode follows:
  8630. @table @var
  8631. @item 0
  8632. Leave input plane unchanged. Default.
  8633. @item 1
  8634. Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
  8635. @item 2
  8636. Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
  8637. @item 3
  8638. Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
  8639. @item 4
  8640. Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
  8641. This is equivalent to a median filter.
  8642. @item 5
  8643. Line-sensitive clipping giving the minimal change.
  8644. @item 6
  8645. Line-sensitive clipping, intermediate.
  8646. @item 7
  8647. Line-sensitive clipping, intermediate.
  8648. @item 8
  8649. Line-sensitive clipping, intermediate.
  8650. @item 9
  8651. Line-sensitive clipping on a line where the neighbours pixels are the closest.
  8652. @item 10
  8653. Replaces the target pixel with the closest neighbour.
  8654. @item 11
  8655. [1 2 1] horizontal and vertical kernel blur.
  8656. @item 12
  8657. Same as mode 11.
  8658. @item 13
  8659. Bob mode, interpolates top field from the line where the neighbours
  8660. pixels are the closest.
  8661. @item 14
  8662. Bob mode, interpolates bottom field from the line where the neighbours
  8663. pixels are the closest.
  8664. @item 15
  8665. Bob mode, interpolates top field. Same as 13 but with a more complicated
  8666. interpolation formula.
  8667. @item 16
  8668. Bob mode, interpolates bottom field. Same as 14 but with a more complicated
  8669. interpolation formula.
  8670. @item 17
  8671. Clips the pixel with the minimum and maximum of respectively the maximum and
  8672. minimum of each pair of opposite neighbour pixels.
  8673. @item 18
  8674. Line-sensitive clipping using opposite neighbours whose greatest distance from
  8675. the current pixel is minimal.
  8676. @item 19
  8677. Replaces the pixel with the average of its 8 neighbours.
  8678. @item 20
  8679. Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
  8680. @item 21
  8681. Clips pixels using the averages of opposite neighbour.
  8682. @item 22
  8683. Same as mode 21 but simpler and faster.
  8684. @item 23
  8685. Small edge and halo removal, but reputed useless.
  8686. @item 24
  8687. Similar as 23.
  8688. @end table
  8689. @section removelogo
  8690. Suppress a TV station logo, using an image file to determine which
  8691. pixels comprise the logo. It works by filling in the pixels that
  8692. comprise the logo with neighboring pixels.
  8693. The filter accepts the following options:
  8694. @table @option
  8695. @item filename, f
  8696. Set the filter bitmap file, which can be any image format supported by
  8697. libavformat. The width and height of the image file must match those of the
  8698. video stream being processed.
  8699. @end table
  8700. Pixels in the provided bitmap image with a value of zero are not
  8701. considered part of the logo, non-zero pixels are considered part of
  8702. the logo. If you use white (255) for the logo and black (0) for the
  8703. rest, you will be safe. For making the filter bitmap, it is
  8704. recommended to take a screen capture of a black frame with the logo
  8705. visible, and then using a threshold filter followed by the erode
  8706. filter once or twice.
  8707. If needed, little splotches can be fixed manually. Remember that if
  8708. logo pixels are not covered, the filter quality will be much
  8709. reduced. Marking too many pixels as part of the logo does not hurt as
  8710. much, but it will increase the amount of blurring needed to cover over
  8711. the image and will destroy more information than necessary, and extra
  8712. pixels will slow things down on a large logo.
  8713. @section repeatfields
  8714. This filter uses the repeat_field flag from the Video ES headers and hard repeats
  8715. fields based on its value.
  8716. @section reverse
  8717. Reverse a video clip.
  8718. Warning: This filter requires memory to buffer the entire clip, so trimming
  8719. is suggested.
  8720. @subsection Examples
  8721. @itemize
  8722. @item
  8723. Take the first 5 seconds of a clip, and reverse it.
  8724. @example
  8725. trim=end=5,reverse
  8726. @end example
  8727. @end itemize
  8728. @section rotate
  8729. Rotate video by an arbitrary angle expressed in radians.
  8730. The filter accepts the following options:
  8731. A description of the optional parameters follows.
  8732. @table @option
  8733. @item angle, a
  8734. Set an expression for the angle by which to rotate the input video
  8735. clockwise, expressed as a number of radians. A negative value will
  8736. result in a counter-clockwise rotation. By default it is set to "0".
  8737. This expression is evaluated for each frame.
  8738. @item out_w, ow
  8739. Set the output width expression, default value is "iw".
  8740. This expression is evaluated just once during configuration.
  8741. @item out_h, oh
  8742. Set the output height expression, default value is "ih".
  8743. This expression is evaluated just once during configuration.
  8744. @item bilinear
  8745. Enable bilinear interpolation if set to 1, a value of 0 disables
  8746. it. Default value is 1.
  8747. @item fillcolor, c
  8748. Set the color used to fill the output area not covered by the rotated
  8749. image. For the general syntax of this option, check the "Color" section in the
  8750. ffmpeg-utils manual. If the special value "none" is selected then no
  8751. background is printed (useful for example if the background is never shown).
  8752. Default value is "black".
  8753. @end table
  8754. The expressions for the angle and the output size can contain the
  8755. following constants and functions:
  8756. @table @option
  8757. @item n
  8758. sequential number of the input frame, starting from 0. It is always NAN
  8759. before the first frame is filtered.
  8760. @item t
  8761. time in seconds of the input frame, it is set to 0 when the filter is
  8762. configured. It is always NAN before the first frame is filtered.
  8763. @item hsub
  8764. @item vsub
  8765. horizontal and vertical chroma subsample values. For example for the
  8766. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  8767. @item in_w, iw
  8768. @item in_h, ih
  8769. the input video width and height
  8770. @item out_w, ow
  8771. @item out_h, oh
  8772. the output width and height, that is the size of the padded area as
  8773. specified by the @var{width} and @var{height} expressions
  8774. @item rotw(a)
  8775. @item roth(a)
  8776. the minimal width/height required for completely containing the input
  8777. video rotated by @var{a} radians.
  8778. These are only available when computing the @option{out_w} and
  8779. @option{out_h} expressions.
  8780. @end table
  8781. @subsection Examples
  8782. @itemize
  8783. @item
  8784. Rotate the input by PI/6 radians clockwise:
  8785. @example
  8786. rotate=PI/6
  8787. @end example
  8788. @item
  8789. Rotate the input by PI/6 radians counter-clockwise:
  8790. @example
  8791. rotate=-PI/6
  8792. @end example
  8793. @item
  8794. Rotate the input by 45 degrees clockwise:
  8795. @example
  8796. rotate=45*PI/180
  8797. @end example
  8798. @item
  8799. Apply a constant rotation with period T, starting from an angle of PI/3:
  8800. @example
  8801. rotate=PI/3+2*PI*t/T
  8802. @end example
  8803. @item
  8804. Make the input video rotation oscillating with a period of T
  8805. seconds and an amplitude of A radians:
  8806. @example
  8807. rotate=A*sin(2*PI/T*t)
  8808. @end example
  8809. @item
  8810. Rotate the video, output size is chosen so that the whole rotating
  8811. input video is always completely contained in the output:
  8812. @example
  8813. rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
  8814. @end example
  8815. @item
  8816. Rotate the video, reduce the output size so that no background is ever
  8817. shown:
  8818. @example
  8819. rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
  8820. @end example
  8821. @end itemize
  8822. @subsection Commands
  8823. The filter supports the following commands:
  8824. @table @option
  8825. @item a, angle
  8826. Set the angle expression.
  8827. The command accepts the same syntax of the corresponding option.
  8828. If the specified expression is not valid, it is kept at its current
  8829. value.
  8830. @end table
  8831. @section sab
  8832. Apply Shape Adaptive Blur.
  8833. The filter accepts the following options:
  8834. @table @option
  8835. @item luma_radius, lr
  8836. Set luma blur filter strength, must be a value in range 0.1-4.0, default
  8837. value is 1.0. A greater value will result in a more blurred image, and
  8838. in slower processing.
  8839. @item luma_pre_filter_radius, lpfr
  8840. Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
  8841. value is 1.0.
  8842. @item luma_strength, ls
  8843. Set luma maximum difference between pixels to still be considered, must
  8844. be a value in the 0.1-100.0 range, default value is 1.0.
  8845. @item chroma_radius, cr
  8846. Set chroma blur filter strength, must be a value in range -0.9-4.0. A
  8847. greater value will result in a more blurred image, and in slower
  8848. processing.
  8849. @item chroma_pre_filter_radius, cpfr
  8850. Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
  8851. @item chroma_strength, cs
  8852. Set chroma maximum difference between pixels to still be considered,
  8853. must be a value in the -0.9-100.0 range.
  8854. @end table
  8855. Each chroma option value, if not explicitly specified, is set to the
  8856. corresponding luma option value.
  8857. @anchor{scale}
  8858. @section scale
  8859. Scale (resize) the input video, using the libswscale library.
  8860. The scale filter forces the output display aspect ratio to be the same
  8861. of the input, by changing the output sample aspect ratio.
  8862. If the input image format is different from the format requested by
  8863. the next filter, the scale filter will convert the input to the
  8864. requested format.
  8865. @subsection Options
  8866. The filter accepts the following options, or any of the options
  8867. supported by the libswscale scaler.
  8868. See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
  8869. the complete list of scaler options.
  8870. @table @option
  8871. @item width, w
  8872. @item height, h
  8873. Set the output video dimension expression. Default value is the input
  8874. dimension.
  8875. If the value is 0, the input width is used for the output.
  8876. If one of the values is -1, the scale filter will use a value that
  8877. maintains the aspect ratio of the input image, calculated from the
  8878. other specified dimension. If both of them are -1, the input size is
  8879. used
  8880. If one of the values is -n with n > 1, the scale filter will also use a value
  8881. that maintains the aspect ratio of the input image, calculated from the other
  8882. specified dimension. After that it will, however, make sure that the calculated
  8883. dimension is divisible by n and adjust the value if necessary.
  8884. See below for the list of accepted constants for use in the dimension
  8885. expression.
  8886. @item eval
  8887. Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
  8888. @table @samp
  8889. @item init
  8890. Only evaluate expressions once during the filter initialization or when a command is processed.
  8891. @item frame
  8892. Evaluate expressions for each incoming frame.
  8893. @end table
  8894. Default value is @samp{init}.
  8895. @item interl
  8896. Set the interlacing mode. It accepts the following values:
  8897. @table @samp
  8898. @item 1
  8899. Force interlaced aware scaling.
  8900. @item 0
  8901. Do not apply interlaced scaling.
  8902. @item -1
  8903. Select interlaced aware scaling depending on whether the source frames
  8904. are flagged as interlaced or not.
  8905. @end table
  8906. Default value is @samp{0}.
  8907. @item flags
  8908. Set libswscale scaling flags. See
  8909. @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
  8910. complete list of values. If not explicitly specified the filter applies
  8911. the default flags.
  8912. @item param0, param1
  8913. Set libswscale input parameters for scaling algorithms that need them. See
  8914. @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
  8915. complete documentation. If not explicitly specified the filter applies
  8916. empty parameters.
  8917. @item size, s
  8918. Set the video size. For the syntax of this option, check the
  8919. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  8920. @item in_color_matrix
  8921. @item out_color_matrix
  8922. Set in/output YCbCr color space type.
  8923. This allows the autodetected value to be overridden as well as allows forcing
  8924. a specific value used for the output and encoder.
  8925. If not specified, the color space type depends on the pixel format.
  8926. Possible values:
  8927. @table @samp
  8928. @item auto
  8929. Choose automatically.
  8930. @item bt709
  8931. Format conforming to International Telecommunication Union (ITU)
  8932. Recommendation BT.709.
  8933. @item fcc
  8934. Set color space conforming to the United States Federal Communications
  8935. Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
  8936. @item bt601
  8937. Set color space conforming to:
  8938. @itemize
  8939. @item
  8940. ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
  8941. @item
  8942. ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
  8943. @item
  8944. Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
  8945. @end itemize
  8946. @item smpte240m
  8947. Set color space conforming to SMPTE ST 240:1999.
  8948. @end table
  8949. @item in_range
  8950. @item out_range
  8951. Set in/output YCbCr sample range.
  8952. This allows the autodetected value to be overridden as well as allows forcing
  8953. a specific value used for the output and encoder. If not specified, the
  8954. range depends on the pixel format. Possible values:
  8955. @table @samp
  8956. @item auto
  8957. Choose automatically.
  8958. @item jpeg/full/pc
  8959. Set full range (0-255 in case of 8-bit luma).
  8960. @item mpeg/tv
  8961. Set "MPEG" range (16-235 in case of 8-bit luma).
  8962. @end table
  8963. @item force_original_aspect_ratio
  8964. Enable decreasing or increasing output video width or height if necessary to
  8965. keep the original aspect ratio. Possible values:
  8966. @table @samp
  8967. @item disable
  8968. Scale the video as specified and disable this feature.
  8969. @item decrease
  8970. The output video dimensions will automatically be decreased if needed.
  8971. @item increase
  8972. The output video dimensions will automatically be increased if needed.
  8973. @end table
  8974. One useful instance of this option is that when you know a specific device's
  8975. maximum allowed resolution, you can use this to limit the output video to
  8976. that, while retaining the aspect ratio. For example, device A allows
  8977. 1280x720 playback, and your video is 1920x800. Using this option (set it to
  8978. decrease) and specifying 1280x720 to the command line makes the output
  8979. 1280x533.
  8980. Please note that this is a different thing than specifying -1 for @option{w}
  8981. or @option{h}, you still need to specify the output resolution for this option
  8982. to work.
  8983. @end table
  8984. The values of the @option{w} and @option{h} options are expressions
  8985. containing the following constants:
  8986. @table @var
  8987. @item in_w
  8988. @item in_h
  8989. The input width and height
  8990. @item iw
  8991. @item ih
  8992. These are the same as @var{in_w} and @var{in_h}.
  8993. @item out_w
  8994. @item out_h
  8995. The output (scaled) width and height
  8996. @item ow
  8997. @item oh
  8998. These are the same as @var{out_w} and @var{out_h}
  8999. @item a
  9000. The same as @var{iw} / @var{ih}
  9001. @item sar
  9002. input sample aspect ratio
  9003. @item dar
  9004. The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
  9005. @item hsub
  9006. @item vsub
  9007. horizontal and vertical input chroma subsample values. For example for the
  9008. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  9009. @item ohsub
  9010. @item ovsub
  9011. horizontal and vertical output chroma subsample values. For example for the
  9012. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  9013. @end table
  9014. @subsection Examples
  9015. @itemize
  9016. @item
  9017. Scale the input video to a size of 200x100
  9018. @example
  9019. scale=w=200:h=100
  9020. @end example
  9021. This is equivalent to:
  9022. @example
  9023. scale=200:100
  9024. @end example
  9025. or:
  9026. @example
  9027. scale=200x100
  9028. @end example
  9029. @item
  9030. Specify a size abbreviation for the output size:
  9031. @example
  9032. scale=qcif
  9033. @end example
  9034. which can also be written as:
  9035. @example
  9036. scale=size=qcif
  9037. @end example
  9038. @item
  9039. Scale the input to 2x:
  9040. @example
  9041. scale=w=2*iw:h=2*ih
  9042. @end example
  9043. @item
  9044. The above is the same as:
  9045. @example
  9046. scale=2*in_w:2*in_h
  9047. @end example
  9048. @item
  9049. Scale the input to 2x with forced interlaced scaling:
  9050. @example
  9051. scale=2*iw:2*ih:interl=1
  9052. @end example
  9053. @item
  9054. Scale the input to half size:
  9055. @example
  9056. scale=w=iw/2:h=ih/2
  9057. @end example
  9058. @item
  9059. Increase the width, and set the height to the same size:
  9060. @example
  9061. scale=3/2*iw:ow
  9062. @end example
  9063. @item
  9064. Seek Greek harmony:
  9065. @example
  9066. scale=iw:1/PHI*iw
  9067. scale=ih*PHI:ih
  9068. @end example
  9069. @item
  9070. Increase the height, and set the width to 3/2 of the height:
  9071. @example
  9072. scale=w=3/2*oh:h=3/5*ih
  9073. @end example
  9074. @item
  9075. Increase the size, making the size a multiple of the chroma
  9076. subsample values:
  9077. @example
  9078. scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
  9079. @end example
  9080. @item
  9081. Increase the width to a maximum of 500 pixels,
  9082. keeping the same aspect ratio as the input:
  9083. @example
  9084. scale=w='min(500\, iw*3/2):h=-1'
  9085. @end example
  9086. @end itemize
  9087. @subsection Commands
  9088. This filter supports the following commands:
  9089. @table @option
  9090. @item width, w
  9091. @item height, h
  9092. Set the output video dimension expression.
  9093. The command accepts the same syntax of the corresponding option.
  9094. If the specified expression is not valid, it is kept at its current
  9095. value.
  9096. @end table
  9097. @section scale_npp
  9098. Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
  9099. format conversion on CUDA video frames. Setting the output width and height
  9100. works in the same way as for the @var{scale} filter.
  9101. The following additional options are accepted:
  9102. @table @option
  9103. @item format
  9104. The pixel format of the output CUDA frames. If set to the string "same" (the
  9105. default), the input format will be kept. Note that automatic format negotiation
  9106. and conversion is not yet supported for hardware frames
  9107. @item interp_algo
  9108. The interpolation algorithm used for resizing. One of the following:
  9109. @table @option
  9110. @item nn
  9111. Nearest neighbour.
  9112. @item linear
  9113. @item cubic
  9114. @item cubic2p_bspline
  9115. 2-parameter cubic (B=1, C=0)
  9116. @item cubic2p_catmullrom
  9117. 2-parameter cubic (B=0, C=1/2)
  9118. @item cubic2p_b05c03
  9119. 2-parameter cubic (B=1/2, C=3/10)
  9120. @item super
  9121. Supersampling
  9122. @item lanczos
  9123. @end table
  9124. @end table
  9125. @section scale2ref
  9126. Scale (resize) the input video, based on a reference video.
  9127. See the scale filter for available options, scale2ref supports the same but
  9128. uses the reference video instead of the main input as basis.
  9129. @subsection Examples
  9130. @itemize
  9131. @item
  9132. Scale a subtitle stream to match the main video in size before overlaying
  9133. @example
  9134. 'scale2ref[b][a];[a][b]overlay'
  9135. @end example
  9136. @end itemize
  9137. @anchor{selectivecolor}
  9138. @section selectivecolor
  9139. Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
  9140. as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
  9141. by the "purity" of the color (that is, how saturated it already is).
  9142. This filter is similar to the Adobe Photoshop Selective Color tool.
  9143. The filter accepts the following options:
  9144. @table @option
  9145. @item correction_method
  9146. Select color correction method.
  9147. Available values are:
  9148. @table @samp
  9149. @item absolute
  9150. Specified adjustments are applied "as-is" (added/subtracted to original pixel
  9151. component value).
  9152. @item relative
  9153. Specified adjustments are relative to the original component value.
  9154. @end table
  9155. Default is @code{absolute}.
  9156. @item reds
  9157. Adjustments for red pixels (pixels where the red component is the maximum)
  9158. @item yellows
  9159. Adjustments for yellow pixels (pixels where the blue component is the minimum)
  9160. @item greens
  9161. Adjustments for green pixels (pixels where the green component is the maximum)
  9162. @item cyans
  9163. Adjustments for cyan pixels (pixels where the red component is the minimum)
  9164. @item blues
  9165. Adjustments for blue pixels (pixels where the blue component is the maximum)
  9166. @item magentas
  9167. Adjustments for magenta pixels (pixels where the green component is the minimum)
  9168. @item whites
  9169. Adjustments for white pixels (pixels where all components are greater than 128)
  9170. @item neutrals
  9171. Adjustments for all pixels except pure black and pure white
  9172. @item blacks
  9173. Adjustments for black pixels (pixels where all components are lesser than 128)
  9174. @item psfile
  9175. Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
  9176. @end table
  9177. All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
  9178. 4 space separated floating point adjustment values in the [-1,1] range,
  9179. respectively to adjust the amount of cyan, magenta, yellow and black for the
  9180. pixels of its range.
  9181. @subsection Examples
  9182. @itemize
  9183. @item
  9184. Increase cyan by 50% and reduce yellow by 33% in every green areas, and
  9185. increase magenta by 27% in blue areas:
  9186. @example
  9187. selectivecolor=greens=.5 0 -.33 0:blues=0 .27
  9188. @end example
  9189. @item
  9190. Use a Photoshop selective color preset:
  9191. @example
  9192. selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
  9193. @end example
  9194. @end itemize
  9195. @anchor{separatefields}
  9196. @section separatefields
  9197. The @code{separatefields} takes a frame-based video input and splits
  9198. each frame into its components fields, producing a new half height clip
  9199. with twice the frame rate and twice the frame count.
  9200. This filter use field-dominance information in frame to decide which
  9201. of each pair of fields to place first in the output.
  9202. If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
  9203. @section setdar, setsar
  9204. The @code{setdar} filter sets the Display Aspect Ratio for the filter
  9205. output video.
  9206. This is done by changing the specified Sample (aka Pixel) Aspect
  9207. Ratio, according to the following equation:
  9208. @example
  9209. @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
  9210. @end example
  9211. Keep in mind that the @code{setdar} filter does not modify the pixel
  9212. dimensions of the video frame. Also, the display aspect ratio set by
  9213. this filter may be changed by later filters in the filterchain,
  9214. e.g. in case of scaling or if another "setdar" or a "setsar" filter is
  9215. applied.
  9216. The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
  9217. the filter output video.
  9218. Note that as a consequence of the application of this filter, the
  9219. output display aspect ratio will change according to the equation
  9220. above.
  9221. Keep in mind that the sample aspect ratio set by the @code{setsar}
  9222. filter may be changed by later filters in the filterchain, e.g. if
  9223. another "setsar" or a "setdar" filter is applied.
  9224. It accepts the following parameters:
  9225. @table @option
  9226. @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
  9227. Set the aspect ratio used by the filter.
  9228. The parameter can be a floating point number string, an expression, or
  9229. a string of the form @var{num}:@var{den}, where @var{num} and
  9230. @var{den} are the numerator and denominator of the aspect ratio. If
  9231. the parameter is not specified, it is assumed the value "0".
  9232. In case the form "@var{num}:@var{den}" is used, the @code{:} character
  9233. should be escaped.
  9234. @item max
  9235. Set the maximum integer value to use for expressing numerator and
  9236. denominator when reducing the expressed aspect ratio to a rational.
  9237. Default value is @code{100}.
  9238. @end table
  9239. The parameter @var{sar} is an expression containing
  9240. the following constants:
  9241. @table @option
  9242. @item E, PI, PHI
  9243. These are approximated values for the mathematical constants e
  9244. (Euler's number), pi (Greek pi), and phi (the golden ratio).
  9245. @item w, h
  9246. The input width and height.
  9247. @item a
  9248. These are the same as @var{w} / @var{h}.
  9249. @item sar
  9250. The input sample aspect ratio.
  9251. @item dar
  9252. The input display aspect ratio. It is the same as
  9253. (@var{w} / @var{h}) * @var{sar}.
  9254. @item hsub, vsub
  9255. Horizontal and vertical chroma subsample values. For example, for the
  9256. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  9257. @end table
  9258. @subsection Examples
  9259. @itemize
  9260. @item
  9261. To change the display aspect ratio to 16:9, specify one of the following:
  9262. @example
  9263. setdar=dar=1.77777
  9264. setdar=dar=16/9
  9265. @end example
  9266. @item
  9267. To change the sample aspect ratio to 10:11, specify:
  9268. @example
  9269. setsar=sar=10/11
  9270. @end example
  9271. @item
  9272. To set a display aspect ratio of 16:9, and specify a maximum integer value of
  9273. 1000 in the aspect ratio reduction, use the command:
  9274. @example
  9275. setdar=ratio=16/9:max=1000
  9276. @end example
  9277. @end itemize
  9278. @anchor{setfield}
  9279. @section setfield
  9280. Force field for the output video frame.
  9281. The @code{setfield} filter marks the interlace type field for the
  9282. output frames. It does not change the input frame, but only sets the
  9283. corresponding property, which affects how the frame is treated by
  9284. following filters (e.g. @code{fieldorder} or @code{yadif}).
  9285. The filter accepts the following options:
  9286. @table @option
  9287. @item mode
  9288. Available values are:
  9289. @table @samp
  9290. @item auto
  9291. Keep the same field property.
  9292. @item bff
  9293. Mark the frame as bottom-field-first.
  9294. @item tff
  9295. Mark the frame as top-field-first.
  9296. @item prog
  9297. Mark the frame as progressive.
  9298. @end table
  9299. @end table
  9300. @section showinfo
  9301. Show a line containing various information for each input video frame.
  9302. The input video is not modified.
  9303. The shown line contains a sequence of key/value pairs of the form
  9304. @var{key}:@var{value}.
  9305. The following values are shown in the output:
  9306. @table @option
  9307. @item n
  9308. The (sequential) number of the input frame, starting from 0.
  9309. @item pts
  9310. The Presentation TimeStamp of the input frame, expressed as a number of
  9311. time base units. The time base unit depends on the filter input pad.
  9312. @item pts_time
  9313. The Presentation TimeStamp of the input frame, expressed as a number of
  9314. seconds.
  9315. @item pos
  9316. The position of the frame in the input stream, or -1 if this information is
  9317. unavailable and/or meaningless (for example in case of synthetic video).
  9318. @item fmt
  9319. The pixel format name.
  9320. @item sar
  9321. The sample aspect ratio of the input frame, expressed in the form
  9322. @var{num}/@var{den}.
  9323. @item s
  9324. The size of the input frame. For the syntax of this option, check the
  9325. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  9326. @item i
  9327. The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
  9328. for bottom field first).
  9329. @item iskey
  9330. This is 1 if the frame is a key frame, 0 otherwise.
  9331. @item type
  9332. The picture type of the input frame ("I" for an I-frame, "P" for a
  9333. P-frame, "B" for a B-frame, or "?" for an unknown type).
  9334. Also refer to the documentation of the @code{AVPictureType} enum and of
  9335. the @code{av_get_picture_type_char} function defined in
  9336. @file{libavutil/avutil.h}.
  9337. @item checksum
  9338. The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
  9339. @item plane_checksum
  9340. The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
  9341. expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
  9342. @end table
  9343. @section showpalette
  9344. Displays the 256 colors palette of each frame. This filter is only relevant for
  9345. @var{pal8} pixel format frames.
  9346. It accepts the following option:
  9347. @table @option
  9348. @item s
  9349. Set the size of the box used to represent one palette color entry. Default is
  9350. @code{30} (for a @code{30x30} pixel box).
  9351. @end table
  9352. @section shuffleframes
  9353. Reorder and/or duplicate video frames.
  9354. It accepts the following parameters:
  9355. @table @option
  9356. @item mapping
  9357. Set the destination indexes of input frames.
  9358. This is space or '|' separated list of indexes that maps input frames to output
  9359. frames. Number of indexes also sets maximal value that each index may have.
  9360. @end table
  9361. The first frame has the index 0. The default is to keep the input unchanged.
  9362. @subsection Examples
  9363. @itemize
  9364. @item
  9365. Swap second and third frame of every three frames of the input:
  9366. @example
  9367. ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
  9368. @end example
  9369. @item
  9370. Swap 10th and 1st frame of every ten frames of the input:
  9371. @example
  9372. ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
  9373. @end example
  9374. @end itemize
  9375. @section shuffleplanes
  9376. Reorder and/or duplicate video planes.
  9377. It accepts the following parameters:
  9378. @table @option
  9379. @item map0
  9380. The index of the input plane to be used as the first output plane.
  9381. @item map1
  9382. The index of the input plane to be used as the second output plane.
  9383. @item map2
  9384. The index of the input plane to be used as the third output plane.
  9385. @item map3
  9386. The index of the input plane to be used as the fourth output plane.
  9387. @end table
  9388. The first plane has the index 0. The default is to keep the input unchanged.
  9389. @subsection Examples
  9390. @itemize
  9391. @item
  9392. Swap the second and third planes of the input:
  9393. @example
  9394. ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
  9395. @end example
  9396. @end itemize
  9397. @anchor{signalstats}
  9398. @section signalstats
  9399. Evaluate various visual metrics that assist in determining issues associated
  9400. with the digitization of analog video media.
  9401. By default the filter will log these metadata values:
  9402. @table @option
  9403. @item YMIN
  9404. Display the minimal Y value contained within the input frame. Expressed in
  9405. range of [0-255].
  9406. @item YLOW
  9407. Display the Y value at the 10% percentile within the input frame. Expressed in
  9408. range of [0-255].
  9409. @item YAVG
  9410. Display the average Y value within the input frame. Expressed in range of
  9411. [0-255].
  9412. @item YHIGH
  9413. Display the Y value at the 90% percentile within the input frame. Expressed in
  9414. range of [0-255].
  9415. @item YMAX
  9416. Display the maximum Y value contained within the input frame. Expressed in
  9417. range of [0-255].
  9418. @item UMIN
  9419. Display the minimal U value contained within the input frame. Expressed in
  9420. range of [0-255].
  9421. @item ULOW
  9422. Display the U value at the 10% percentile within the input frame. Expressed in
  9423. range of [0-255].
  9424. @item UAVG
  9425. Display the average U value within the input frame. Expressed in range of
  9426. [0-255].
  9427. @item UHIGH
  9428. Display the U value at the 90% percentile within the input frame. Expressed in
  9429. range of [0-255].
  9430. @item UMAX
  9431. Display the maximum U value contained within the input frame. Expressed in
  9432. range of [0-255].
  9433. @item VMIN
  9434. Display the minimal V value contained within the input frame. Expressed in
  9435. range of [0-255].
  9436. @item VLOW
  9437. Display the V value at the 10% percentile within the input frame. Expressed in
  9438. range of [0-255].
  9439. @item VAVG
  9440. Display the average V value within the input frame. Expressed in range of
  9441. [0-255].
  9442. @item VHIGH
  9443. Display the V value at the 90% percentile within the input frame. Expressed in
  9444. range of [0-255].
  9445. @item VMAX
  9446. Display the maximum V value contained within the input frame. Expressed in
  9447. range of [0-255].
  9448. @item SATMIN
  9449. Display the minimal saturation value contained within the input frame.
  9450. Expressed in range of [0-~181.02].
  9451. @item SATLOW
  9452. Display the saturation value at the 10% percentile within the input frame.
  9453. Expressed in range of [0-~181.02].
  9454. @item SATAVG
  9455. Display the average saturation value within the input frame. Expressed in range
  9456. of [0-~181.02].
  9457. @item SATHIGH
  9458. Display the saturation value at the 90% percentile within the input frame.
  9459. Expressed in range of [0-~181.02].
  9460. @item SATMAX
  9461. Display the maximum saturation value contained within the input frame.
  9462. Expressed in range of [0-~181.02].
  9463. @item HUEMED
  9464. Display the median value for hue within the input frame. Expressed in range of
  9465. [0-360].
  9466. @item HUEAVG
  9467. Display the average value for hue within the input frame. Expressed in range of
  9468. [0-360].
  9469. @item YDIF
  9470. Display the average of sample value difference between all values of the Y
  9471. plane in the current frame and corresponding values of the previous input frame.
  9472. Expressed in range of [0-255].
  9473. @item UDIF
  9474. Display the average of sample value difference between all values of the U
  9475. plane in the current frame and corresponding values of the previous input frame.
  9476. Expressed in range of [0-255].
  9477. @item VDIF
  9478. Display the average of sample value difference between all values of the V
  9479. plane in the current frame and corresponding values of the previous input frame.
  9480. Expressed in range of [0-255].
  9481. @item YBITDEPTH
  9482. Display bit depth of Y plane in current frame.
  9483. Expressed in range of [0-16].
  9484. @item UBITDEPTH
  9485. Display bit depth of U plane in current frame.
  9486. Expressed in range of [0-16].
  9487. @item VBITDEPTH
  9488. Display bit depth of V plane in current frame.
  9489. Expressed in range of [0-16].
  9490. @end table
  9491. The filter accepts the following options:
  9492. @table @option
  9493. @item stat
  9494. @item out
  9495. @option{stat} specify an additional form of image analysis.
  9496. @option{out} output video with the specified type of pixel highlighted.
  9497. Both options accept the following values:
  9498. @table @samp
  9499. @item tout
  9500. Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
  9501. unlike the neighboring pixels of the same field. Examples of temporal outliers
  9502. include the results of video dropouts, head clogs, or tape tracking issues.
  9503. @item vrep
  9504. Identify @var{vertical line repetition}. Vertical line repetition includes
  9505. similar rows of pixels within a frame. In born-digital video vertical line
  9506. repetition is common, but this pattern is uncommon in video digitized from an
  9507. analog source. When it occurs in video that results from the digitization of an
  9508. analog source it can indicate concealment from a dropout compensator.
  9509. @item brng
  9510. Identify pixels that fall outside of legal broadcast range.
  9511. @end table
  9512. @item color, c
  9513. Set the highlight color for the @option{out} option. The default color is
  9514. yellow.
  9515. @end table
  9516. @subsection Examples
  9517. @itemize
  9518. @item
  9519. Output data of various video metrics:
  9520. @example
  9521. ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
  9522. @end example
  9523. @item
  9524. Output specific data about the minimum and maximum values of the Y plane per frame:
  9525. @example
  9526. ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
  9527. @end example
  9528. @item
  9529. Playback video while highlighting pixels that are outside of broadcast range in red.
  9530. @example
  9531. ffplay example.mov -vf signalstats="out=brng:color=red"
  9532. @end example
  9533. @item
  9534. Playback video with signalstats metadata drawn over the frame.
  9535. @example
  9536. ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
  9537. @end example
  9538. The contents of signalstat_drawtext.txt used in the command are:
  9539. @example
  9540. time %@{pts:hms@}
  9541. Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
  9542. U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
  9543. V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
  9544. saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
  9545. @end example
  9546. @end itemize
  9547. @anchor{smartblur}
  9548. @section smartblur
  9549. Blur the input video without impacting the outlines.
  9550. It accepts the following options:
  9551. @table @option
  9552. @item luma_radius, lr
  9553. Set the luma radius. The option value must be a float number in
  9554. the range [0.1,5.0] that specifies the variance of the gaussian filter
  9555. used to blur the image (slower if larger). Default value is 1.0.
  9556. @item luma_strength, ls
  9557. Set the luma strength. The option value must be a float number
  9558. in the range [-1.0,1.0] that configures the blurring. A value included
  9559. in [0.0,1.0] will blur the image whereas a value included in
  9560. [-1.0,0.0] will sharpen the image. Default value is 1.0.
  9561. @item luma_threshold, lt
  9562. Set the luma threshold used as a coefficient to determine
  9563. whether a pixel should be blurred or not. The option value must be an
  9564. integer in the range [-30,30]. A value of 0 will filter all the image,
  9565. a value included in [0,30] will filter flat areas and a value included
  9566. in [-30,0] will filter edges. Default value is 0.
  9567. @item chroma_radius, cr
  9568. Set the chroma radius. The option value must be a float number in
  9569. the range [0.1,5.0] that specifies the variance of the gaussian filter
  9570. used to blur the image (slower if larger). Default value is 1.0.
  9571. @item chroma_strength, cs
  9572. Set the chroma strength. The option value must be a float number
  9573. in the range [-1.0,1.0] that configures the blurring. A value included
  9574. in [0.0,1.0] will blur the image whereas a value included in
  9575. [-1.0,0.0] will sharpen the image. Default value is 1.0.
  9576. @item chroma_threshold, ct
  9577. Set the chroma threshold used as a coefficient to determine
  9578. whether a pixel should be blurred or not. The option value must be an
  9579. integer in the range [-30,30]. A value of 0 will filter all the image,
  9580. a value included in [0,30] will filter flat areas and a value included
  9581. in [-30,0] will filter edges. Default value is 0.
  9582. @end table
  9583. If a chroma option is not explicitly set, the corresponding luma value
  9584. is set.
  9585. @section ssim
  9586. Obtain the SSIM (Structural SImilarity Metric) between two input videos.
  9587. This filter takes in input two input videos, the first input is
  9588. considered the "main" source and is passed unchanged to the
  9589. output. The second input is used as a "reference" video for computing
  9590. the SSIM.
  9591. Both video inputs must have the same resolution and pixel format for
  9592. this filter to work correctly. Also it assumes that both inputs
  9593. have the same number of frames, which are compared one by one.
  9594. The filter stores the calculated SSIM of each frame.
  9595. The description of the accepted parameters follows.
  9596. @table @option
  9597. @item stats_file, f
  9598. If specified the filter will use the named file to save the SSIM of
  9599. each individual frame. When filename equals "-" the data is sent to
  9600. standard output.
  9601. @end table
  9602. The file printed if @var{stats_file} is selected, contains a sequence of
  9603. key/value pairs of the form @var{key}:@var{value} for each compared
  9604. couple of frames.
  9605. A description of each shown parameter follows:
  9606. @table @option
  9607. @item n
  9608. sequential number of the input frame, starting from 1
  9609. @item Y, U, V, R, G, B
  9610. SSIM of the compared frames for the component specified by the suffix.
  9611. @item All
  9612. SSIM of the compared frames for the whole frame.
  9613. @item dB
  9614. Same as above but in dB representation.
  9615. @end table
  9616. For example:
  9617. @example
  9618. movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
  9619. [main][ref] ssim="stats_file=stats.log" [out]
  9620. @end example
  9621. On this example the input file being processed is compared with the
  9622. reference file @file{ref_movie.mpg}. The SSIM of each individual frame
  9623. is stored in @file{stats.log}.
  9624. Another example with both psnr and ssim at same time:
  9625. @example
  9626. ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
  9627. @end example
  9628. @section stereo3d
  9629. Convert between different stereoscopic image formats.
  9630. The filters accept the following options:
  9631. @table @option
  9632. @item in
  9633. Set stereoscopic image format of input.
  9634. Available values for input image formats are:
  9635. @table @samp
  9636. @item sbsl
  9637. side by side parallel (left eye left, right eye right)
  9638. @item sbsr
  9639. side by side crosseye (right eye left, left eye right)
  9640. @item sbs2l
  9641. side by side parallel with half width resolution
  9642. (left eye left, right eye right)
  9643. @item sbs2r
  9644. side by side crosseye with half width resolution
  9645. (right eye left, left eye right)
  9646. @item abl
  9647. above-below (left eye above, right eye below)
  9648. @item abr
  9649. above-below (right eye above, left eye below)
  9650. @item ab2l
  9651. above-below with half height resolution
  9652. (left eye above, right eye below)
  9653. @item ab2r
  9654. above-below with half height resolution
  9655. (right eye above, left eye below)
  9656. @item al
  9657. alternating frames (left eye first, right eye second)
  9658. @item ar
  9659. alternating frames (right eye first, left eye second)
  9660. @item irl
  9661. interleaved rows (left eye has top row, right eye starts on next row)
  9662. @item irr
  9663. interleaved rows (right eye has top row, left eye starts on next row)
  9664. @item icl
  9665. interleaved columns, left eye first
  9666. @item icr
  9667. interleaved columns, right eye first
  9668. Default value is @samp{sbsl}.
  9669. @end table
  9670. @item out
  9671. Set stereoscopic image format of output.
  9672. @table @samp
  9673. @item sbsl
  9674. side by side parallel (left eye left, right eye right)
  9675. @item sbsr
  9676. side by side crosseye (right eye left, left eye right)
  9677. @item sbs2l
  9678. side by side parallel with half width resolution
  9679. (left eye left, right eye right)
  9680. @item sbs2r
  9681. side by side crosseye with half width resolution
  9682. (right eye left, left eye right)
  9683. @item abl
  9684. above-below (left eye above, right eye below)
  9685. @item abr
  9686. above-below (right eye above, left eye below)
  9687. @item ab2l
  9688. above-below with half height resolution
  9689. (left eye above, right eye below)
  9690. @item ab2r
  9691. above-below with half height resolution
  9692. (right eye above, left eye below)
  9693. @item al
  9694. alternating frames (left eye first, right eye second)
  9695. @item ar
  9696. alternating frames (right eye first, left eye second)
  9697. @item irl
  9698. interleaved rows (left eye has top row, right eye starts on next row)
  9699. @item irr
  9700. interleaved rows (right eye has top row, left eye starts on next row)
  9701. @item arbg
  9702. anaglyph red/blue gray
  9703. (red filter on left eye, blue filter on right eye)
  9704. @item argg
  9705. anaglyph red/green gray
  9706. (red filter on left eye, green filter on right eye)
  9707. @item arcg
  9708. anaglyph red/cyan gray
  9709. (red filter on left eye, cyan filter on right eye)
  9710. @item arch
  9711. anaglyph red/cyan half colored
  9712. (red filter on left eye, cyan filter on right eye)
  9713. @item arcc
  9714. anaglyph red/cyan color
  9715. (red filter on left eye, cyan filter on right eye)
  9716. @item arcd
  9717. anaglyph red/cyan color optimized with the least squares projection of dubois
  9718. (red filter on left eye, cyan filter on right eye)
  9719. @item agmg
  9720. anaglyph green/magenta gray
  9721. (green filter on left eye, magenta filter on right eye)
  9722. @item agmh
  9723. anaglyph green/magenta half colored
  9724. (green filter on left eye, magenta filter on right eye)
  9725. @item agmc
  9726. anaglyph green/magenta colored
  9727. (green filter on left eye, magenta filter on right eye)
  9728. @item agmd
  9729. anaglyph green/magenta color optimized with the least squares projection of dubois
  9730. (green filter on left eye, magenta filter on right eye)
  9731. @item aybg
  9732. anaglyph yellow/blue gray
  9733. (yellow filter on left eye, blue filter on right eye)
  9734. @item aybh
  9735. anaglyph yellow/blue half colored
  9736. (yellow filter on left eye, blue filter on right eye)
  9737. @item aybc
  9738. anaglyph yellow/blue colored
  9739. (yellow filter on left eye, blue filter on right eye)
  9740. @item aybd
  9741. anaglyph yellow/blue color optimized with the least squares projection of dubois
  9742. (yellow filter on left eye, blue filter on right eye)
  9743. @item ml
  9744. mono output (left eye only)
  9745. @item mr
  9746. mono output (right eye only)
  9747. @item chl
  9748. checkerboard, left eye first
  9749. @item chr
  9750. checkerboard, right eye first
  9751. @item icl
  9752. interleaved columns, left eye first
  9753. @item icr
  9754. interleaved columns, right eye first
  9755. @item hdmi
  9756. HDMI frame pack
  9757. @end table
  9758. Default value is @samp{arcd}.
  9759. @end table
  9760. @subsection Examples
  9761. @itemize
  9762. @item
  9763. Convert input video from side by side parallel to anaglyph yellow/blue dubois:
  9764. @example
  9765. stereo3d=sbsl:aybd
  9766. @end example
  9767. @item
  9768. Convert input video from above below (left eye above, right eye below) to side by side crosseye.
  9769. @example
  9770. stereo3d=abl:sbsr
  9771. @end example
  9772. @end itemize
  9773. @section streamselect, astreamselect
  9774. Select video or audio streams.
  9775. The filter accepts the following options:
  9776. @table @option
  9777. @item inputs
  9778. Set number of inputs. Default is 2.
  9779. @item map
  9780. Set input indexes to remap to outputs.
  9781. @end table
  9782. @subsection Commands
  9783. The @code{streamselect} and @code{astreamselect} filter supports the following
  9784. commands:
  9785. @table @option
  9786. @item map
  9787. Set input indexes to remap to outputs.
  9788. @end table
  9789. @subsection Examples
  9790. @itemize
  9791. @item
  9792. Select first 5 seconds 1st stream and rest of time 2nd stream:
  9793. @example
  9794. sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
  9795. @end example
  9796. @item
  9797. Same as above, but for audio:
  9798. @example
  9799. asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
  9800. @end example
  9801. @end itemize
  9802. @section sobel
  9803. Apply sobel operator to input video stream.
  9804. The filter accepts the following option:
  9805. @table @option
  9806. @item planes
  9807. Set which planes will be processed, unprocessed planes will be copied.
  9808. By default value 0xf, all planes will be processed.
  9809. @item scale
  9810. Set value which will be multiplied with filtered result.
  9811. @item delta
  9812. Set value which will be added to filtered result.
  9813. @end table
  9814. @anchor{spp}
  9815. @section spp
  9816. Apply a simple postprocessing filter that compresses and decompresses the image
  9817. at several (or - in the case of @option{quality} level @code{6} - all) shifts
  9818. and average the results.
  9819. The filter accepts the following options:
  9820. @table @option
  9821. @item quality
  9822. Set quality. This option defines the number of levels for averaging. It accepts
  9823. an integer in the range 0-6. If set to @code{0}, the filter will have no
  9824. effect. A value of @code{6} means the higher quality. For each increment of
  9825. that value the speed drops by a factor of approximately 2. Default value is
  9826. @code{3}.
  9827. @item qp
  9828. Force a constant quantization parameter. If not set, the filter will use the QP
  9829. from the video stream (if available).
  9830. @item mode
  9831. Set thresholding mode. Available modes are:
  9832. @table @samp
  9833. @item hard
  9834. Set hard thresholding (default).
  9835. @item soft
  9836. Set soft thresholding (better de-ringing effect, but likely blurrier).
  9837. @end table
  9838. @item use_bframe_qp
  9839. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  9840. option may cause flicker since the B-Frames have often larger QP. Default is
  9841. @code{0} (not enabled).
  9842. @end table
  9843. @anchor{subtitles}
  9844. @section subtitles
  9845. Draw subtitles on top of input video using the libass library.
  9846. To enable compilation of this filter you need to configure FFmpeg with
  9847. @code{--enable-libass}. This filter also requires a build with libavcodec and
  9848. libavformat to convert the passed subtitles file to ASS (Advanced Substation
  9849. Alpha) subtitles format.
  9850. The filter accepts the following options:
  9851. @table @option
  9852. @item filename, f
  9853. Set the filename of the subtitle file to read. It must be specified.
  9854. @item original_size
  9855. Specify the size of the original video, the video for which the ASS file
  9856. was composed. For the syntax of this option, check the
  9857. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  9858. Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
  9859. correctly scale the fonts if the aspect ratio has been changed.
  9860. @item fontsdir
  9861. Set a directory path containing fonts that can be used by the filter.
  9862. These fonts will be used in addition to whatever the font provider uses.
  9863. @item charenc
  9864. Set subtitles input character encoding. @code{subtitles} filter only. Only
  9865. useful if not UTF-8.
  9866. @item stream_index, si
  9867. Set subtitles stream index. @code{subtitles} filter only.
  9868. @item force_style
  9869. Override default style or script info parameters of the subtitles. It accepts a
  9870. string containing ASS style format @code{KEY=VALUE} couples separated by ",".
  9871. @end table
  9872. If the first key is not specified, it is assumed that the first value
  9873. specifies the @option{filename}.
  9874. For example, to render the file @file{sub.srt} on top of the input
  9875. video, use the command:
  9876. @example
  9877. subtitles=sub.srt
  9878. @end example
  9879. which is equivalent to:
  9880. @example
  9881. subtitles=filename=sub.srt
  9882. @end example
  9883. To render the default subtitles stream from file @file{video.mkv}, use:
  9884. @example
  9885. subtitles=video.mkv
  9886. @end example
  9887. To render the second subtitles stream from that file, use:
  9888. @example
  9889. subtitles=video.mkv:si=1
  9890. @end example
  9891. To make the subtitles stream from @file{sub.srt} appear in transparent green
  9892. @code{DejaVu Serif}, use:
  9893. @example
  9894. subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HAA00FF00'
  9895. @end example
  9896. @section super2xsai
  9897. Scale the input by 2x and smooth using the Super2xSaI (Scale and
  9898. Interpolate) pixel art scaling algorithm.
  9899. Useful for enlarging pixel art images without reducing sharpness.
  9900. @section swaprect
  9901. Swap two rectangular objects in video.
  9902. This filter accepts the following options:
  9903. @table @option
  9904. @item w
  9905. Set object width.
  9906. @item h
  9907. Set object height.
  9908. @item x1
  9909. Set 1st rect x coordinate.
  9910. @item y1
  9911. Set 1st rect y coordinate.
  9912. @item x2
  9913. Set 2nd rect x coordinate.
  9914. @item y2
  9915. Set 2nd rect y coordinate.
  9916. All expressions are evaluated once for each frame.
  9917. @end table
  9918. The all options are expressions containing the following constants:
  9919. @table @option
  9920. @item w
  9921. @item h
  9922. The input width and height.
  9923. @item a
  9924. same as @var{w} / @var{h}
  9925. @item sar
  9926. input sample aspect ratio
  9927. @item dar
  9928. input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
  9929. @item n
  9930. The number of the input frame, starting from 0.
  9931. @item t
  9932. The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
  9933. @item pos
  9934. the position in the file of the input frame, NAN if unknown
  9935. @end table
  9936. @section swapuv
  9937. Swap U & V plane.
  9938. @section telecine
  9939. Apply telecine process to the video.
  9940. This filter accepts the following options:
  9941. @table @option
  9942. @item first_field
  9943. @table @samp
  9944. @item top, t
  9945. top field first
  9946. @item bottom, b
  9947. bottom field first
  9948. The default value is @code{top}.
  9949. @end table
  9950. @item pattern
  9951. A string of numbers representing the pulldown pattern you wish to apply.
  9952. The default value is @code{23}.
  9953. @end table
  9954. @example
  9955. Some typical patterns:
  9956. NTSC output (30i):
  9957. 27.5p: 32222
  9958. 24p: 23 (classic)
  9959. 24p: 2332 (preferred)
  9960. 20p: 33
  9961. 18p: 334
  9962. 16p: 3444
  9963. PAL output (25i):
  9964. 27.5p: 12222
  9965. 24p: 222222222223 ("Euro pulldown")
  9966. 16.67p: 33
  9967. 16p: 33333334
  9968. @end example
  9969. @section thumbnail
  9970. Select the most representative frame in a given sequence of consecutive frames.
  9971. The filter accepts the following options:
  9972. @table @option
  9973. @item n
  9974. Set the frames batch size to analyze; in a set of @var{n} frames, the filter
  9975. will pick one of them, and then handle the next batch of @var{n} frames until
  9976. the end. Default is @code{100}.
  9977. @end table
  9978. Since the filter keeps track of the whole frames sequence, a bigger @var{n}
  9979. value will result in a higher memory usage, so a high value is not recommended.
  9980. @subsection Examples
  9981. @itemize
  9982. @item
  9983. Extract one picture each 50 frames:
  9984. @example
  9985. thumbnail=50
  9986. @end example
  9987. @item
  9988. Complete example of a thumbnail creation with @command{ffmpeg}:
  9989. @example
  9990. ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
  9991. @end example
  9992. @end itemize
  9993. @section tile
  9994. Tile several successive frames together.
  9995. The filter accepts the following options:
  9996. @table @option
  9997. @item layout
  9998. Set the grid size (i.e. the number of lines and columns). For the syntax of
  9999. this option, check the
  10000. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  10001. @item nb_frames
  10002. Set the maximum number of frames to render in the given area. It must be less
  10003. than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
  10004. the area will be used.
  10005. @item margin
  10006. Set the outer border margin in pixels.
  10007. @item padding
  10008. Set the inner border thickness (i.e. the number of pixels between frames). For
  10009. more advanced padding options (such as having different values for the edges),
  10010. refer to the pad video filter.
  10011. @item color
  10012. Specify the color of the unused area. For the syntax of this option, check the
  10013. "Color" section in the ffmpeg-utils manual. The default value of @var{color}
  10014. is "black".
  10015. @end table
  10016. @subsection Examples
  10017. @itemize
  10018. @item
  10019. Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
  10020. @example
  10021. ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
  10022. @end example
  10023. The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
  10024. duplicating each output frame to accommodate the originally detected frame
  10025. rate.
  10026. @item
  10027. Display @code{5} pictures in an area of @code{3x2} frames,
  10028. with @code{7} pixels between them, and @code{2} pixels of initial margin, using
  10029. mixed flat and named options:
  10030. @example
  10031. tile=3x2:nb_frames=5:padding=7:margin=2
  10032. @end example
  10033. @end itemize
  10034. @section tinterlace
  10035. Perform various types of temporal field interlacing.
  10036. Frames are counted starting from 1, so the first input frame is
  10037. considered odd.
  10038. The filter accepts the following options:
  10039. @table @option
  10040. @item mode
  10041. Specify the mode of the interlacing. This option can also be specified
  10042. as a value alone. See below for a list of values for this option.
  10043. Available values are:
  10044. @table @samp
  10045. @item merge, 0
  10046. Move odd frames into the upper field, even into the lower field,
  10047. generating a double height frame at half frame rate.
  10048. @example
  10049. ------> time
  10050. Input:
  10051. Frame 1 Frame 2 Frame 3 Frame 4
  10052. 11111 22222 33333 44444
  10053. 11111 22222 33333 44444
  10054. 11111 22222 33333 44444
  10055. 11111 22222 33333 44444
  10056. Output:
  10057. 11111 33333
  10058. 22222 44444
  10059. 11111 33333
  10060. 22222 44444
  10061. 11111 33333
  10062. 22222 44444
  10063. 11111 33333
  10064. 22222 44444
  10065. @end example
  10066. @item drop_even, 1
  10067. Only output odd frames, even frames are dropped, generating a frame with
  10068. unchanged height at half frame rate.
  10069. @example
  10070. ------> time
  10071. Input:
  10072. Frame 1 Frame 2 Frame 3 Frame 4
  10073. 11111 22222 33333 44444
  10074. 11111 22222 33333 44444
  10075. 11111 22222 33333 44444
  10076. 11111 22222 33333 44444
  10077. Output:
  10078. 11111 33333
  10079. 11111 33333
  10080. 11111 33333
  10081. 11111 33333
  10082. @end example
  10083. @item drop_odd, 2
  10084. Only output even frames, odd frames are dropped, generating a frame with
  10085. unchanged height at half frame rate.
  10086. @example
  10087. ------> time
  10088. Input:
  10089. Frame 1 Frame 2 Frame 3 Frame 4
  10090. 11111 22222 33333 44444
  10091. 11111 22222 33333 44444
  10092. 11111 22222 33333 44444
  10093. 11111 22222 33333 44444
  10094. Output:
  10095. 22222 44444
  10096. 22222 44444
  10097. 22222 44444
  10098. 22222 44444
  10099. @end example
  10100. @item pad, 3
  10101. Expand each frame to full height, but pad alternate lines with black,
  10102. generating a frame with double height at the same input frame rate.
  10103. @example
  10104. ------> time
  10105. Input:
  10106. Frame 1 Frame 2 Frame 3 Frame 4
  10107. 11111 22222 33333 44444
  10108. 11111 22222 33333 44444
  10109. 11111 22222 33333 44444
  10110. 11111 22222 33333 44444
  10111. Output:
  10112. 11111 ..... 33333 .....
  10113. ..... 22222 ..... 44444
  10114. 11111 ..... 33333 .....
  10115. ..... 22222 ..... 44444
  10116. 11111 ..... 33333 .....
  10117. ..... 22222 ..... 44444
  10118. 11111 ..... 33333 .....
  10119. ..... 22222 ..... 44444
  10120. @end example
  10121. @item interleave_top, 4
  10122. Interleave the upper field from odd frames with the lower field from
  10123. even frames, generating a frame with unchanged height at half frame rate.
  10124. @example
  10125. ------> time
  10126. Input:
  10127. Frame 1 Frame 2 Frame 3 Frame 4
  10128. 11111<- 22222 33333<- 44444
  10129. 11111 22222<- 33333 44444<-
  10130. 11111<- 22222 33333<- 44444
  10131. 11111 22222<- 33333 44444<-
  10132. Output:
  10133. 11111 33333
  10134. 22222 44444
  10135. 11111 33333
  10136. 22222 44444
  10137. @end example
  10138. @item interleave_bottom, 5
  10139. Interleave the lower field from odd frames with the upper field from
  10140. even frames, generating a frame with unchanged height at half frame rate.
  10141. @example
  10142. ------> time
  10143. Input:
  10144. Frame 1 Frame 2 Frame 3 Frame 4
  10145. 11111 22222<- 33333 44444<-
  10146. 11111<- 22222 33333<- 44444
  10147. 11111 22222<- 33333 44444<-
  10148. 11111<- 22222 33333<- 44444
  10149. Output:
  10150. 22222 44444
  10151. 11111 33333
  10152. 22222 44444
  10153. 11111 33333
  10154. @end example
  10155. @item interlacex2, 6
  10156. Double frame rate with unchanged height. Frames are inserted each
  10157. containing the second temporal field from the previous input frame and
  10158. the first temporal field from the next input frame. This mode relies on
  10159. the top_field_first flag. Useful for interlaced video displays with no
  10160. field synchronisation.
  10161. @example
  10162. ------> time
  10163. Input:
  10164. Frame 1 Frame 2 Frame 3 Frame 4
  10165. 11111 22222 33333 44444
  10166. 11111 22222 33333 44444
  10167. 11111 22222 33333 44444
  10168. 11111 22222 33333 44444
  10169. Output:
  10170. 11111 22222 22222 33333 33333 44444 44444
  10171. 11111 11111 22222 22222 33333 33333 44444
  10172. 11111 22222 22222 33333 33333 44444 44444
  10173. 11111 11111 22222 22222 33333 33333 44444
  10174. @end example
  10175. @item mergex2, 7
  10176. Move odd frames into the upper field, even into the lower field,
  10177. generating a double height frame at same frame rate.
  10178. @example
  10179. ------> time
  10180. Input:
  10181. Frame 1 Frame 2 Frame 3 Frame 4
  10182. 11111 22222 33333 44444
  10183. 11111 22222 33333 44444
  10184. 11111 22222 33333 44444
  10185. 11111 22222 33333 44444
  10186. Output:
  10187. 11111 33333 33333 55555
  10188. 22222 22222 44444 44444
  10189. 11111 33333 33333 55555
  10190. 22222 22222 44444 44444
  10191. 11111 33333 33333 55555
  10192. 22222 22222 44444 44444
  10193. 11111 33333 33333 55555
  10194. 22222 22222 44444 44444
  10195. @end example
  10196. @end table
  10197. Numeric values are deprecated but are accepted for backward
  10198. compatibility reasons.
  10199. Default mode is @code{merge}.
  10200. @item flags
  10201. Specify flags influencing the filter process.
  10202. Available value for @var{flags} is:
  10203. @table @option
  10204. @item low_pass_filter, vlfp
  10205. Enable vertical low-pass filtering in the filter.
  10206. Vertical low-pass filtering is required when creating an interlaced
  10207. destination from a progressive source which contains high-frequency
  10208. vertical detail. Filtering will reduce interlace 'twitter' and Moire
  10209. patterning.
  10210. Vertical low-pass filtering can only be enabled for @option{mode}
  10211. @var{interleave_top} and @var{interleave_bottom}.
  10212. @end table
  10213. @end table
  10214. @section transpose
  10215. Transpose rows with columns in the input video and optionally flip it.
  10216. It accepts the following parameters:
  10217. @table @option
  10218. @item dir
  10219. Specify the transposition direction.
  10220. Can assume the following values:
  10221. @table @samp
  10222. @item 0, 4, cclock_flip
  10223. Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
  10224. @example
  10225. L.R L.l
  10226. . . -> . .
  10227. l.r R.r
  10228. @end example
  10229. @item 1, 5, clock
  10230. Rotate by 90 degrees clockwise, that is:
  10231. @example
  10232. L.R l.L
  10233. . . -> . .
  10234. l.r r.R
  10235. @end example
  10236. @item 2, 6, cclock
  10237. Rotate by 90 degrees counterclockwise, that is:
  10238. @example
  10239. L.R R.r
  10240. . . -> . .
  10241. l.r L.l
  10242. @end example
  10243. @item 3, 7, clock_flip
  10244. Rotate by 90 degrees clockwise and vertically flip, that is:
  10245. @example
  10246. L.R r.R
  10247. . . -> . .
  10248. l.r l.L
  10249. @end example
  10250. @end table
  10251. For values between 4-7, the transposition is only done if the input
  10252. video geometry is portrait and not landscape. These values are
  10253. deprecated, the @code{passthrough} option should be used instead.
  10254. Numerical values are deprecated, and should be dropped in favor of
  10255. symbolic constants.
  10256. @item passthrough
  10257. Do not apply the transposition if the input geometry matches the one
  10258. specified by the specified value. It accepts the following values:
  10259. @table @samp
  10260. @item none
  10261. Always apply transposition.
  10262. @item portrait
  10263. Preserve portrait geometry (when @var{height} >= @var{width}).
  10264. @item landscape
  10265. Preserve landscape geometry (when @var{width} >= @var{height}).
  10266. @end table
  10267. Default value is @code{none}.
  10268. @end table
  10269. For example to rotate by 90 degrees clockwise and preserve portrait
  10270. layout:
  10271. @example
  10272. transpose=dir=1:passthrough=portrait
  10273. @end example
  10274. The command above can also be specified as:
  10275. @example
  10276. transpose=1:portrait
  10277. @end example
  10278. @section trim
  10279. Trim the input so that the output contains one continuous subpart of the input.
  10280. It accepts the following parameters:
  10281. @table @option
  10282. @item start
  10283. Specify the time of the start of the kept section, i.e. the frame with the
  10284. timestamp @var{start} will be the first frame in the output.
  10285. @item end
  10286. Specify the time of the first frame that will be dropped, i.e. the frame
  10287. immediately preceding the one with the timestamp @var{end} will be the last
  10288. frame in the output.
  10289. @item start_pts
  10290. This is the same as @var{start}, except this option sets the start timestamp
  10291. in timebase units instead of seconds.
  10292. @item end_pts
  10293. This is the same as @var{end}, except this option sets the end timestamp
  10294. in timebase units instead of seconds.
  10295. @item duration
  10296. The maximum duration of the output in seconds.
  10297. @item start_frame
  10298. The number of the first frame that should be passed to the output.
  10299. @item end_frame
  10300. The number of the first frame that should be dropped.
  10301. @end table
  10302. @option{start}, @option{end}, and @option{duration} are expressed as time
  10303. duration specifications; see
  10304. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  10305. for the accepted syntax.
  10306. Note that the first two sets of the start/end options and the @option{duration}
  10307. option look at the frame timestamp, while the _frame variants simply count the
  10308. frames that pass through the filter. Also note that this filter does not modify
  10309. the timestamps. If you wish for the output timestamps to start at zero, insert a
  10310. setpts filter after the trim filter.
  10311. If multiple start or end options are set, this filter tries to be greedy and
  10312. keep all the frames that match at least one of the specified constraints. To keep
  10313. only the part that matches all the constraints at once, chain multiple trim
  10314. filters.
  10315. The defaults are such that all the input is kept. So it is possible to set e.g.
  10316. just the end values to keep everything before the specified time.
  10317. Examples:
  10318. @itemize
  10319. @item
  10320. Drop everything except the second minute of input:
  10321. @example
  10322. ffmpeg -i INPUT -vf trim=60:120
  10323. @end example
  10324. @item
  10325. Keep only the first second:
  10326. @example
  10327. ffmpeg -i INPUT -vf trim=duration=1
  10328. @end example
  10329. @end itemize
  10330. @anchor{unsharp}
  10331. @section unsharp
  10332. Sharpen or blur the input video.
  10333. It accepts the following parameters:
  10334. @table @option
  10335. @item luma_msize_x, lx
  10336. Set the luma matrix horizontal size. It must be an odd integer between
  10337. 3 and 23. The default value is 5.
  10338. @item luma_msize_y, ly
  10339. Set the luma matrix vertical size. It must be an odd integer between 3
  10340. and 23. The default value is 5.
  10341. @item luma_amount, la
  10342. Set the luma effect strength. It must be a floating point number, reasonable
  10343. values lay between -1.5 and 1.5.
  10344. Negative values will blur the input video, while positive values will
  10345. sharpen it, a value of zero will disable the effect.
  10346. Default value is 1.0.
  10347. @item chroma_msize_x, cx
  10348. Set the chroma matrix horizontal size. It must be an odd integer
  10349. between 3 and 23. The default value is 5.
  10350. @item chroma_msize_y, cy
  10351. Set the chroma matrix vertical size. It must be an odd integer
  10352. between 3 and 23. The default value is 5.
  10353. @item chroma_amount, ca
  10354. Set the chroma effect strength. It must be a floating point number, reasonable
  10355. values lay between -1.5 and 1.5.
  10356. Negative values will blur the input video, while positive values will
  10357. sharpen it, a value of zero will disable the effect.
  10358. Default value is 0.0.
  10359. @item opencl
  10360. If set to 1, specify using OpenCL capabilities, only available if
  10361. FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
  10362. @end table
  10363. All parameters are optional and default to the equivalent of the
  10364. string '5:5:1.0:5:5:0.0'.
  10365. @subsection Examples
  10366. @itemize
  10367. @item
  10368. Apply strong luma sharpen effect:
  10369. @example
  10370. unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
  10371. @end example
  10372. @item
  10373. Apply a strong blur of both luma and chroma parameters:
  10374. @example
  10375. unsharp=7:7:-2:7:7:-2
  10376. @end example
  10377. @end itemize
  10378. @section uspp
  10379. Apply ultra slow/simple postprocessing filter that compresses and decompresses
  10380. the image at several (or - in the case of @option{quality} level @code{8} - all)
  10381. shifts and average the results.
  10382. The way this differs from the behavior of spp is that uspp actually encodes &
  10383. decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
  10384. DCT similar to MJPEG.
  10385. The filter accepts the following options:
  10386. @table @option
  10387. @item quality
  10388. Set quality. This option defines the number of levels for averaging. It accepts
  10389. an integer in the range 0-8. If set to @code{0}, the filter will have no
  10390. effect. A value of @code{8} means the higher quality. For each increment of
  10391. that value the speed drops by a factor of approximately 2. Default value is
  10392. @code{3}.
  10393. @item qp
  10394. Force a constant quantization parameter. If not set, the filter will use the QP
  10395. from the video stream (if available).
  10396. @end table
  10397. @section vaguedenoiser
  10398. Apply a wavelet based denoiser.
  10399. It transforms each frame from the video input into the wavelet domain,
  10400. using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
  10401. the obtained coefficients. It does an inverse wavelet transform after.
  10402. Due to wavelet properties, it should give a nice smoothed result, and
  10403. reduced noise, without blurring picture features.
  10404. This filter accepts the following options:
  10405. @table @option
  10406. @item threshold
  10407. The filtering strength. The higher, the more filtered the video will be.
  10408. Hard thresholding can use a higher threshold than soft thresholding
  10409. before the video looks overfiltered.
  10410. @item method
  10411. The filtering method the filter will use.
  10412. It accepts the following values:
  10413. @table @samp
  10414. @item hard
  10415. All values under the threshold will be zeroed.
  10416. @item soft
  10417. All values under the threshold will be zeroed. All values above will be
  10418. reduced by the threshold.
  10419. @item garrote
  10420. Scales or nullifies coefficients - intermediary between (more) soft and
  10421. (less) hard thresholding.
  10422. @end table
  10423. @item nsteps
  10424. Number of times, the wavelet will decompose the picture. Picture can't
  10425. be decomposed beyond a particular point (typically, 8 for a 640x480
  10426. frame - as 2^9 = 512 > 480)
  10427. @item percent
  10428. Partial of full denoising (limited coefficients shrinking), from 0 to 100.
  10429. @item planes
  10430. A list of the planes to process. By default all planes are processed.
  10431. @end table
  10432. @section vectorscope
  10433. Display 2 color component values in the two dimensional graph (which is called
  10434. a vectorscope).
  10435. This filter accepts the following options:
  10436. @table @option
  10437. @item mode, m
  10438. Set vectorscope mode.
  10439. It accepts the following values:
  10440. @table @samp
  10441. @item gray
  10442. Gray values are displayed on graph, higher brightness means more pixels have
  10443. same component color value on location in graph. This is the default mode.
  10444. @item color
  10445. Gray values are displayed on graph. Surrounding pixels values which are not
  10446. present in video frame are drawn in gradient of 2 color components which are
  10447. set by option @code{x} and @code{y}. The 3rd color component is static.
  10448. @item color2
  10449. Actual color components values present in video frame are displayed on graph.
  10450. @item color3
  10451. Similar as color2 but higher frequency of same values @code{x} and @code{y}
  10452. on graph increases value of another color component, which is luminance by
  10453. default values of @code{x} and @code{y}.
  10454. @item color4
  10455. Actual colors present in video frame are displayed on graph. If two different
  10456. colors map to same position on graph then color with higher value of component
  10457. not present in graph is picked.
  10458. @item color5
  10459. Gray values are displayed on graph. Similar to @code{color} but with 3rd color
  10460. component picked from radial gradient.
  10461. @end table
  10462. @item x
  10463. Set which color component will be represented on X-axis. Default is @code{1}.
  10464. @item y
  10465. Set which color component will be represented on Y-axis. Default is @code{2}.
  10466. @item intensity, i
  10467. Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
  10468. of color component which represents frequency of (X, Y) location in graph.
  10469. @item envelope, e
  10470. @table @samp
  10471. @item none
  10472. No envelope, this is default.
  10473. @item instant
  10474. Instant envelope, even darkest single pixel will be clearly highlighted.
  10475. @item peak
  10476. Hold maximum and minimum values presented in graph over time. This way you
  10477. can still spot out of range values without constantly looking at vectorscope.
  10478. @item peak+instant
  10479. Peak and instant envelope combined together.
  10480. @end table
  10481. @item graticule, g
  10482. Set what kind of graticule to draw.
  10483. @table @samp
  10484. @item none
  10485. @item green
  10486. @item color
  10487. @end table
  10488. @item opacity, o
  10489. Set graticule opacity.
  10490. @item flags, f
  10491. Set graticule flags.
  10492. @table @samp
  10493. @item white
  10494. Draw graticule for white point.
  10495. @item black
  10496. Draw graticule for black point.
  10497. @item name
  10498. Draw color points short names.
  10499. @end table
  10500. @item bgopacity, b
  10501. Set background opacity.
  10502. @item lthreshold, l
  10503. Set low threshold for color component not represented on X or Y axis.
  10504. Values lower than this value will be ignored. Default is 0.
  10505. Note this value is multiplied with actual max possible value one pixel component
  10506. can have. So for 8-bit input and low threshold value of 0.1 actual threshold
  10507. is 0.1 * 255 = 25.
  10508. @item hthreshold, h
  10509. Set high threshold for color component not represented on X or Y axis.
  10510. Values higher than this value will be ignored. Default is 1.
  10511. Note this value is multiplied with actual max possible value one pixel component
  10512. can have. So for 8-bit input and high threshold value of 0.9 actual threshold
  10513. is 0.9 * 255 = 230.
  10514. @item colorspace, c
  10515. Set what kind of colorspace to use when drawing graticule.
  10516. @table @samp
  10517. @item auto
  10518. @item 601
  10519. @item 709
  10520. @end table
  10521. Default is auto.
  10522. @end table
  10523. @anchor{vidstabdetect}
  10524. @section vidstabdetect
  10525. Analyze video stabilization/deshaking. Perform pass 1 of 2, see
  10526. @ref{vidstabtransform} for pass 2.
  10527. This filter generates a file with relative translation and rotation
  10528. transform information about subsequent frames, which is then used by
  10529. the @ref{vidstabtransform} filter.
  10530. To enable compilation of this filter you need to configure FFmpeg with
  10531. @code{--enable-libvidstab}.
  10532. This filter accepts the following options:
  10533. @table @option
  10534. @item result
  10535. Set the path to the file used to write the transforms information.
  10536. Default value is @file{transforms.trf}.
  10537. @item shakiness
  10538. Set how shaky the video is and how quick the camera is. It accepts an
  10539. integer in the range 1-10, a value of 1 means little shakiness, a
  10540. value of 10 means strong shakiness. Default value is 5.
  10541. @item accuracy
  10542. Set the accuracy of the detection process. It must be a value in the
  10543. range 1-15. A value of 1 means low accuracy, a value of 15 means high
  10544. accuracy. Default value is 15.
  10545. @item stepsize
  10546. Set stepsize of the search process. The region around minimum is
  10547. scanned with 1 pixel resolution. Default value is 6.
  10548. @item mincontrast
  10549. Set minimum contrast. Below this value a local measurement field is
  10550. discarded. Must be a floating point value in the range 0-1. Default
  10551. value is 0.3.
  10552. @item tripod
  10553. Set reference frame number for tripod mode.
  10554. If enabled, the motion of the frames is compared to a reference frame
  10555. in the filtered stream, identified by the specified number. The idea
  10556. is to compensate all movements in a more-or-less static scene and keep
  10557. the camera view absolutely still.
  10558. If set to 0, it is disabled. The frames are counted starting from 1.
  10559. @item show
  10560. Show fields and transforms in the resulting frames. It accepts an
  10561. integer in the range 0-2. Default value is 0, which disables any
  10562. visualization.
  10563. @end table
  10564. @subsection Examples
  10565. @itemize
  10566. @item
  10567. Use default values:
  10568. @example
  10569. vidstabdetect
  10570. @end example
  10571. @item
  10572. Analyze strongly shaky movie and put the results in file
  10573. @file{mytransforms.trf}:
  10574. @example
  10575. vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
  10576. @end example
  10577. @item
  10578. Visualize the result of internal transformations in the resulting
  10579. video:
  10580. @example
  10581. vidstabdetect=show=1
  10582. @end example
  10583. @item
  10584. Analyze a video with medium shakiness using @command{ffmpeg}:
  10585. @example
  10586. ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
  10587. @end example
  10588. @end itemize
  10589. @anchor{vidstabtransform}
  10590. @section vidstabtransform
  10591. Video stabilization/deshaking: pass 2 of 2,
  10592. see @ref{vidstabdetect} for pass 1.
  10593. Read a file with transform information for each frame and
  10594. apply/compensate them. Together with the @ref{vidstabdetect}
  10595. filter this can be used to deshake videos. See also
  10596. @url{http://public.hronopik.de/vid.stab}. It is important to also use
  10597. the @ref{unsharp} filter, see below.
  10598. To enable compilation of this filter you need to configure FFmpeg with
  10599. @code{--enable-libvidstab}.
  10600. @subsection Options
  10601. @table @option
  10602. @item input
  10603. Set path to the file used to read the transforms. Default value is
  10604. @file{transforms.trf}.
  10605. @item smoothing
  10606. Set the number of frames (value*2 + 1) used for lowpass filtering the
  10607. camera movements. Default value is 10.
  10608. For example a number of 10 means that 21 frames are used (10 in the
  10609. past and 10 in the future) to smoothen the motion in the video. A
  10610. larger value leads to a smoother video, but limits the acceleration of
  10611. the camera (pan/tilt movements). 0 is a special case where a static
  10612. camera is simulated.
  10613. @item optalgo
  10614. Set the camera path optimization algorithm.
  10615. Accepted values are:
  10616. @table @samp
  10617. @item gauss
  10618. gaussian kernel low-pass filter on camera motion (default)
  10619. @item avg
  10620. averaging on transformations
  10621. @end table
  10622. @item maxshift
  10623. Set maximal number of pixels to translate frames. Default value is -1,
  10624. meaning no limit.
  10625. @item maxangle
  10626. Set maximal angle in radians (degree*PI/180) to rotate frames. Default
  10627. value is -1, meaning no limit.
  10628. @item crop
  10629. Specify how to deal with borders that may be visible due to movement
  10630. compensation.
  10631. Available values are:
  10632. @table @samp
  10633. @item keep
  10634. keep image information from previous frame (default)
  10635. @item black
  10636. fill the border black
  10637. @end table
  10638. @item invert
  10639. Invert transforms if set to 1. Default value is 0.
  10640. @item relative
  10641. Consider transforms as relative to previous frame if set to 1,
  10642. absolute if set to 0. Default value is 0.
  10643. @item zoom
  10644. Set percentage to zoom. A positive value will result in a zoom-in
  10645. effect, a negative value in a zoom-out effect. Default value is 0 (no
  10646. zoom).
  10647. @item optzoom
  10648. Set optimal zooming to avoid borders.
  10649. Accepted values are:
  10650. @table @samp
  10651. @item 0
  10652. disabled
  10653. @item 1
  10654. optimal static zoom value is determined (only very strong movements
  10655. will lead to visible borders) (default)
  10656. @item 2
  10657. optimal adaptive zoom value is determined (no borders will be
  10658. visible), see @option{zoomspeed}
  10659. @end table
  10660. Note that the value given at zoom is added to the one calculated here.
  10661. @item zoomspeed
  10662. Set percent to zoom maximally each frame (enabled when
  10663. @option{optzoom} is set to 2). Range is from 0 to 5, default value is
  10664. 0.25.
  10665. @item interpol
  10666. Specify type of interpolation.
  10667. Available values are:
  10668. @table @samp
  10669. @item no
  10670. no interpolation
  10671. @item linear
  10672. linear only horizontal
  10673. @item bilinear
  10674. linear in both directions (default)
  10675. @item bicubic
  10676. cubic in both directions (slow)
  10677. @end table
  10678. @item tripod
  10679. Enable virtual tripod mode if set to 1, which is equivalent to
  10680. @code{relative=0:smoothing=0}. Default value is 0.
  10681. Use also @code{tripod} option of @ref{vidstabdetect}.
  10682. @item debug
  10683. Increase log verbosity if set to 1. Also the detected global motions
  10684. are written to the temporary file @file{global_motions.trf}. Default
  10685. value is 0.
  10686. @end table
  10687. @subsection Examples
  10688. @itemize
  10689. @item
  10690. Use @command{ffmpeg} for a typical stabilization with default values:
  10691. @example
  10692. ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
  10693. @end example
  10694. Note the use of the @ref{unsharp} filter which is always recommended.
  10695. @item
  10696. Zoom in a bit more and load transform data from a given file:
  10697. @example
  10698. vidstabtransform=zoom=5:input="mytransforms.trf"
  10699. @end example
  10700. @item
  10701. Smoothen the video even more:
  10702. @example
  10703. vidstabtransform=smoothing=30
  10704. @end example
  10705. @end itemize
  10706. @section vflip
  10707. Flip the input video vertically.
  10708. For example, to vertically flip a video with @command{ffmpeg}:
  10709. @example
  10710. ffmpeg -i in.avi -vf "vflip" out.avi
  10711. @end example
  10712. @anchor{vignette}
  10713. @section vignette
  10714. Make or reverse a natural vignetting effect.
  10715. The filter accepts the following options:
  10716. @table @option
  10717. @item angle, a
  10718. Set lens angle expression as a number of radians.
  10719. The value is clipped in the @code{[0,PI/2]} range.
  10720. Default value: @code{"PI/5"}
  10721. @item x0
  10722. @item y0
  10723. Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
  10724. by default.
  10725. @item mode
  10726. Set forward/backward mode.
  10727. Available modes are:
  10728. @table @samp
  10729. @item forward
  10730. The larger the distance from the central point, the darker the image becomes.
  10731. @item backward
  10732. The larger the distance from the central point, the brighter the image becomes.
  10733. This can be used to reverse a vignette effect, though there is no automatic
  10734. detection to extract the lens @option{angle} and other settings (yet). It can
  10735. also be used to create a burning effect.
  10736. @end table
  10737. Default value is @samp{forward}.
  10738. @item eval
  10739. Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
  10740. It accepts the following values:
  10741. @table @samp
  10742. @item init
  10743. Evaluate expressions only once during the filter initialization.
  10744. @item frame
  10745. Evaluate expressions for each incoming frame. This is way slower than the
  10746. @samp{init} mode since it requires all the scalers to be re-computed, but it
  10747. allows advanced dynamic expressions.
  10748. @end table
  10749. Default value is @samp{init}.
  10750. @item dither
  10751. Set dithering to reduce the circular banding effects. Default is @code{1}
  10752. (enabled).
  10753. @item aspect
  10754. Set vignette aspect. This setting allows one to adjust the shape of the vignette.
  10755. Setting this value to the SAR of the input will make a rectangular vignetting
  10756. following the dimensions of the video.
  10757. Default is @code{1/1}.
  10758. @end table
  10759. @subsection Expressions
  10760. The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
  10761. following parameters.
  10762. @table @option
  10763. @item w
  10764. @item h
  10765. input width and height
  10766. @item n
  10767. the number of input frame, starting from 0
  10768. @item pts
  10769. the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
  10770. @var{TB} units, NAN if undefined
  10771. @item r
  10772. frame rate of the input video, NAN if the input frame rate is unknown
  10773. @item t
  10774. the PTS (Presentation TimeStamp) of the filtered video frame,
  10775. expressed in seconds, NAN if undefined
  10776. @item tb
  10777. time base of the input video
  10778. @end table
  10779. @subsection Examples
  10780. @itemize
  10781. @item
  10782. Apply simple strong vignetting effect:
  10783. @example
  10784. vignette=PI/4
  10785. @end example
  10786. @item
  10787. Make a flickering vignetting:
  10788. @example
  10789. vignette='PI/4+random(1)*PI/50':eval=frame
  10790. @end example
  10791. @end itemize
  10792. @section vstack
  10793. Stack input videos vertically.
  10794. All streams must be of same pixel format and of same width.
  10795. Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
  10796. to create same output.
  10797. The filter accept the following option:
  10798. @table @option
  10799. @item inputs
  10800. Set number of input streams. Default is 2.
  10801. @item shortest
  10802. If set to 1, force the output to terminate when the shortest input
  10803. terminates. Default value is 0.
  10804. @end table
  10805. @section w3fdif
  10806. Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
  10807. Deinterlacing Filter").
  10808. Based on the process described by Martin Weston for BBC R&D, and
  10809. implemented based on the de-interlace algorithm written by Jim
  10810. Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
  10811. uses filter coefficients calculated by BBC R&D.
  10812. There are two sets of filter coefficients, so called "simple":
  10813. and "complex". Which set of filter coefficients is used can
  10814. be set by passing an optional parameter:
  10815. @table @option
  10816. @item filter
  10817. Set the interlacing filter coefficients. Accepts one of the following values:
  10818. @table @samp
  10819. @item simple
  10820. Simple filter coefficient set.
  10821. @item complex
  10822. More-complex filter coefficient set.
  10823. @end table
  10824. Default value is @samp{complex}.
  10825. @item deint
  10826. Specify which frames to deinterlace. Accept one of the following values:
  10827. @table @samp
  10828. @item all
  10829. Deinterlace all frames,
  10830. @item interlaced
  10831. Only deinterlace frames marked as interlaced.
  10832. @end table
  10833. Default value is @samp{all}.
  10834. @end table
  10835. @section waveform
  10836. Video waveform monitor.
  10837. The waveform monitor plots color component intensity. By default luminance
  10838. only. Each column of the waveform corresponds to a column of pixels in the
  10839. source video.
  10840. It accepts the following options:
  10841. @table @option
  10842. @item mode, m
  10843. Can be either @code{row}, or @code{column}. Default is @code{column}.
  10844. In row mode, the graph on the left side represents color component value 0 and
  10845. the right side represents value = 255. In column mode, the top side represents
  10846. color component value = 0 and bottom side represents value = 255.
  10847. @item intensity, i
  10848. Set intensity. Smaller values are useful to find out how many values of the same
  10849. luminance are distributed across input rows/columns.
  10850. Default value is @code{0.04}. Allowed range is [0, 1].
  10851. @item mirror, r
  10852. Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
  10853. In mirrored mode, higher values will be represented on the left
  10854. side for @code{row} mode and at the top for @code{column} mode. Default is
  10855. @code{1} (mirrored).
  10856. @item display, d
  10857. Set display mode.
  10858. It accepts the following values:
  10859. @table @samp
  10860. @item overlay
  10861. Presents information identical to that in the @code{parade}, except
  10862. that the graphs representing color components are superimposed directly
  10863. over one another.
  10864. This display mode makes it easier to spot relative differences or similarities
  10865. in overlapping areas of the color components that are supposed to be identical,
  10866. such as neutral whites, grays, or blacks.
  10867. @item stack
  10868. Display separate graph for the color components side by side in
  10869. @code{row} mode or one below the other in @code{column} mode.
  10870. @item parade
  10871. Display separate graph for the color components side by side in
  10872. @code{column} mode or one below the other in @code{row} mode.
  10873. Using this display mode makes it easy to spot color casts in the highlights
  10874. and shadows of an image, by comparing the contours of the top and the bottom
  10875. graphs of each waveform. Since whites, grays, and blacks are characterized
  10876. by exactly equal amounts of red, green, and blue, neutral areas of the picture
  10877. should display three waveforms of roughly equal width/height. If not, the
  10878. correction is easy to perform by making level adjustments the three waveforms.
  10879. @end table
  10880. Default is @code{stack}.
  10881. @item components, c
  10882. Set which color components to display. Default is 1, which means only luminance
  10883. or red color component if input is in RGB colorspace. If is set for example to
  10884. 7 it will display all 3 (if) available color components.
  10885. @item envelope, e
  10886. @table @samp
  10887. @item none
  10888. No envelope, this is default.
  10889. @item instant
  10890. Instant envelope, minimum and maximum values presented in graph will be easily
  10891. visible even with small @code{step} value.
  10892. @item peak
  10893. Hold minimum and maximum values presented in graph across time. This way you
  10894. can still spot out of range values without constantly looking at waveforms.
  10895. @item peak+instant
  10896. Peak and instant envelope combined together.
  10897. @end table
  10898. @item filter, f
  10899. @table @samp
  10900. @item lowpass
  10901. No filtering, this is default.
  10902. @item flat
  10903. Luma and chroma combined together.
  10904. @item aflat
  10905. Similar as above, but shows difference between blue and red chroma.
  10906. @item chroma
  10907. Displays only chroma.
  10908. @item color
  10909. Displays actual color value on waveform.
  10910. @item acolor
  10911. Similar as above, but with luma showing frequency of chroma values.
  10912. @end table
  10913. @item graticule, g
  10914. Set which graticule to display.
  10915. @table @samp
  10916. @item none
  10917. Do not display graticule.
  10918. @item green
  10919. Display green graticule showing legal broadcast ranges.
  10920. @end table
  10921. @item opacity, o
  10922. Set graticule opacity.
  10923. @item flags, fl
  10924. Set graticule flags.
  10925. @table @samp
  10926. @item numbers
  10927. Draw numbers above lines. By default enabled.
  10928. @item dots
  10929. Draw dots instead of lines.
  10930. @end table
  10931. @item scale, s
  10932. Set scale used for displaying graticule.
  10933. @table @samp
  10934. @item digital
  10935. @item millivolts
  10936. @item ire
  10937. @end table
  10938. Default is digital.
  10939. @item bgopacity, b
  10940. Set background opacity.
  10941. @end table
  10942. @section weave
  10943. The @code{weave} takes a field-based video input and join
  10944. each two sequential fields into single frame, producing a new double
  10945. height clip with half the frame rate and half the frame count.
  10946. It accepts the following option:
  10947. @table @option
  10948. @item first_field
  10949. Set first field. Available values are:
  10950. @table @samp
  10951. @item top, t
  10952. Set the frame as top-field-first.
  10953. @item bottom, b
  10954. Set the frame as bottom-field-first.
  10955. @end table
  10956. @end table
  10957. @subsection Examples
  10958. @itemize
  10959. @item
  10960. Interlace video using @ref{select} and @ref{separatefields} filter:
  10961. @example
  10962. separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
  10963. @end example
  10964. @end itemize
  10965. @section xbr
  10966. Apply the xBR high-quality magnification filter which is designed for pixel
  10967. art. It follows a set of edge-detection rules, see
  10968. @url{http://www.libretro.com/forums/viewtopic.php?f=6&t=134}.
  10969. It accepts the following option:
  10970. @table @option
  10971. @item n
  10972. Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
  10973. @code{3xBR} and @code{4} for @code{4xBR}.
  10974. Default is @code{3}.
  10975. @end table
  10976. @anchor{yadif}
  10977. @section yadif
  10978. Deinterlace the input video ("yadif" means "yet another deinterlacing
  10979. filter").
  10980. It accepts the following parameters:
  10981. @table @option
  10982. @item mode
  10983. The interlacing mode to adopt. It accepts one of the following values:
  10984. @table @option
  10985. @item 0, send_frame
  10986. Output one frame for each frame.
  10987. @item 1, send_field
  10988. Output one frame for each field.
  10989. @item 2, send_frame_nospatial
  10990. Like @code{send_frame}, but it skips the spatial interlacing check.
  10991. @item 3, send_field_nospatial
  10992. Like @code{send_field}, but it skips the spatial interlacing check.
  10993. @end table
  10994. The default value is @code{send_frame}.
  10995. @item parity
  10996. The picture field parity assumed for the input interlaced video. It accepts one
  10997. of the following values:
  10998. @table @option
  10999. @item 0, tff
  11000. Assume the top field is first.
  11001. @item 1, bff
  11002. Assume the bottom field is first.
  11003. @item -1, auto
  11004. Enable automatic detection of field parity.
  11005. @end table
  11006. The default value is @code{auto}.
  11007. If the interlacing is unknown or the decoder does not export this information,
  11008. top field first will be assumed.
  11009. @item deint
  11010. Specify which frames to deinterlace. Accept one of the following
  11011. values:
  11012. @table @option
  11013. @item 0, all
  11014. Deinterlace all frames.
  11015. @item 1, interlaced
  11016. Only deinterlace frames marked as interlaced.
  11017. @end table
  11018. The default value is @code{all}.
  11019. @end table
  11020. @section zoompan
  11021. Apply Zoom & Pan effect.
  11022. This filter accepts the following options:
  11023. @table @option
  11024. @item zoom, z
  11025. Set the zoom expression. Default is 1.
  11026. @item x
  11027. @item y
  11028. Set the x and y expression. Default is 0.
  11029. @item d
  11030. Set the duration expression in number of frames.
  11031. This sets for how many number of frames effect will last for
  11032. single input image.
  11033. @item s
  11034. Set the output image size, default is 'hd720'.
  11035. @item fps
  11036. Set the output frame rate, default is '25'.
  11037. @end table
  11038. Each expression can contain the following constants:
  11039. @table @option
  11040. @item in_w, iw
  11041. Input width.
  11042. @item in_h, ih
  11043. Input height.
  11044. @item out_w, ow
  11045. Output width.
  11046. @item out_h, oh
  11047. Output height.
  11048. @item in
  11049. Input frame count.
  11050. @item on
  11051. Output frame count.
  11052. @item x
  11053. @item y
  11054. Last calculated 'x' and 'y' position from 'x' and 'y' expression
  11055. for current input frame.
  11056. @item px
  11057. @item py
  11058. 'x' and 'y' of last output frame of previous input frame or 0 when there was
  11059. not yet such frame (first input frame).
  11060. @item zoom
  11061. Last calculated zoom from 'z' expression for current input frame.
  11062. @item pzoom
  11063. Last calculated zoom of last output frame of previous input frame.
  11064. @item duration
  11065. Number of output frames for current input frame. Calculated from 'd' expression
  11066. for each input frame.
  11067. @item pduration
  11068. number of output frames created for previous input frame
  11069. @item a
  11070. Rational number: input width / input height
  11071. @item sar
  11072. sample aspect ratio
  11073. @item dar
  11074. display aspect ratio
  11075. @end table
  11076. @subsection Examples
  11077. @itemize
  11078. @item
  11079. Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
  11080. @example
  11081. 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
  11082. @end example
  11083. @item
  11084. Zoom-in up to 1.5 and pan always at center of picture:
  11085. @example
  11086. zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
  11087. @end example
  11088. @item
  11089. Same as above but without pausing:
  11090. @example
  11091. zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
  11092. @end example
  11093. @end itemize
  11094. @section zscale
  11095. Scale (resize) the input video, using the z.lib library:
  11096. https://github.com/sekrit-twc/zimg.
  11097. The zscale filter forces the output display aspect ratio to be the same
  11098. as the input, by changing the output sample aspect ratio.
  11099. If the input image format is different from the format requested by
  11100. the next filter, the zscale filter will convert the input to the
  11101. requested format.
  11102. @subsection Options
  11103. The filter accepts the following options.
  11104. @table @option
  11105. @item width, w
  11106. @item height, h
  11107. Set the output video dimension expression. Default value is the input
  11108. dimension.
  11109. If the @var{width} or @var{w} is 0, the input width is used for the output.
  11110. If the @var{height} or @var{h} is 0, the input height is used for the output.
  11111. If one of the values is -1, the zscale filter will use a value that
  11112. maintains the aspect ratio of the input image, calculated from the
  11113. other specified dimension. If both of them are -1, the input size is
  11114. used
  11115. If one of the values is -n with n > 1, the zscale filter will also use a value
  11116. that maintains the aspect ratio of the input image, calculated from the other
  11117. specified dimension. After that it will, however, make sure that the calculated
  11118. dimension is divisible by n and adjust the value if necessary.
  11119. See below for the list of accepted constants for use in the dimension
  11120. expression.
  11121. @item size, s
  11122. Set the video size. For the syntax of this option, check the
  11123. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11124. @item dither, d
  11125. Set the dither type.
  11126. Possible values are:
  11127. @table @var
  11128. @item none
  11129. @item ordered
  11130. @item random
  11131. @item error_diffusion
  11132. @end table
  11133. Default is none.
  11134. @item filter, f
  11135. Set the resize filter type.
  11136. Possible values are:
  11137. @table @var
  11138. @item point
  11139. @item bilinear
  11140. @item bicubic
  11141. @item spline16
  11142. @item spline36
  11143. @item lanczos
  11144. @end table
  11145. Default is bilinear.
  11146. @item range, r
  11147. Set the color range.
  11148. Possible values are:
  11149. @table @var
  11150. @item input
  11151. @item limited
  11152. @item full
  11153. @end table
  11154. Default is same as input.
  11155. @item primaries, p
  11156. Set the color primaries.
  11157. Possible values are:
  11158. @table @var
  11159. @item input
  11160. @item 709
  11161. @item unspecified
  11162. @item 170m
  11163. @item 240m
  11164. @item 2020
  11165. @end table
  11166. Default is same as input.
  11167. @item transfer, t
  11168. Set the transfer characteristics.
  11169. Possible values are:
  11170. @table @var
  11171. @item input
  11172. @item 709
  11173. @item unspecified
  11174. @item 601
  11175. @item linear
  11176. @item 2020_10
  11177. @item 2020_12
  11178. @end table
  11179. Default is same as input.
  11180. @item matrix, m
  11181. Set the colorspace matrix.
  11182. Possible value are:
  11183. @table @var
  11184. @item input
  11185. @item 709
  11186. @item unspecified
  11187. @item 470bg
  11188. @item 170m
  11189. @item 2020_ncl
  11190. @item 2020_cl
  11191. @end table
  11192. Default is same as input.
  11193. @item rangein, rin
  11194. Set the input color range.
  11195. Possible values are:
  11196. @table @var
  11197. @item input
  11198. @item limited
  11199. @item full
  11200. @end table
  11201. Default is same as input.
  11202. @item primariesin, pin
  11203. Set the input color primaries.
  11204. Possible values are:
  11205. @table @var
  11206. @item input
  11207. @item 709
  11208. @item unspecified
  11209. @item 170m
  11210. @item 240m
  11211. @item 2020
  11212. @end table
  11213. Default is same as input.
  11214. @item transferin, tin
  11215. Set the input transfer characteristics.
  11216. Possible values are:
  11217. @table @var
  11218. @item input
  11219. @item 709
  11220. @item unspecified
  11221. @item 601
  11222. @item linear
  11223. @item 2020_10
  11224. @item 2020_12
  11225. @end table
  11226. Default is same as input.
  11227. @item matrixin, min
  11228. Set the input colorspace matrix.
  11229. Possible value are:
  11230. @table @var
  11231. @item input
  11232. @item 709
  11233. @item unspecified
  11234. @item 470bg
  11235. @item 170m
  11236. @item 2020_ncl
  11237. @item 2020_cl
  11238. @end table
  11239. @item chromal, c
  11240. Set the output chroma location.
  11241. Possible values are:
  11242. @table @var
  11243. @item input
  11244. @item left
  11245. @item center
  11246. @item topleft
  11247. @item top
  11248. @item bottomleft
  11249. @item bottom
  11250. @end table
  11251. @item chromalin, cin
  11252. Set the input chroma location.
  11253. Possible values are:
  11254. @table @var
  11255. @item input
  11256. @item left
  11257. @item center
  11258. @item topleft
  11259. @item top
  11260. @item bottomleft
  11261. @item bottom
  11262. @end table
  11263. @end table
  11264. The values of the @option{w} and @option{h} options are expressions
  11265. containing the following constants:
  11266. @table @var
  11267. @item in_w
  11268. @item in_h
  11269. The input width and height
  11270. @item iw
  11271. @item ih
  11272. These are the same as @var{in_w} and @var{in_h}.
  11273. @item out_w
  11274. @item out_h
  11275. The output (scaled) width and height
  11276. @item ow
  11277. @item oh
  11278. These are the same as @var{out_w} and @var{out_h}
  11279. @item a
  11280. The same as @var{iw} / @var{ih}
  11281. @item sar
  11282. input sample aspect ratio
  11283. @item dar
  11284. The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
  11285. @item hsub
  11286. @item vsub
  11287. horizontal and vertical input chroma subsample values. For example for the
  11288. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11289. @item ohsub
  11290. @item ovsub
  11291. horizontal and vertical output chroma subsample values. For example for the
  11292. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11293. @end table
  11294. @table @option
  11295. @end table
  11296. @c man end VIDEO FILTERS
  11297. @chapter Video Sources
  11298. @c man begin VIDEO SOURCES
  11299. Below is a description of the currently available video sources.
  11300. @section buffer
  11301. Buffer video frames, and make them available to the filter chain.
  11302. This source is mainly intended for a programmatic use, in particular
  11303. through the interface defined in @file{libavfilter/vsrc_buffer.h}.
  11304. It accepts the following parameters:
  11305. @table @option
  11306. @item video_size
  11307. Specify the size (width and height) of the buffered video frames. For the
  11308. syntax of this option, check the
  11309. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11310. @item width
  11311. The input video width.
  11312. @item height
  11313. The input video height.
  11314. @item pix_fmt
  11315. A string representing the pixel format of the buffered video frames.
  11316. It may be a number corresponding to a pixel format, or a pixel format
  11317. name.
  11318. @item time_base
  11319. Specify the timebase assumed by the timestamps of the buffered frames.
  11320. @item frame_rate
  11321. Specify the frame rate expected for the video stream.
  11322. @item pixel_aspect, sar
  11323. The sample (pixel) aspect ratio of the input video.
  11324. @item sws_param
  11325. Specify the optional parameters to be used for the scale filter which
  11326. is automatically inserted when an input change is detected in the
  11327. input size or format.
  11328. @item hw_frames_ctx
  11329. When using a hardware pixel format, this should be a reference to an
  11330. AVHWFramesContext describing input frames.
  11331. @end table
  11332. For example:
  11333. @example
  11334. buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
  11335. @end example
  11336. will instruct the source to accept video frames with size 320x240 and
  11337. with format "yuv410p", assuming 1/24 as the timestamps timebase and
  11338. square pixels (1:1 sample aspect ratio).
  11339. Since the pixel format with name "yuv410p" corresponds to the number 6
  11340. (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
  11341. this example corresponds to:
  11342. @example
  11343. buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
  11344. @end example
  11345. Alternatively, the options can be specified as a flat string, but this
  11346. syntax is deprecated:
  11347. @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}]
  11348. @section cellauto
  11349. Create a pattern generated by an elementary cellular automaton.
  11350. The initial state of the cellular automaton can be defined through the
  11351. @option{filename}, and @option{pattern} options. If such options are
  11352. not specified an initial state is created randomly.
  11353. At each new frame a new row in the video is filled with the result of
  11354. the cellular automaton next generation. The behavior when the whole
  11355. frame is filled is defined by the @option{scroll} option.
  11356. This source accepts the following options:
  11357. @table @option
  11358. @item filename, f
  11359. Read the initial cellular automaton state, i.e. the starting row, from
  11360. the specified file.
  11361. In the file, each non-whitespace character is considered an alive
  11362. cell, a newline will terminate the row, and further characters in the
  11363. file will be ignored.
  11364. @item pattern, p
  11365. Read the initial cellular automaton state, i.e. the starting row, from
  11366. the specified string.
  11367. Each non-whitespace character in the string is considered an alive
  11368. cell, a newline will terminate the row, and further characters in the
  11369. string will be ignored.
  11370. @item rate, r
  11371. Set the video rate, that is the number of frames generated per second.
  11372. Default is 25.
  11373. @item random_fill_ratio, ratio
  11374. Set the random fill ratio for the initial cellular automaton row. It
  11375. is a floating point number value ranging from 0 to 1, defaults to
  11376. 1/PHI.
  11377. This option is ignored when a file or a pattern is specified.
  11378. @item random_seed, seed
  11379. Set the seed for filling randomly the initial row, must be an integer
  11380. included between 0 and UINT32_MAX. If not specified, or if explicitly
  11381. set to -1, the filter will try to use a good random seed on a best
  11382. effort basis.
  11383. @item rule
  11384. Set the cellular automaton rule, it is a number ranging from 0 to 255.
  11385. Default value is 110.
  11386. @item size, s
  11387. Set the size of the output video. For the syntax of this option, check the
  11388. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11389. If @option{filename} or @option{pattern} is specified, the size is set
  11390. by default to the width of the specified initial state row, and the
  11391. height is set to @var{width} * PHI.
  11392. If @option{size} is set, it must contain the width of the specified
  11393. pattern string, and the specified pattern will be centered in the
  11394. larger row.
  11395. If a filename or a pattern string is not specified, the size value
  11396. defaults to "320x518" (used for a randomly generated initial state).
  11397. @item scroll
  11398. If set to 1, scroll the output upward when all the rows in the output
  11399. have been already filled. If set to 0, the new generated row will be
  11400. written over the top row just after the bottom row is filled.
  11401. Defaults to 1.
  11402. @item start_full, full
  11403. If set to 1, completely fill the output with generated rows before
  11404. outputting the first frame.
  11405. This is the default behavior, for disabling set the value to 0.
  11406. @item stitch
  11407. If set to 1, stitch the left and right row edges together.
  11408. This is the default behavior, for disabling set the value to 0.
  11409. @end table
  11410. @subsection Examples
  11411. @itemize
  11412. @item
  11413. Read the initial state from @file{pattern}, and specify an output of
  11414. size 200x400.
  11415. @example
  11416. cellauto=f=pattern:s=200x400
  11417. @end example
  11418. @item
  11419. Generate a random initial row with a width of 200 cells, with a fill
  11420. ratio of 2/3:
  11421. @example
  11422. cellauto=ratio=2/3:s=200x200
  11423. @end example
  11424. @item
  11425. Create a pattern generated by rule 18 starting by a single alive cell
  11426. centered on an initial row with width 100:
  11427. @example
  11428. cellauto=p=@@:s=100x400:full=0:rule=18
  11429. @end example
  11430. @item
  11431. Specify a more elaborated initial pattern:
  11432. @example
  11433. cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
  11434. @end example
  11435. @end itemize
  11436. @anchor{coreimagesrc}
  11437. @section coreimagesrc
  11438. Video source generated on GPU using Apple's CoreImage API on OSX.
  11439. This video source is a specialized version of the @ref{coreimage} video filter.
  11440. Use a core image generator at the beginning of the applied filterchain to
  11441. generate the content.
  11442. The coreimagesrc video source accepts the following options:
  11443. @table @option
  11444. @item list_generators
  11445. List all available generators along with all their respective options as well as
  11446. possible minimum and maximum values along with the default values.
  11447. @example
  11448. list_generators=true
  11449. @end example
  11450. @item size, s
  11451. Specify the size of the sourced video. For the syntax of this option, check the
  11452. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11453. The default value is @code{320x240}.
  11454. @item rate, r
  11455. Specify the frame rate of the sourced video, as the number of frames
  11456. generated per second. It has to be a string in the format
  11457. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  11458. number or a valid video frame rate abbreviation. The default value is
  11459. "25".
  11460. @item sar
  11461. Set the sample aspect ratio of the sourced video.
  11462. @item duration, d
  11463. Set the duration of the sourced video. See
  11464. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  11465. for the accepted syntax.
  11466. If not specified, or the expressed duration is negative, the video is
  11467. supposed to be generated forever.
  11468. @end table
  11469. Additionally, all options of the @ref{coreimage} video filter are accepted.
  11470. A complete filterchain can be used for further processing of the
  11471. generated input without CPU-HOST transfer. See @ref{coreimage} documentation
  11472. and examples for details.
  11473. @subsection Examples
  11474. @itemize
  11475. @item
  11476. Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
  11477. given as complete and escaped command-line for Apple's standard bash shell:
  11478. @example
  11479. ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
  11480. @end example
  11481. This example is equivalent to the QRCode example of @ref{coreimage} without the
  11482. need for a nullsrc video source.
  11483. @end itemize
  11484. @section mandelbrot
  11485. Generate a Mandelbrot set fractal, and progressively zoom towards the
  11486. point specified with @var{start_x} and @var{start_y}.
  11487. This source accepts the following options:
  11488. @table @option
  11489. @item end_pts
  11490. Set the terminal pts value. Default value is 400.
  11491. @item end_scale
  11492. Set the terminal scale value.
  11493. Must be a floating point value. Default value is 0.3.
  11494. @item inner
  11495. Set the inner coloring mode, that is the algorithm used to draw the
  11496. Mandelbrot fractal internal region.
  11497. It shall assume one of the following values:
  11498. @table @option
  11499. @item black
  11500. Set black mode.
  11501. @item convergence
  11502. Show time until convergence.
  11503. @item mincol
  11504. Set color based on point closest to the origin of the iterations.
  11505. @item period
  11506. Set period mode.
  11507. @end table
  11508. Default value is @var{mincol}.
  11509. @item bailout
  11510. Set the bailout value. Default value is 10.0.
  11511. @item maxiter
  11512. Set the maximum of iterations performed by the rendering
  11513. algorithm. Default value is 7189.
  11514. @item outer
  11515. Set outer coloring mode.
  11516. It shall assume one of following values:
  11517. @table @option
  11518. @item iteration_count
  11519. Set iteration cound mode.
  11520. @item normalized_iteration_count
  11521. set normalized iteration count mode.
  11522. @end table
  11523. Default value is @var{normalized_iteration_count}.
  11524. @item rate, r
  11525. Set frame rate, expressed as number of frames per second. Default
  11526. value is "25".
  11527. @item size, s
  11528. Set frame size. For the syntax of this option, check the "Video
  11529. size" section in the ffmpeg-utils manual. Default value is "640x480".
  11530. @item start_scale
  11531. Set the initial scale value. Default value is 3.0.
  11532. @item start_x
  11533. Set the initial x position. Must be a floating point value between
  11534. -100 and 100. Default value is -0.743643887037158704752191506114774.
  11535. @item start_y
  11536. Set the initial y position. Must be a floating point value between
  11537. -100 and 100. Default value is -0.131825904205311970493132056385139.
  11538. @end table
  11539. @section mptestsrc
  11540. Generate various test patterns, as generated by the MPlayer test filter.
  11541. The size of the generated video is fixed, and is 256x256.
  11542. This source is useful in particular for testing encoding features.
  11543. This source accepts the following options:
  11544. @table @option
  11545. @item rate, r
  11546. Specify the frame rate of the sourced video, as the number of frames
  11547. generated per second. It has to be a string in the format
  11548. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  11549. number or a valid video frame rate abbreviation. The default value is
  11550. "25".
  11551. @item duration, d
  11552. Set the duration of the sourced video. See
  11553. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  11554. for the accepted syntax.
  11555. If not specified, or the expressed duration is negative, the video is
  11556. supposed to be generated forever.
  11557. @item test, t
  11558. Set the number or the name of the test to perform. Supported tests are:
  11559. @table @option
  11560. @item dc_luma
  11561. @item dc_chroma
  11562. @item freq_luma
  11563. @item freq_chroma
  11564. @item amp_luma
  11565. @item amp_chroma
  11566. @item cbp
  11567. @item mv
  11568. @item ring1
  11569. @item ring2
  11570. @item all
  11571. @end table
  11572. Default value is "all", which will cycle through the list of all tests.
  11573. @end table
  11574. Some examples:
  11575. @example
  11576. mptestsrc=t=dc_luma
  11577. @end example
  11578. will generate a "dc_luma" test pattern.
  11579. @section frei0r_src
  11580. Provide a frei0r source.
  11581. To enable compilation of this filter you need to install the frei0r
  11582. header and configure FFmpeg with @code{--enable-frei0r}.
  11583. This source accepts the following parameters:
  11584. @table @option
  11585. @item size
  11586. The size of the video to generate. For the syntax of this option, check the
  11587. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11588. @item framerate
  11589. The framerate of the generated video. It may be a string of the form
  11590. @var{num}/@var{den} or a frame rate abbreviation.
  11591. @item filter_name
  11592. The name to the frei0r source to load. For more information regarding frei0r and
  11593. how to set the parameters, read the @ref{frei0r} section in the video filters
  11594. documentation.
  11595. @item filter_params
  11596. A '|'-separated list of parameters to pass to the frei0r source.
  11597. @end table
  11598. For example, to generate a frei0r partik0l source with size 200x200
  11599. and frame rate 10 which is overlaid on the overlay filter main input:
  11600. @example
  11601. frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
  11602. @end example
  11603. @section life
  11604. Generate a life pattern.
  11605. This source is based on a generalization of John Conway's life game.
  11606. The sourced input represents a life grid, each pixel represents a cell
  11607. which can be in one of two possible states, alive or dead. Every cell
  11608. interacts with its eight neighbours, which are the cells that are
  11609. horizontally, vertically, or diagonally adjacent.
  11610. At each interaction the grid evolves according to the adopted rule,
  11611. which specifies the number of neighbor alive cells which will make a
  11612. cell stay alive or born. The @option{rule} option allows one to specify
  11613. the rule to adopt.
  11614. This source accepts the following options:
  11615. @table @option
  11616. @item filename, f
  11617. Set the file from which to read the initial grid state. In the file,
  11618. each non-whitespace character is considered an alive cell, and newline
  11619. is used to delimit the end of each row.
  11620. If this option is not specified, the initial grid is generated
  11621. randomly.
  11622. @item rate, r
  11623. Set the video rate, that is the number of frames generated per second.
  11624. Default is 25.
  11625. @item random_fill_ratio, ratio
  11626. Set the random fill ratio for the initial random grid. It is a
  11627. floating point number value ranging from 0 to 1, defaults to 1/PHI.
  11628. It is ignored when a file is specified.
  11629. @item random_seed, seed
  11630. Set the seed for filling the initial random grid, must be an integer
  11631. included between 0 and UINT32_MAX. If not specified, or if explicitly
  11632. set to -1, the filter will try to use a good random seed on a best
  11633. effort basis.
  11634. @item rule
  11635. Set the life rule.
  11636. A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
  11637. where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
  11638. @var{NS} specifies the number of alive neighbor cells which make a
  11639. live cell stay alive, and @var{NB} the number of alive neighbor cells
  11640. which make a dead cell to become alive (i.e. to "born").
  11641. "s" and "b" can be used in place of "S" and "B", respectively.
  11642. Alternatively a rule can be specified by an 18-bits integer. The 9
  11643. high order bits are used to encode the next cell state if it is alive
  11644. for each number of neighbor alive cells, the low order bits specify
  11645. the rule for "borning" new cells. Higher order bits encode for an
  11646. higher number of neighbor cells.
  11647. For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
  11648. rule of 12 and a born rule of 9, which corresponds to "S23/B03".
  11649. Default value is "S23/B3", which is the original Conway's game of life
  11650. rule, and will keep a cell alive if it has 2 or 3 neighbor alive
  11651. cells, and will born a new cell if there are three alive cells around
  11652. a dead cell.
  11653. @item size, s
  11654. Set the size of the output video. For the syntax of this option, check the
  11655. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11656. If @option{filename} is specified, the size is set by default to the
  11657. same size of the input file. If @option{size} is set, it must contain
  11658. the size specified in the input file, and the initial grid defined in
  11659. that file is centered in the larger resulting area.
  11660. If a filename is not specified, the size value defaults to "320x240"
  11661. (used for a randomly generated initial grid).
  11662. @item stitch
  11663. If set to 1, stitch the left and right grid edges together, and the
  11664. top and bottom edges also. Defaults to 1.
  11665. @item mold
  11666. Set cell mold speed. If set, a dead cell will go from @option{death_color} to
  11667. @option{mold_color} with a step of @option{mold}. @option{mold} can have a
  11668. value from 0 to 255.
  11669. @item life_color
  11670. Set the color of living (or new born) cells.
  11671. @item death_color
  11672. Set the color of dead cells. If @option{mold} is set, this is the first color
  11673. used to represent a dead cell.
  11674. @item mold_color
  11675. Set mold color, for definitely dead and moldy cells.
  11676. For the syntax of these 3 color options, check the "Color" section in the
  11677. ffmpeg-utils manual.
  11678. @end table
  11679. @subsection Examples
  11680. @itemize
  11681. @item
  11682. Read a grid from @file{pattern}, and center it on a grid of size
  11683. 300x300 pixels:
  11684. @example
  11685. life=f=pattern:s=300x300
  11686. @end example
  11687. @item
  11688. Generate a random grid of size 200x200, with a fill ratio of 2/3:
  11689. @example
  11690. life=ratio=2/3:s=200x200
  11691. @end example
  11692. @item
  11693. Specify a custom rule for evolving a randomly generated grid:
  11694. @example
  11695. life=rule=S14/B34
  11696. @end example
  11697. @item
  11698. Full example with slow death effect (mold) using @command{ffplay}:
  11699. @example
  11700. ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
  11701. @end example
  11702. @end itemize
  11703. @anchor{allrgb}
  11704. @anchor{allyuv}
  11705. @anchor{color}
  11706. @anchor{haldclutsrc}
  11707. @anchor{nullsrc}
  11708. @anchor{rgbtestsrc}
  11709. @anchor{smptebars}
  11710. @anchor{smptehdbars}
  11711. @anchor{testsrc}
  11712. @anchor{testsrc2}
  11713. @anchor{yuvtestsrc}
  11714. @section allrgb, allyuv, color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
  11715. The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
  11716. The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
  11717. The @code{color} source provides an uniformly colored input.
  11718. The @code{haldclutsrc} source provides an identity Hald CLUT. See also
  11719. @ref{haldclut} filter.
  11720. The @code{nullsrc} source returns unprocessed video frames. It is
  11721. mainly useful to be employed in analysis / debugging tools, or as the
  11722. source for filters which ignore the input data.
  11723. The @code{rgbtestsrc} source generates an RGB test pattern useful for
  11724. detecting RGB vs BGR issues. You should see a red, green and blue
  11725. stripe from top to bottom.
  11726. The @code{smptebars} source generates a color bars pattern, based on
  11727. the SMPTE Engineering Guideline EG 1-1990.
  11728. The @code{smptehdbars} source generates a color bars pattern, based on
  11729. the SMPTE RP 219-2002.
  11730. The @code{testsrc} source generates a test video pattern, showing a
  11731. color pattern, a scrolling gradient and a timestamp. This is mainly
  11732. intended for testing purposes.
  11733. The @code{testsrc2} source is similar to testsrc, but supports more
  11734. pixel formats instead of just @code{rgb24}. This allows using it as an
  11735. input for other tests without requiring a format conversion.
  11736. The @code{yuvtestsrc} source generates an YUV test pattern. You should
  11737. see a y, cb and cr stripe from top to bottom.
  11738. The sources accept the following parameters:
  11739. @table @option
  11740. @item color, c
  11741. Specify the color of the source, only available in the @code{color}
  11742. source. For the syntax of this option, check the "Color" section in the
  11743. ffmpeg-utils manual.
  11744. @item level
  11745. Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
  11746. source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
  11747. pixels to be used as identity matrix for 3D lookup tables. Each component is
  11748. coded on a @code{1/(N*N)} scale.
  11749. @item size, s
  11750. Specify the size of the sourced video. For the syntax of this option, check the
  11751. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11752. The default value is @code{320x240}.
  11753. This option is not available with the @code{haldclutsrc} filter.
  11754. @item rate, r
  11755. Specify the frame rate of the sourced video, as the number of frames
  11756. generated per second. It has to be a string in the format
  11757. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  11758. number or a valid video frame rate abbreviation. The default value is
  11759. "25".
  11760. @item sar
  11761. Set the sample aspect ratio of the sourced video.
  11762. @item duration, d
  11763. Set the duration of the sourced video. See
  11764. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  11765. for the accepted syntax.
  11766. If not specified, or the expressed duration is negative, the video is
  11767. supposed to be generated forever.
  11768. @item decimals, n
  11769. Set the number of decimals to show in the timestamp, only available in the
  11770. @code{testsrc} source.
  11771. The displayed timestamp value will correspond to the original
  11772. timestamp value multiplied by the power of 10 of the specified
  11773. value. Default value is 0.
  11774. @end table
  11775. For example the following:
  11776. @example
  11777. testsrc=duration=5.3:size=qcif:rate=10
  11778. @end example
  11779. will generate a video with a duration of 5.3 seconds, with size
  11780. 176x144 and a frame rate of 10 frames per second.
  11781. The following graph description will generate a red source
  11782. with an opacity of 0.2, with size "qcif" and a frame rate of 10
  11783. frames per second.
  11784. @example
  11785. color=c=red@@0.2:s=qcif:r=10
  11786. @end example
  11787. If the input content is to be ignored, @code{nullsrc} can be used. The
  11788. following command generates noise in the luminance plane by employing
  11789. the @code{geq} filter:
  11790. @example
  11791. nullsrc=s=256x256, geq=random(1)*255:128:128
  11792. @end example
  11793. @subsection Commands
  11794. The @code{color} source supports the following commands:
  11795. @table @option
  11796. @item c, color
  11797. Set the color of the created image. Accepts the same syntax of the
  11798. corresponding @option{color} option.
  11799. @end table
  11800. @c man end VIDEO SOURCES
  11801. @chapter Video Sinks
  11802. @c man begin VIDEO SINKS
  11803. Below is a description of the currently available video sinks.
  11804. @section buffersink
  11805. Buffer video frames, and make them available to the end of the filter
  11806. graph.
  11807. This sink is mainly intended for programmatic use, in particular
  11808. through the interface defined in @file{libavfilter/buffersink.h}
  11809. or the options system.
  11810. It accepts a pointer to an AVBufferSinkContext structure, which
  11811. defines the incoming buffers' formats, to be passed as the opaque
  11812. parameter to @code{avfilter_init_filter} for initialization.
  11813. @section nullsink
  11814. Null video sink: do absolutely nothing with the input video. It is
  11815. mainly useful as a template and for use in analysis / debugging
  11816. tools.
  11817. @c man end VIDEO SINKS
  11818. @chapter Multimedia Filters
  11819. @c man begin MULTIMEDIA FILTERS
  11820. Below is a description of the currently available multimedia filters.
  11821. @section ahistogram
  11822. Convert input audio to a video output, displaying the volume histogram.
  11823. The filter accepts the following options:
  11824. @table @option
  11825. @item dmode
  11826. Specify how histogram is calculated.
  11827. It accepts the following values:
  11828. @table @samp
  11829. @item single
  11830. Use single histogram for all channels.
  11831. @item separate
  11832. Use separate histogram for each channel.
  11833. @end table
  11834. Default is @code{single}.
  11835. @item rate, r
  11836. Set frame rate, expressed as number of frames per second. Default
  11837. value is "25".
  11838. @item size, s
  11839. Specify the video size for the output. For the syntax of this option, check the
  11840. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11841. Default value is @code{hd720}.
  11842. @item scale
  11843. Set display scale.
  11844. It accepts the following values:
  11845. @table @samp
  11846. @item log
  11847. logarithmic
  11848. @item sqrt
  11849. square root
  11850. @item cbrt
  11851. cubic root
  11852. @item lin
  11853. linear
  11854. @item rlog
  11855. reverse logarithmic
  11856. @end table
  11857. Default is @code{log}.
  11858. @item ascale
  11859. Set amplitude scale.
  11860. It accepts the following values:
  11861. @table @samp
  11862. @item log
  11863. logarithmic
  11864. @item lin
  11865. linear
  11866. @end table
  11867. Default is @code{log}.
  11868. @item acount
  11869. Set how much frames to accumulate in histogram.
  11870. Defauls is 1. Setting this to -1 accumulates all frames.
  11871. @item rheight
  11872. Set histogram ratio of window height.
  11873. @item slide
  11874. Set sonogram sliding.
  11875. It accepts the following values:
  11876. @table @samp
  11877. @item replace
  11878. replace old rows with new ones.
  11879. @item scroll
  11880. scroll from top to bottom.
  11881. @end table
  11882. Default is @code{replace}.
  11883. @end table
  11884. @section aphasemeter
  11885. Convert input audio to a video output, displaying the audio phase.
  11886. The filter accepts the following options:
  11887. @table @option
  11888. @item rate, r
  11889. Set the output frame rate. Default value is @code{25}.
  11890. @item size, s
  11891. Set the video size for the output. For the syntax of this option, check the
  11892. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11893. Default value is @code{800x400}.
  11894. @item rc
  11895. @item gc
  11896. @item bc
  11897. Specify the red, green, blue contrast. Default values are @code{2},
  11898. @code{7} and @code{1}.
  11899. Allowed range is @code{[0, 255]}.
  11900. @item mpc
  11901. Set color which will be used for drawing median phase. If color is
  11902. @code{none} which is default, no median phase value will be drawn.
  11903. @end table
  11904. The filter also exports the frame metadata @code{lavfi.aphasemeter.phase} which
  11905. represents mean phase of current audio frame. Value is in range @code{[-1, 1]}.
  11906. The @code{-1} means left and right channels are completely out of phase and
  11907. @code{1} means channels are in phase.
  11908. @section avectorscope
  11909. Convert input audio to a video output, representing the audio vector
  11910. scope.
  11911. The filter is used to measure the difference between channels of stereo
  11912. audio stream. A monoaural signal, consisting of identical left and right
  11913. signal, results in straight vertical line. Any stereo separation is visible
  11914. as a deviation from this line, creating a Lissajous figure.
  11915. If the straight (or deviation from it) but horizontal line appears this
  11916. indicates that the left and right channels are out of phase.
  11917. The filter accepts the following options:
  11918. @table @option
  11919. @item mode, m
  11920. Set the vectorscope mode.
  11921. Available values are:
  11922. @table @samp
  11923. @item lissajous
  11924. Lissajous rotated by 45 degrees.
  11925. @item lissajous_xy
  11926. Same as above but not rotated.
  11927. @item polar
  11928. Shape resembling half of circle.
  11929. @end table
  11930. Default value is @samp{lissajous}.
  11931. @item size, s
  11932. Set the video size for the output. For the syntax of this option, check the
  11933. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11934. Default value is @code{400x400}.
  11935. @item rate, r
  11936. Set the output frame rate. Default value is @code{25}.
  11937. @item rc
  11938. @item gc
  11939. @item bc
  11940. @item ac
  11941. Specify the red, green, blue and alpha contrast. Default values are @code{40},
  11942. @code{160}, @code{80} and @code{255}.
  11943. Allowed range is @code{[0, 255]}.
  11944. @item rf
  11945. @item gf
  11946. @item bf
  11947. @item af
  11948. Specify the red, green, blue and alpha fade. Default values are @code{15},
  11949. @code{10}, @code{5} and @code{5}.
  11950. Allowed range is @code{[0, 255]}.
  11951. @item zoom
  11952. Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}.
  11953. @item draw
  11954. Set the vectorscope drawing mode.
  11955. Available values are:
  11956. @table @samp
  11957. @item dot
  11958. Draw dot for each sample.
  11959. @item line
  11960. Draw line between previous and current sample.
  11961. @end table
  11962. Default value is @samp{dot}.
  11963. @item scale
  11964. Specify amplitude scale of audio samples.
  11965. Available values are:
  11966. @table @samp
  11967. @item lin
  11968. Linear.
  11969. @item sqrt
  11970. Square root.
  11971. @item cbrt
  11972. Cubic root.
  11973. @item log
  11974. Logarithmic.
  11975. @end table
  11976. @end table
  11977. @subsection Examples
  11978. @itemize
  11979. @item
  11980. Complete example using @command{ffplay}:
  11981. @example
  11982. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  11983. [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
  11984. @end example
  11985. @end itemize
  11986. @section bench, abench
  11987. Benchmark part of a filtergraph.
  11988. The filter accepts the following options:
  11989. @table @option
  11990. @item action
  11991. Start or stop a timer.
  11992. Available values are:
  11993. @table @samp
  11994. @item start
  11995. Get the current time, set it as frame metadata (using the key
  11996. @code{lavfi.bench.start_time}), and forward the frame to the next filter.
  11997. @item stop
  11998. Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
  11999. the input frame metadata to get the time difference. Time difference, average,
  12000. maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
  12001. @code{min}) are then printed. The timestamps are expressed in seconds.
  12002. @end table
  12003. @end table
  12004. @subsection Examples
  12005. @itemize
  12006. @item
  12007. Benchmark @ref{selectivecolor} filter:
  12008. @example
  12009. bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
  12010. @end example
  12011. @end itemize
  12012. @section concat
  12013. Concatenate audio and video streams, joining them together one after the
  12014. other.
  12015. The filter works on segments of synchronized video and audio streams. All
  12016. segments must have the same number of streams of each type, and that will
  12017. also be the number of streams at output.
  12018. The filter accepts the following options:
  12019. @table @option
  12020. @item n
  12021. Set the number of segments. Default is 2.
  12022. @item v
  12023. Set the number of output video streams, that is also the number of video
  12024. streams in each segment. Default is 1.
  12025. @item a
  12026. Set the number of output audio streams, that is also the number of audio
  12027. streams in each segment. Default is 0.
  12028. @item unsafe
  12029. Activate unsafe mode: do not fail if segments have a different format.
  12030. @end table
  12031. The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
  12032. @var{a} audio outputs.
  12033. There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
  12034. segment, in the same order as the outputs, then the inputs for the second
  12035. segment, etc.
  12036. Related streams do not always have exactly the same duration, for various
  12037. reasons including codec frame size or sloppy authoring. For that reason,
  12038. related synchronized streams (e.g. a video and its audio track) should be
  12039. concatenated at once. The concat filter will use the duration of the longest
  12040. stream in each segment (except the last one), and if necessary pad shorter
  12041. audio streams with silence.
  12042. For this filter to work correctly, all segments must start at timestamp 0.
  12043. All corresponding streams must have the same parameters in all segments; the
  12044. filtering system will automatically select a common pixel format for video
  12045. streams, and a common sample format, sample rate and channel layout for
  12046. audio streams, but other settings, such as resolution, must be converted
  12047. explicitly by the user.
  12048. Different frame rates are acceptable but will result in variable frame rate
  12049. at output; be sure to configure the output file to handle it.
  12050. @subsection Examples
  12051. @itemize
  12052. @item
  12053. Concatenate an opening, an episode and an ending, all in bilingual version
  12054. (video in stream 0, audio in streams 1 and 2):
  12055. @example
  12056. ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
  12057. '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
  12058. concat=n=3:v=1:a=2 [v] [a1] [a2]' \
  12059. -map '[v]' -map '[a1]' -map '[a2]' output.mkv
  12060. @end example
  12061. @item
  12062. Concatenate two parts, handling audio and video separately, using the
  12063. (a)movie sources, and adjusting the resolution:
  12064. @example
  12065. movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
  12066. movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
  12067. [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
  12068. @end example
  12069. Note that a desync will happen at the stitch if the audio and video streams
  12070. do not have exactly the same duration in the first file.
  12071. @end itemize
  12072. @section drawgraph, adrawgraph
  12073. Draw a graph using input video or audio metadata.
  12074. It accepts the following parameters:
  12075. @table @option
  12076. @item m1
  12077. Set 1st frame metadata key from which metadata values will be used to draw a graph.
  12078. @item fg1
  12079. Set 1st foreground color expression.
  12080. @item m2
  12081. Set 2nd frame metadata key from which metadata values will be used to draw a graph.
  12082. @item fg2
  12083. Set 2nd foreground color expression.
  12084. @item m3
  12085. Set 3rd frame metadata key from which metadata values will be used to draw a graph.
  12086. @item fg3
  12087. Set 3rd foreground color expression.
  12088. @item m4
  12089. Set 4th frame metadata key from which metadata values will be used to draw a graph.
  12090. @item fg4
  12091. Set 4th foreground color expression.
  12092. @item min
  12093. Set minimal value of metadata value.
  12094. @item max
  12095. Set maximal value of metadata value.
  12096. @item bg
  12097. Set graph background color. Default is white.
  12098. @item mode
  12099. Set graph mode.
  12100. Available values for mode is:
  12101. @table @samp
  12102. @item bar
  12103. @item dot
  12104. @item line
  12105. @end table
  12106. Default is @code{line}.
  12107. @item slide
  12108. Set slide mode.
  12109. Available values for slide is:
  12110. @table @samp
  12111. @item frame
  12112. Draw new frame when right border is reached.
  12113. @item replace
  12114. Replace old columns with new ones.
  12115. @item scroll
  12116. Scroll from right to left.
  12117. @item rscroll
  12118. Scroll from left to right.
  12119. @item picture
  12120. Draw single picture.
  12121. @end table
  12122. Default is @code{frame}.
  12123. @item size
  12124. Set size of graph video. For the syntax of this option, check the
  12125. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12126. The default value is @code{900x256}.
  12127. The foreground color expressions can use the following variables:
  12128. @table @option
  12129. @item MIN
  12130. Minimal value of metadata value.
  12131. @item MAX
  12132. Maximal value of metadata value.
  12133. @item VAL
  12134. Current metadata key value.
  12135. @end table
  12136. The color is defined as 0xAABBGGRR.
  12137. @end table
  12138. Example using metadata from @ref{signalstats} filter:
  12139. @example
  12140. signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
  12141. @end example
  12142. Example using metadata from @ref{ebur128} filter:
  12143. @example
  12144. ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
  12145. @end example
  12146. @anchor{ebur128}
  12147. @section ebur128
  12148. EBU R128 scanner filter. This filter takes an audio stream as input and outputs
  12149. it unchanged. By default, it logs a message at a frequency of 10Hz with the
  12150. Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
  12151. Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
  12152. The filter also has a video output (see the @var{video} option) with a real
  12153. time graph to observe the loudness evolution. The graphic contains the logged
  12154. message mentioned above, so it is not printed anymore when this option is set,
  12155. unless the verbose logging is set. The main graphing area contains the
  12156. short-term loudness (3 seconds of analysis), and the gauge on the right is for
  12157. the momentary loudness (400 milliseconds).
  12158. More information about the Loudness Recommendation EBU R128 on
  12159. @url{http://tech.ebu.ch/loudness}.
  12160. The filter accepts the following options:
  12161. @table @option
  12162. @item video
  12163. Activate the video output. The audio stream is passed unchanged whether this
  12164. option is set or no. The video stream will be the first output stream if
  12165. activated. Default is @code{0}.
  12166. @item size
  12167. Set the video size. This option is for video only. For the syntax of this
  12168. option, check the
  12169. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12170. Default and minimum resolution is @code{640x480}.
  12171. @item meter
  12172. Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
  12173. @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
  12174. other integer value between this range is allowed.
  12175. @item metadata
  12176. Set metadata injection. If set to @code{1}, the audio input will be segmented
  12177. into 100ms output frames, each of them containing various loudness information
  12178. in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
  12179. Default is @code{0}.
  12180. @item framelog
  12181. Force the frame logging level.
  12182. Available values are:
  12183. @table @samp
  12184. @item info
  12185. information logging level
  12186. @item verbose
  12187. verbose logging level
  12188. @end table
  12189. By default, the logging level is set to @var{info}. If the @option{video} or
  12190. the @option{metadata} options are set, it switches to @var{verbose}.
  12191. @item peak
  12192. Set peak mode(s).
  12193. Available modes can be cumulated (the option is a @code{flag} type). Possible
  12194. values are:
  12195. @table @samp
  12196. @item none
  12197. Disable any peak mode (default).
  12198. @item sample
  12199. Enable sample-peak mode.
  12200. Simple peak mode looking for the higher sample value. It logs a message
  12201. for sample-peak (identified by @code{SPK}).
  12202. @item true
  12203. Enable true-peak mode.
  12204. If enabled, the peak lookup is done on an over-sampled version of the input
  12205. stream for better peak accuracy. It logs a message for true-peak.
  12206. (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
  12207. This mode requires a build with @code{libswresample}.
  12208. @end table
  12209. @item dualmono
  12210. Treat mono input files as "dual mono". If a mono file is intended for playback
  12211. on a stereo system, its EBU R128 measurement will be perceptually incorrect.
  12212. If set to @code{true}, this option will compensate for this effect.
  12213. Multi-channel input files are not affected by this option.
  12214. @item panlaw
  12215. Set a specific pan law to be used for the measurement of dual mono files.
  12216. This parameter is optional, and has a default value of -3.01dB.
  12217. @end table
  12218. @subsection Examples
  12219. @itemize
  12220. @item
  12221. Real-time graph using @command{ffplay}, with a EBU scale meter +18:
  12222. @example
  12223. ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
  12224. @end example
  12225. @item
  12226. Run an analysis with @command{ffmpeg}:
  12227. @example
  12228. ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
  12229. @end example
  12230. @end itemize
  12231. @section interleave, ainterleave
  12232. Temporally interleave frames from several inputs.
  12233. @code{interleave} works with video inputs, @code{ainterleave} with audio.
  12234. These filters read frames from several inputs and send the oldest
  12235. queued frame to the output.
  12236. Input streams must have a well defined, monotonically increasing frame
  12237. timestamp values.
  12238. In order to submit one frame to output, these filters need to enqueue
  12239. at least one frame for each input, so they cannot work in case one
  12240. input is not yet terminated and will not receive incoming frames.
  12241. For example consider the case when one input is a @code{select} filter
  12242. which always drop input frames. The @code{interleave} filter will keep
  12243. reading from that input, but it will never be able to send new frames
  12244. to output until the input will send an end-of-stream signal.
  12245. Also, depending on inputs synchronization, the filters will drop
  12246. frames in case one input receives more frames than the other ones, and
  12247. the queue is already filled.
  12248. These filters accept the following options:
  12249. @table @option
  12250. @item nb_inputs, n
  12251. Set the number of different inputs, it is 2 by default.
  12252. @end table
  12253. @subsection Examples
  12254. @itemize
  12255. @item
  12256. Interleave frames belonging to different streams using @command{ffmpeg}:
  12257. @example
  12258. ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
  12259. @end example
  12260. @item
  12261. Add flickering blur effect:
  12262. @example
  12263. select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
  12264. @end example
  12265. @end itemize
  12266. @section metadata, ametadata
  12267. Manipulate frame metadata.
  12268. This filter accepts the following options:
  12269. @table @option
  12270. @item mode
  12271. Set mode of operation of the filter.
  12272. Can be one of the following:
  12273. @table @samp
  12274. @item select
  12275. If both @code{value} and @code{key} is set, select frames
  12276. which have such metadata. If only @code{key} is set, select
  12277. every frame that has such key in metadata.
  12278. @item add
  12279. Add new metadata @code{key} and @code{value}. If key is already available
  12280. do nothing.
  12281. @item modify
  12282. Modify value of already present key.
  12283. @item delete
  12284. If @code{value} is set, delete only keys that have such value.
  12285. Otherwise, delete key.
  12286. @item print
  12287. Print key and its value if metadata was found. If @code{key} is not set print all
  12288. metadata values available in frame.
  12289. @end table
  12290. @item key
  12291. Set key used with all modes. Must be set for all modes except @code{print}.
  12292. @item value
  12293. Set metadata value which will be used. This option is mandatory for
  12294. @code{modify} and @code{add} mode.
  12295. @item function
  12296. Which function to use when comparing metadata value and @code{value}.
  12297. Can be one of following:
  12298. @table @samp
  12299. @item same_str
  12300. Values are interpreted as strings, returns true if metadata value is same as @code{value}.
  12301. @item starts_with
  12302. Values are interpreted as strings, returns true if metadata value starts with
  12303. the @code{value} option string.
  12304. @item less
  12305. Values are interpreted as floats, returns true if metadata value is less than @code{value}.
  12306. @item equal
  12307. Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
  12308. @item greater
  12309. Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
  12310. @item expr
  12311. Values are interpreted as floats, returns true if expression from option @code{expr}
  12312. evaluates to true.
  12313. @end table
  12314. @item expr
  12315. Set expression which is used when @code{function} is set to @code{expr}.
  12316. The expression is evaluated through the eval API and can contain the following
  12317. constants:
  12318. @table @option
  12319. @item VALUE1
  12320. Float representation of @code{value} from metadata key.
  12321. @item VALUE2
  12322. Float representation of @code{value} as supplied by user in @code{value} option.
  12323. @item file
  12324. If specified in @code{print} mode, output is written to the named file. Instead of
  12325. plain filename any writable url can be specified. Filename ``-'' is a shorthand
  12326. for standard output. If @code{file} option is not set, output is written to the log
  12327. with AV_LOG_INFO loglevel.
  12328. @end table
  12329. @end table
  12330. @subsection Examples
  12331. @itemize
  12332. @item
  12333. Print all metadata values for frames with key @code{lavfi.singnalstats.YDIF} with values
  12334. between 0 and 1.
  12335. @example
  12336. signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
  12337. @end example
  12338. @item
  12339. Print silencedetect output to file @file{metadata.txt}.
  12340. @example
  12341. silencedetect,ametadata=mode=print:file=metadata.txt
  12342. @end example
  12343. @item
  12344. Direct all metadata to a pipe with file descriptor 4.
  12345. @example
  12346. metadata=mode=print:file='pipe\:4'
  12347. @end example
  12348. @end itemize
  12349. @section perms, aperms
  12350. Set read/write permissions for the output frames.
  12351. These filters are mainly aimed at developers to test direct path in the
  12352. following filter in the filtergraph.
  12353. The filters accept the following options:
  12354. @table @option
  12355. @item mode
  12356. Select the permissions mode.
  12357. It accepts the following values:
  12358. @table @samp
  12359. @item none
  12360. Do nothing. This is the default.
  12361. @item ro
  12362. Set all the output frames read-only.
  12363. @item rw
  12364. Set all the output frames directly writable.
  12365. @item toggle
  12366. Make the frame read-only if writable, and writable if read-only.
  12367. @item random
  12368. Set each output frame read-only or writable randomly.
  12369. @end table
  12370. @item seed
  12371. Set the seed for the @var{random} mode, must be an integer included between
  12372. @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
  12373. @code{-1}, the filter will try to use a good random seed on a best effort
  12374. basis.
  12375. @end table
  12376. Note: in case of auto-inserted filter between the permission filter and the
  12377. following one, the permission might not be received as expected in that
  12378. following filter. Inserting a @ref{format} or @ref{aformat} filter before the
  12379. perms/aperms filter can avoid this problem.
  12380. @section realtime, arealtime
  12381. Slow down filtering to match real time approximatively.
  12382. These filters will pause the filtering for a variable amount of time to
  12383. match the output rate with the input timestamps.
  12384. They are similar to the @option{re} option to @code{ffmpeg}.
  12385. They accept the following options:
  12386. @table @option
  12387. @item limit
  12388. Time limit for the pauses. Any pause longer than that will be considered
  12389. a timestamp discontinuity and reset the timer. Default is 2 seconds.
  12390. @end table
  12391. @anchor{select}
  12392. @section select, aselect
  12393. Select frames to pass in output.
  12394. This filter accepts the following options:
  12395. @table @option
  12396. @item expr, e
  12397. Set expression, which is evaluated for each input frame.
  12398. If the expression is evaluated to zero, the frame is discarded.
  12399. If the evaluation result is negative or NaN, the frame is sent to the
  12400. first output; otherwise it is sent to the output with index
  12401. @code{ceil(val)-1}, assuming that the input index starts from 0.
  12402. For example a value of @code{1.2} corresponds to the output with index
  12403. @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
  12404. @item outputs, n
  12405. Set the number of outputs. The output to which to send the selected
  12406. frame is based on the result of the evaluation. Default value is 1.
  12407. @end table
  12408. The expression can contain the following constants:
  12409. @table @option
  12410. @item n
  12411. The (sequential) number of the filtered frame, starting from 0.
  12412. @item selected_n
  12413. The (sequential) number of the selected frame, starting from 0.
  12414. @item prev_selected_n
  12415. The sequential number of the last selected frame. It's NAN if undefined.
  12416. @item TB
  12417. The timebase of the input timestamps.
  12418. @item pts
  12419. The PTS (Presentation TimeStamp) of the filtered video frame,
  12420. expressed in @var{TB} units. It's NAN if undefined.
  12421. @item t
  12422. The PTS of the filtered video frame,
  12423. expressed in seconds. It's NAN if undefined.
  12424. @item prev_pts
  12425. The PTS of the previously filtered video frame. It's NAN if undefined.
  12426. @item prev_selected_pts
  12427. The PTS of the last previously filtered video frame. It's NAN if undefined.
  12428. @item prev_selected_t
  12429. The PTS of the last previously selected video frame. It's NAN if undefined.
  12430. @item start_pts
  12431. The PTS of the first video frame in the video. It's NAN if undefined.
  12432. @item start_t
  12433. The time of the first video frame in the video. It's NAN if undefined.
  12434. @item pict_type @emph{(video only)}
  12435. The type of the filtered frame. It can assume one of the following
  12436. values:
  12437. @table @option
  12438. @item I
  12439. @item P
  12440. @item B
  12441. @item S
  12442. @item SI
  12443. @item SP
  12444. @item BI
  12445. @end table
  12446. @item interlace_type @emph{(video only)}
  12447. The frame interlace type. It can assume one of the following values:
  12448. @table @option
  12449. @item PROGRESSIVE
  12450. The frame is progressive (not interlaced).
  12451. @item TOPFIRST
  12452. The frame is top-field-first.
  12453. @item BOTTOMFIRST
  12454. The frame is bottom-field-first.
  12455. @end table
  12456. @item consumed_sample_n @emph{(audio only)}
  12457. the number of selected samples before the current frame
  12458. @item samples_n @emph{(audio only)}
  12459. the number of samples in the current frame
  12460. @item sample_rate @emph{(audio only)}
  12461. the input sample rate
  12462. @item key
  12463. This is 1 if the filtered frame is a key-frame, 0 otherwise.
  12464. @item pos
  12465. the position in the file of the filtered frame, -1 if the information
  12466. is not available (e.g. for synthetic video)
  12467. @item scene @emph{(video only)}
  12468. value between 0 and 1 to indicate a new scene; a low value reflects a low
  12469. probability for the current frame to introduce a new scene, while a higher
  12470. value means the current frame is more likely to be one (see the example below)
  12471. @item concatdec_select
  12472. The concat demuxer can select only part of a concat input file by setting an
  12473. inpoint and an outpoint, but the output packets may not be entirely contained
  12474. in the selected interval. By using this variable, it is possible to skip frames
  12475. generated by the concat demuxer which are not exactly contained in the selected
  12476. interval.
  12477. This works by comparing the frame pts against the @var{lavf.concat.start_time}
  12478. and the @var{lavf.concat.duration} packet metadata values which are also
  12479. present in the decoded frames.
  12480. The @var{concatdec_select} variable is -1 if the frame pts is at least
  12481. start_time and either the duration metadata is missing or the frame pts is less
  12482. than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
  12483. missing.
  12484. That basically means that an input frame is selected if its pts is within the
  12485. interval set by the concat demuxer.
  12486. @end table
  12487. The default value of the select expression is "1".
  12488. @subsection Examples
  12489. @itemize
  12490. @item
  12491. Select all frames in input:
  12492. @example
  12493. select
  12494. @end example
  12495. The example above is the same as:
  12496. @example
  12497. select=1
  12498. @end example
  12499. @item
  12500. Skip all frames:
  12501. @example
  12502. select=0
  12503. @end example
  12504. @item
  12505. Select only I-frames:
  12506. @example
  12507. select='eq(pict_type\,I)'
  12508. @end example
  12509. @item
  12510. Select one frame every 100:
  12511. @example
  12512. select='not(mod(n\,100))'
  12513. @end example
  12514. @item
  12515. Select only frames contained in the 10-20 time interval:
  12516. @example
  12517. select=between(t\,10\,20)
  12518. @end example
  12519. @item
  12520. Select only I-frames contained in the 10-20 time interval:
  12521. @example
  12522. select=between(t\,10\,20)*eq(pict_type\,I)
  12523. @end example
  12524. @item
  12525. Select frames with a minimum distance of 10 seconds:
  12526. @example
  12527. select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
  12528. @end example
  12529. @item
  12530. Use aselect to select only audio frames with samples number > 100:
  12531. @example
  12532. aselect='gt(samples_n\,100)'
  12533. @end example
  12534. @item
  12535. Create a mosaic of the first scenes:
  12536. @example
  12537. ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
  12538. @end example
  12539. Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
  12540. choice.
  12541. @item
  12542. Send even and odd frames to separate outputs, and compose them:
  12543. @example
  12544. select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
  12545. @end example
  12546. @item
  12547. Select useful frames from an ffconcat file which is using inpoints and
  12548. outpoints but where the source files are not intra frame only.
  12549. @example
  12550. ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
  12551. @end example
  12552. @end itemize
  12553. @section sendcmd, asendcmd
  12554. Send commands to filters in the filtergraph.
  12555. These filters read commands to be sent to other filters in the
  12556. filtergraph.
  12557. @code{sendcmd} must be inserted between two video filters,
  12558. @code{asendcmd} must be inserted between two audio filters, but apart
  12559. from that they act the same way.
  12560. The specification of commands can be provided in the filter arguments
  12561. with the @var{commands} option, or in a file specified by the
  12562. @var{filename} option.
  12563. These filters accept the following options:
  12564. @table @option
  12565. @item commands, c
  12566. Set the commands to be read and sent to the other filters.
  12567. @item filename, f
  12568. Set the filename of the commands to be read and sent to the other
  12569. filters.
  12570. @end table
  12571. @subsection Commands syntax
  12572. A commands description consists of a sequence of interval
  12573. specifications, comprising a list of commands to be executed when a
  12574. particular event related to that interval occurs. The occurring event
  12575. is typically the current frame time entering or leaving a given time
  12576. interval.
  12577. An interval is specified by the following syntax:
  12578. @example
  12579. @var{START}[-@var{END}] @var{COMMANDS};
  12580. @end example
  12581. The time interval is specified by the @var{START} and @var{END} times.
  12582. @var{END} is optional and defaults to the maximum time.
  12583. The current frame time is considered within the specified interval if
  12584. it is included in the interval [@var{START}, @var{END}), that is when
  12585. the time is greater or equal to @var{START} and is lesser than
  12586. @var{END}.
  12587. @var{COMMANDS} consists of a sequence of one or more command
  12588. specifications, separated by ",", relating to that interval. The
  12589. syntax of a command specification is given by:
  12590. @example
  12591. [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
  12592. @end example
  12593. @var{FLAGS} is optional and specifies the type of events relating to
  12594. the time interval which enable sending the specified command, and must
  12595. be a non-null sequence of identifier flags separated by "+" or "|" and
  12596. enclosed between "[" and "]".
  12597. The following flags are recognized:
  12598. @table @option
  12599. @item enter
  12600. The command is sent when the current frame timestamp enters the
  12601. specified interval. In other words, the command is sent when the
  12602. previous frame timestamp was not in the given interval, and the
  12603. current is.
  12604. @item leave
  12605. The command is sent when the current frame timestamp leaves the
  12606. specified interval. In other words, the command is sent when the
  12607. previous frame timestamp was in the given interval, and the
  12608. current is not.
  12609. @end table
  12610. If @var{FLAGS} is not specified, a default value of @code{[enter]} is
  12611. assumed.
  12612. @var{TARGET} specifies the target of the command, usually the name of
  12613. the filter class or a specific filter instance name.
  12614. @var{COMMAND} specifies the name of the command for the target filter.
  12615. @var{ARG} is optional and specifies the optional list of argument for
  12616. the given @var{COMMAND}.
  12617. Between one interval specification and another, whitespaces, or
  12618. sequences of characters starting with @code{#} until the end of line,
  12619. are ignored and can be used to annotate comments.
  12620. A simplified BNF description of the commands specification syntax
  12621. follows:
  12622. @example
  12623. @var{COMMAND_FLAG} ::= "enter" | "leave"
  12624. @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
  12625. @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
  12626. @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
  12627. @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
  12628. @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
  12629. @end example
  12630. @subsection Examples
  12631. @itemize
  12632. @item
  12633. Specify audio tempo change at second 4:
  12634. @example
  12635. asendcmd=c='4.0 atempo tempo 1.5',atempo
  12636. @end example
  12637. @item
  12638. Specify a list of drawtext and hue commands in a file.
  12639. @example
  12640. # show text in the interval 5-10
  12641. 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
  12642. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
  12643. # desaturate the image in the interval 15-20
  12644. 15.0-20.0 [enter] hue s 0,
  12645. [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
  12646. [leave] hue s 1,
  12647. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
  12648. # apply an exponential saturation fade-out effect, starting from time 25
  12649. 25 [enter] hue s exp(25-t)
  12650. @end example
  12651. A filtergraph allowing to read and process the above command list
  12652. stored in a file @file{test.cmd}, can be specified with:
  12653. @example
  12654. sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
  12655. @end example
  12656. @end itemize
  12657. @anchor{setpts}
  12658. @section setpts, asetpts
  12659. Change the PTS (presentation timestamp) of the input frames.
  12660. @code{setpts} works on video frames, @code{asetpts} on audio frames.
  12661. This filter accepts the following options:
  12662. @table @option
  12663. @item expr
  12664. The expression which is evaluated for each frame to construct its timestamp.
  12665. @end table
  12666. The expression is evaluated through the eval API and can contain the following
  12667. constants:
  12668. @table @option
  12669. @item FRAME_RATE
  12670. frame rate, only defined for constant frame-rate video
  12671. @item PTS
  12672. The presentation timestamp in input
  12673. @item N
  12674. The count of the input frame for video or the number of consumed samples,
  12675. not including the current frame for audio, starting from 0.
  12676. @item NB_CONSUMED_SAMPLES
  12677. The number of consumed samples, not including the current frame (only
  12678. audio)
  12679. @item NB_SAMPLES, S
  12680. The number of samples in the current frame (only audio)
  12681. @item SAMPLE_RATE, SR
  12682. The audio sample rate.
  12683. @item STARTPTS
  12684. The PTS of the first frame.
  12685. @item STARTT
  12686. the time in seconds of the first frame
  12687. @item INTERLACED
  12688. State whether the current frame is interlaced.
  12689. @item T
  12690. the time in seconds of the current frame
  12691. @item POS
  12692. original position in the file of the frame, or undefined if undefined
  12693. for the current frame
  12694. @item PREV_INPTS
  12695. The previous input PTS.
  12696. @item PREV_INT
  12697. previous input time in seconds
  12698. @item PREV_OUTPTS
  12699. The previous output PTS.
  12700. @item PREV_OUTT
  12701. previous output time in seconds
  12702. @item RTCTIME
  12703. The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
  12704. instead.
  12705. @item RTCSTART
  12706. The wallclock (RTC) time at the start of the movie in microseconds.
  12707. @item TB
  12708. The timebase of the input timestamps.
  12709. @end table
  12710. @subsection Examples
  12711. @itemize
  12712. @item
  12713. Start counting PTS from zero
  12714. @example
  12715. setpts=PTS-STARTPTS
  12716. @end example
  12717. @item
  12718. Apply fast motion effect:
  12719. @example
  12720. setpts=0.5*PTS
  12721. @end example
  12722. @item
  12723. Apply slow motion effect:
  12724. @example
  12725. setpts=2.0*PTS
  12726. @end example
  12727. @item
  12728. Set fixed rate of 25 frames per second:
  12729. @example
  12730. setpts=N/(25*TB)
  12731. @end example
  12732. @item
  12733. Set fixed rate 25 fps with some jitter:
  12734. @example
  12735. setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
  12736. @end example
  12737. @item
  12738. Apply an offset of 10 seconds to the input PTS:
  12739. @example
  12740. setpts=PTS+10/TB
  12741. @end example
  12742. @item
  12743. Generate timestamps from a "live source" and rebase onto the current timebase:
  12744. @example
  12745. setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
  12746. @end example
  12747. @item
  12748. Generate timestamps by counting samples:
  12749. @example
  12750. asetpts=N/SR/TB
  12751. @end example
  12752. @end itemize
  12753. @section settb, asettb
  12754. Set the timebase to use for the output frames timestamps.
  12755. It is mainly useful for testing timebase configuration.
  12756. It accepts the following parameters:
  12757. @table @option
  12758. @item expr, tb
  12759. The expression which is evaluated into the output timebase.
  12760. @end table
  12761. The value for @option{tb} is an arithmetic expression representing a
  12762. rational. The expression can contain the constants "AVTB" (the default
  12763. timebase), "intb" (the input timebase) and "sr" (the sample rate,
  12764. audio only). Default value is "intb".
  12765. @subsection Examples
  12766. @itemize
  12767. @item
  12768. Set the timebase to 1/25:
  12769. @example
  12770. settb=expr=1/25
  12771. @end example
  12772. @item
  12773. Set the timebase to 1/10:
  12774. @example
  12775. settb=expr=0.1
  12776. @end example
  12777. @item
  12778. Set the timebase to 1001/1000:
  12779. @example
  12780. settb=1+0.001
  12781. @end example
  12782. @item
  12783. Set the timebase to 2*intb:
  12784. @example
  12785. settb=2*intb
  12786. @end example
  12787. @item
  12788. Set the default timebase value:
  12789. @example
  12790. settb=AVTB
  12791. @end example
  12792. @end itemize
  12793. @section showcqt
  12794. Convert input audio to a video output representing frequency spectrum
  12795. logarithmically using Brown-Puckette constant Q transform algorithm with
  12796. direct frequency domain coefficient calculation (but the transform itself
  12797. is not really constant Q, instead the Q factor is actually variable/clamped),
  12798. with musical tone scale, from E0 to D#10.
  12799. The filter accepts the following options:
  12800. @table @option
  12801. @item size, s
  12802. Specify the video size for the output. It must be even. For the syntax of this option,
  12803. check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12804. Default value is @code{1920x1080}.
  12805. @item fps, rate, r
  12806. Set the output frame rate. Default value is @code{25}.
  12807. @item bar_h
  12808. Set the bargraph height. It must be even. Default value is @code{-1} which
  12809. computes the bargraph height automatically.
  12810. @item axis_h
  12811. Set the axis height. It must be even. Default value is @code{-1} which computes
  12812. the axis height automatically.
  12813. @item sono_h
  12814. Set the sonogram height. It must be even. Default value is @code{-1} which
  12815. computes the sonogram height automatically.
  12816. @item fullhd
  12817. Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
  12818. instead. Default value is @code{1}.
  12819. @item sono_v, volume
  12820. Specify the sonogram volume expression. It can contain variables:
  12821. @table @option
  12822. @item bar_v
  12823. the @var{bar_v} evaluated expression
  12824. @item frequency, freq, f
  12825. the frequency where it is evaluated
  12826. @item timeclamp, tc
  12827. the value of @var{timeclamp} option
  12828. @end table
  12829. and functions:
  12830. @table @option
  12831. @item a_weighting(f)
  12832. A-weighting of equal loudness
  12833. @item b_weighting(f)
  12834. B-weighting of equal loudness
  12835. @item c_weighting(f)
  12836. C-weighting of equal loudness.
  12837. @end table
  12838. Default value is @code{16}.
  12839. @item bar_v, volume2
  12840. Specify the bargraph volume expression. It can contain variables:
  12841. @table @option
  12842. @item sono_v
  12843. the @var{sono_v} evaluated expression
  12844. @item frequency, freq, f
  12845. the frequency where it is evaluated
  12846. @item timeclamp, tc
  12847. the value of @var{timeclamp} option
  12848. @end table
  12849. and functions:
  12850. @table @option
  12851. @item a_weighting(f)
  12852. A-weighting of equal loudness
  12853. @item b_weighting(f)
  12854. B-weighting of equal loudness
  12855. @item c_weighting(f)
  12856. C-weighting of equal loudness.
  12857. @end table
  12858. Default value is @code{sono_v}.
  12859. @item sono_g, gamma
  12860. Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
  12861. higher gamma makes the spectrum having more range. Default value is @code{3}.
  12862. Acceptable range is @code{[1, 7]}.
  12863. @item bar_g, gamma2
  12864. Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
  12865. @code{[1, 7]}.
  12866. @item timeclamp, tc
  12867. Specify the transform timeclamp. At low frequency, there is trade-off between
  12868. accuracy in time domain and frequency domain. If timeclamp is lower,
  12869. event in time domain is represented more accurately (such as fast bass drum),
  12870. otherwise event in frequency domain is represented more accurately
  12871. (such as bass guitar). Acceptable range is @code{[0.1, 1]}. Default value is @code{0.17}.
  12872. @item basefreq
  12873. Specify the transform base frequency. Default value is @code{20.01523126408007475},
  12874. which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
  12875. @item endfreq
  12876. Specify the transform end frequency. Default value is @code{20495.59681441799654},
  12877. which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
  12878. @item coeffclamp
  12879. This option is deprecated and ignored.
  12880. @item tlength
  12881. Specify the transform length in time domain. Use this option to control accuracy
  12882. trade-off between time domain and frequency domain at every frequency sample.
  12883. It can contain variables:
  12884. @table @option
  12885. @item frequency, freq, f
  12886. the frequency where it is evaluated
  12887. @item timeclamp, tc
  12888. the value of @var{timeclamp} option.
  12889. @end table
  12890. Default value is @code{384*tc/(384+tc*f)}.
  12891. @item count
  12892. Specify the transform count for every video frame. Default value is @code{6}.
  12893. Acceptable range is @code{[1, 30]}.
  12894. @item fcount
  12895. Specify the transform count for every single pixel. Default value is @code{0},
  12896. which makes it computed automatically. Acceptable range is @code{[0, 10]}.
  12897. @item fontfile
  12898. Specify font file for use with freetype to draw the axis. If not specified,
  12899. use embedded font. Note that drawing with font file or embedded font is not
  12900. implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
  12901. option instead.
  12902. @item fontcolor
  12903. Specify font color expression. This is arithmetic expression that should return
  12904. integer value 0xRRGGBB. It can contain variables:
  12905. @table @option
  12906. @item frequency, freq, f
  12907. the frequency where it is evaluated
  12908. @item timeclamp, tc
  12909. the value of @var{timeclamp} option
  12910. @end table
  12911. and functions:
  12912. @table @option
  12913. @item midi(f)
  12914. midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
  12915. @item r(x), g(x), b(x)
  12916. red, green, and blue value of intensity x.
  12917. @end table
  12918. Default value is @code{st(0, (midi(f)-59.5)/12);
  12919. st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
  12920. r(1-ld(1)) + b(ld(1))}.
  12921. @item axisfile
  12922. Specify image file to draw the axis. This option override @var{fontfile} and
  12923. @var{fontcolor} option.
  12924. @item axis, text
  12925. Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
  12926. the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
  12927. Default value is @code{1}.
  12928. @end table
  12929. @subsection Examples
  12930. @itemize
  12931. @item
  12932. Playing audio while showing the spectrum:
  12933. @example
  12934. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
  12935. @end example
  12936. @item
  12937. Same as above, but with frame rate 30 fps:
  12938. @example
  12939. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
  12940. @end example
  12941. @item
  12942. Playing at 1280x720:
  12943. @example
  12944. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
  12945. @end example
  12946. @item
  12947. Disable sonogram display:
  12948. @example
  12949. sono_h=0
  12950. @end example
  12951. @item
  12952. A1 and its harmonics: A1, A2, (near)E3, A3:
  12953. @example
  12954. 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),
  12955. asplit[a][out1]; [a] showcqt [out0]'
  12956. @end example
  12957. @item
  12958. Same as above, but with more accuracy in frequency domain:
  12959. @example
  12960. 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),
  12961. asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
  12962. @end example
  12963. @item
  12964. Custom volume:
  12965. @example
  12966. bar_v=10:sono_v=bar_v*a_weighting(f)
  12967. @end example
  12968. @item
  12969. Custom gamma, now spectrum is linear to the amplitude.
  12970. @example
  12971. bar_g=2:sono_g=2
  12972. @end example
  12973. @item
  12974. Custom tlength equation:
  12975. @example
  12976. tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'
  12977. @end example
  12978. @item
  12979. Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
  12980. @example
  12981. fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
  12982. @end example
  12983. @item
  12984. Custom frequency range with custom axis using image file:
  12985. @example
  12986. axisfile=myaxis.png:basefreq=40:endfreq=10000
  12987. @end example
  12988. @end itemize
  12989. @section showfreqs
  12990. Convert input audio to video output representing the audio power spectrum.
  12991. Audio amplitude is on Y-axis while frequency is on X-axis.
  12992. The filter accepts the following options:
  12993. @table @option
  12994. @item size, s
  12995. Specify size of video. For the syntax of this option, check the
  12996. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12997. Default is @code{1024x512}.
  12998. @item mode
  12999. Set display mode.
  13000. This set how each frequency bin will be represented.
  13001. It accepts the following values:
  13002. @table @samp
  13003. @item line
  13004. @item bar
  13005. @item dot
  13006. @end table
  13007. Default is @code{bar}.
  13008. @item ascale
  13009. Set amplitude scale.
  13010. It accepts the following values:
  13011. @table @samp
  13012. @item lin
  13013. Linear scale.
  13014. @item sqrt
  13015. Square root scale.
  13016. @item cbrt
  13017. Cubic root scale.
  13018. @item log
  13019. Logarithmic scale.
  13020. @end table
  13021. Default is @code{log}.
  13022. @item fscale
  13023. Set frequency scale.
  13024. It accepts the following values:
  13025. @table @samp
  13026. @item lin
  13027. Linear scale.
  13028. @item log
  13029. Logarithmic scale.
  13030. @item rlog
  13031. Reverse logarithmic scale.
  13032. @end table
  13033. Default is @code{lin}.
  13034. @item win_size
  13035. Set window size.
  13036. It accepts the following values:
  13037. @table @samp
  13038. @item w16
  13039. @item w32
  13040. @item w64
  13041. @item w128
  13042. @item w256
  13043. @item w512
  13044. @item w1024
  13045. @item w2048
  13046. @item w4096
  13047. @item w8192
  13048. @item w16384
  13049. @item w32768
  13050. @item w65536
  13051. @end table
  13052. Default is @code{w2048}
  13053. @item win_func
  13054. Set windowing function.
  13055. It accepts the following values:
  13056. @table @samp
  13057. @item rect
  13058. @item bartlett
  13059. @item hanning
  13060. @item hamming
  13061. @item blackman
  13062. @item welch
  13063. @item flattop
  13064. @item bharris
  13065. @item bnuttall
  13066. @item bhann
  13067. @item sine
  13068. @item nuttall
  13069. @item lanczos
  13070. @item gauss
  13071. @item tukey
  13072. @item dolph
  13073. @item cauchy
  13074. @item parzen
  13075. @item poisson
  13076. @end table
  13077. Default is @code{hanning}.
  13078. @item overlap
  13079. Set window overlap. In range @code{[0, 1]}. Default is @code{1},
  13080. which means optimal overlap for selected window function will be picked.
  13081. @item averaging
  13082. Set time averaging. Setting this to 0 will display current maximal peaks.
  13083. Default is @code{1}, which means time averaging is disabled.
  13084. @item colors
  13085. Specify list of colors separated by space or by '|' which will be used to
  13086. draw channel frequencies. Unrecognized or missing colors will be replaced
  13087. by white color.
  13088. @item cmode
  13089. Set channel display mode.
  13090. It accepts the following values:
  13091. @table @samp
  13092. @item combined
  13093. @item separate
  13094. @end table
  13095. Default is @code{combined}.
  13096. @item minamp
  13097. Set minimum amplitude used in @code{log} amplitude scaler.
  13098. @end table
  13099. @anchor{showspectrum}
  13100. @section showspectrum
  13101. Convert input audio to a video output, representing the audio frequency
  13102. spectrum.
  13103. The filter accepts the following options:
  13104. @table @option
  13105. @item size, s
  13106. Specify the video size for the output. For the syntax of this option, check the
  13107. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  13108. Default value is @code{640x512}.
  13109. @item slide
  13110. Specify how the spectrum should slide along the window.
  13111. It accepts the following values:
  13112. @table @samp
  13113. @item replace
  13114. the samples start again on the left when they reach the right
  13115. @item scroll
  13116. the samples scroll from right to left
  13117. @item fullframe
  13118. frames are only produced when the samples reach the right
  13119. @item rscroll
  13120. the samples scroll from left to right
  13121. @end table
  13122. Default value is @code{replace}.
  13123. @item mode
  13124. Specify display mode.
  13125. It accepts the following values:
  13126. @table @samp
  13127. @item combined
  13128. all channels are displayed in the same row
  13129. @item separate
  13130. all channels are displayed in separate rows
  13131. @end table
  13132. Default value is @samp{combined}.
  13133. @item color
  13134. Specify display color mode.
  13135. It accepts the following values:
  13136. @table @samp
  13137. @item channel
  13138. each channel is displayed in a separate color
  13139. @item intensity
  13140. each channel is displayed using the same color scheme
  13141. @item rainbow
  13142. each channel is displayed using the rainbow color scheme
  13143. @item moreland
  13144. each channel is displayed using the moreland color scheme
  13145. @item nebulae
  13146. each channel is displayed using the nebulae color scheme
  13147. @item fire
  13148. each channel is displayed using the fire color scheme
  13149. @item fiery
  13150. each channel is displayed using the fiery color scheme
  13151. @item fruit
  13152. each channel is displayed using the fruit color scheme
  13153. @item cool
  13154. each channel is displayed using the cool color scheme
  13155. @end table
  13156. Default value is @samp{channel}.
  13157. @item scale
  13158. Specify scale used for calculating intensity color values.
  13159. It accepts the following values:
  13160. @table @samp
  13161. @item lin
  13162. linear
  13163. @item sqrt
  13164. square root, default
  13165. @item cbrt
  13166. cubic root
  13167. @item log
  13168. logarithmic
  13169. @item 4thrt
  13170. 4th root
  13171. @item 5thrt
  13172. 5th root
  13173. @end table
  13174. Default value is @samp{sqrt}.
  13175. @item saturation
  13176. Set saturation modifier for displayed colors. Negative values provide
  13177. alternative color scheme. @code{0} is no saturation at all.
  13178. Saturation must be in [-10.0, 10.0] range.
  13179. Default value is @code{1}.
  13180. @item win_func
  13181. Set window function.
  13182. It accepts the following values:
  13183. @table @samp
  13184. @item rect
  13185. @item bartlett
  13186. @item hann
  13187. @item hanning
  13188. @item hamming
  13189. @item blackman
  13190. @item welch
  13191. @item flattop
  13192. @item bharris
  13193. @item bnuttall
  13194. @item bhann
  13195. @item sine
  13196. @item nuttall
  13197. @item lanczos
  13198. @item gauss
  13199. @item tukey
  13200. @item dolph
  13201. @item cauchy
  13202. @item parzen
  13203. @item poisson
  13204. @end table
  13205. Default value is @code{hann}.
  13206. @item orientation
  13207. Set orientation of time vs frequency axis. Can be @code{vertical} or
  13208. @code{horizontal}. Default is @code{vertical}.
  13209. @item overlap
  13210. Set ratio of overlap window. Default value is @code{0}.
  13211. When value is @code{1} overlap is set to recommended size for specific
  13212. window function currently used.
  13213. @item gain
  13214. Set scale gain for calculating intensity color values.
  13215. Default value is @code{1}.
  13216. @item data
  13217. Set which data to display. Can be @code{magnitude}, default or @code{phase}.
  13218. @item rotation
  13219. Set color rotation, must be in [-1.0, 1.0] range.
  13220. Default value is @code{0}.
  13221. @end table
  13222. The usage is very similar to the showwaves filter; see the examples in that
  13223. section.
  13224. @subsection Examples
  13225. @itemize
  13226. @item
  13227. Large window with logarithmic color scaling:
  13228. @example
  13229. showspectrum=s=1280x480:scale=log
  13230. @end example
  13231. @item
  13232. Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
  13233. @example
  13234. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  13235. [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
  13236. @end example
  13237. @end itemize
  13238. @section showspectrumpic
  13239. Convert input audio to a single video frame, representing the audio frequency
  13240. spectrum.
  13241. The filter accepts the following options:
  13242. @table @option
  13243. @item size, s
  13244. Specify the video size for the output. For the syntax of this option, check the
  13245. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  13246. Default value is @code{4096x2048}.
  13247. @item mode
  13248. Specify display mode.
  13249. It accepts the following values:
  13250. @table @samp
  13251. @item combined
  13252. all channels are displayed in the same row
  13253. @item separate
  13254. all channels are displayed in separate rows
  13255. @end table
  13256. Default value is @samp{combined}.
  13257. @item color
  13258. Specify display color mode.
  13259. It accepts the following values:
  13260. @table @samp
  13261. @item channel
  13262. each channel is displayed in a separate color
  13263. @item intensity
  13264. each channel is displayed using the same color scheme
  13265. @item rainbow
  13266. each channel is displayed using the rainbow color scheme
  13267. @item moreland
  13268. each channel is displayed using the moreland color scheme
  13269. @item nebulae
  13270. each channel is displayed using the nebulae color scheme
  13271. @item fire
  13272. each channel is displayed using the fire color scheme
  13273. @item fiery
  13274. each channel is displayed using the fiery color scheme
  13275. @item fruit
  13276. each channel is displayed using the fruit color scheme
  13277. @item cool
  13278. each channel is displayed using the cool color scheme
  13279. @end table
  13280. Default value is @samp{intensity}.
  13281. @item scale
  13282. Specify scale used for calculating intensity color values.
  13283. It accepts the following values:
  13284. @table @samp
  13285. @item lin
  13286. linear
  13287. @item sqrt
  13288. square root, default
  13289. @item cbrt
  13290. cubic root
  13291. @item log
  13292. logarithmic
  13293. @item 4thrt
  13294. 4th root
  13295. @item 5thrt
  13296. 5th root
  13297. @end table
  13298. Default value is @samp{log}.
  13299. @item saturation
  13300. Set saturation modifier for displayed colors. Negative values provide
  13301. alternative color scheme. @code{0} is no saturation at all.
  13302. Saturation must be in [-10.0, 10.0] range.
  13303. Default value is @code{1}.
  13304. @item win_func
  13305. Set window function.
  13306. It accepts the following values:
  13307. @table @samp
  13308. @item rect
  13309. @item bartlett
  13310. @item hann
  13311. @item hanning
  13312. @item hamming
  13313. @item blackman
  13314. @item welch
  13315. @item flattop
  13316. @item bharris
  13317. @item bnuttall
  13318. @item bhann
  13319. @item sine
  13320. @item nuttall
  13321. @item lanczos
  13322. @item gauss
  13323. @item tukey
  13324. @item dolph
  13325. @item cauchy
  13326. @item parzen
  13327. @item poisson
  13328. @end table
  13329. Default value is @code{hann}.
  13330. @item orientation
  13331. Set orientation of time vs frequency axis. Can be @code{vertical} or
  13332. @code{horizontal}. Default is @code{vertical}.
  13333. @item gain
  13334. Set scale gain for calculating intensity color values.
  13335. Default value is @code{1}.
  13336. @item legend
  13337. Draw time and frequency axes and legends. Default is enabled.
  13338. @item rotation
  13339. Set color rotation, must be in [-1.0, 1.0] range.
  13340. Default value is @code{0}.
  13341. @end table
  13342. @subsection Examples
  13343. @itemize
  13344. @item
  13345. Extract an audio spectrogram of a whole audio track
  13346. in a 1024x1024 picture using @command{ffmpeg}:
  13347. @example
  13348. ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
  13349. @end example
  13350. @end itemize
  13351. @section showvolume
  13352. Convert input audio volume to a video output.
  13353. The filter accepts the following options:
  13354. @table @option
  13355. @item rate, r
  13356. Set video rate.
  13357. @item b
  13358. Set border width, allowed range is [0, 5]. Default is 1.
  13359. @item w
  13360. Set channel width, allowed range is [80, 8192]. Default is 400.
  13361. @item h
  13362. Set channel height, allowed range is [1, 900]. Default is 20.
  13363. @item f
  13364. Set fade, allowed range is [0.001, 1]. Default is 0.95.
  13365. @item c
  13366. Set volume color expression.
  13367. The expression can use the following variables:
  13368. @table @option
  13369. @item VOLUME
  13370. Current max volume of channel in dB.
  13371. @item PEAK
  13372. Current peak.
  13373. @item CHANNEL
  13374. Current channel number, starting from 0.
  13375. @end table
  13376. @item t
  13377. If set, displays channel names. Default is enabled.
  13378. @item v
  13379. If set, displays volume values. Default is enabled.
  13380. @item o
  13381. Set orientation, can be @code{horizontal} or @code{vertical},
  13382. default is @code{horizontal}.
  13383. @item s
  13384. Set step size, allowed range s [0, 5]. Default is 0, which means
  13385. step is disabled.
  13386. @end table
  13387. @section showwaves
  13388. Convert input audio to a video output, representing the samples waves.
  13389. The filter accepts the following options:
  13390. @table @option
  13391. @item size, s
  13392. Specify the video size for the output. For the syntax of this option, check the
  13393. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  13394. Default value is @code{600x240}.
  13395. @item mode
  13396. Set display mode.
  13397. Available values are:
  13398. @table @samp
  13399. @item point
  13400. Draw a point for each sample.
  13401. @item line
  13402. Draw a vertical line for each sample.
  13403. @item p2p
  13404. Draw a point for each sample and a line between them.
  13405. @item cline
  13406. Draw a centered vertical line for each sample.
  13407. @end table
  13408. Default value is @code{point}.
  13409. @item n
  13410. Set the number of samples which are printed on the same column. A
  13411. larger value will decrease the frame rate. Must be a positive
  13412. integer. This option can be set only if the value for @var{rate}
  13413. is not explicitly specified.
  13414. @item rate, r
  13415. Set the (approximate) output frame rate. This is done by setting the
  13416. option @var{n}. Default value is "25".
  13417. @item split_channels
  13418. Set if channels should be drawn separately or overlap. Default value is 0.
  13419. @item colors
  13420. Set colors separated by '|' which are going to be used for drawing of each channel.
  13421. @item scale
  13422. Set amplitude scale.
  13423. Available values are:
  13424. @table @samp
  13425. @item lin
  13426. Linear.
  13427. @item log
  13428. Logarithmic.
  13429. @item sqrt
  13430. Square root.
  13431. @item cbrt
  13432. Cubic root.
  13433. @end table
  13434. Default is linear.
  13435. @end table
  13436. @subsection Examples
  13437. @itemize
  13438. @item
  13439. Output the input file audio and the corresponding video representation
  13440. at the same time:
  13441. @example
  13442. amovie=a.mp3,asplit[out0],showwaves[out1]
  13443. @end example
  13444. @item
  13445. Create a synthetic signal and show it with showwaves, forcing a
  13446. frame rate of 30 frames per second:
  13447. @example
  13448. aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
  13449. @end example
  13450. @end itemize
  13451. @section showwavespic
  13452. Convert input audio to a single video frame, representing the samples waves.
  13453. The filter accepts the following options:
  13454. @table @option
  13455. @item size, s
  13456. Specify the video size for the output. For the syntax of this option, check the
  13457. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  13458. Default value is @code{600x240}.
  13459. @item split_channels
  13460. Set if channels should be drawn separately or overlap. Default value is 0.
  13461. @item colors
  13462. Set colors separated by '|' which are going to be used for drawing of each channel.
  13463. @item scale
  13464. Set amplitude scale. Can be linear @code{lin} or logarithmic @code{log}.
  13465. Default is linear.
  13466. @end table
  13467. @subsection Examples
  13468. @itemize
  13469. @item
  13470. Extract a channel split representation of the wave form of a whole audio track
  13471. in a 1024x800 picture using @command{ffmpeg}:
  13472. @example
  13473. ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
  13474. @end example
  13475. @end itemize
  13476. @section spectrumsynth
  13477. Sythesize audio from 2 input video spectrums, first input stream represents
  13478. magnitude across time and second represents phase across time.
  13479. The filter will transform from frequency domain as displayed in videos back
  13480. to time domain as presented in audio output.
  13481. This filter is primarly created for reversing processed @ref{showspectrum}
  13482. filter outputs, but can synthesize sound from other spectrograms too.
  13483. But in such case results are going to be poor if the phase data is not
  13484. available, because in such cases phase data need to be recreated, usually
  13485. its just recreated from random noise.
  13486. For best results use gray only output (@code{channel} color mode in
  13487. @ref{showspectrum} filter) and @code{log} scale for magnitude video and
  13488. @code{lin} scale for phase video. To produce phase, for 2nd video, use
  13489. @code{data} option. Inputs videos should generally use @code{fullframe}
  13490. slide mode as that saves resources needed for decoding video.
  13491. The filter accepts the following options:
  13492. @table @option
  13493. @item sample_rate
  13494. Specify sample rate of output audio, the sample rate of audio from which
  13495. spectrum was generated may differ.
  13496. @item channels
  13497. Set number of channels represented in input video spectrums.
  13498. @item scale
  13499. Set scale which was used when generating magnitude input spectrum.
  13500. Can be @code{lin} or @code{log}. Default is @code{log}.
  13501. @item slide
  13502. Set slide which was used when generating inputs spectrums.
  13503. Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
  13504. Default is @code{fullframe}.
  13505. @item win_func
  13506. Set window function used for resynthesis.
  13507. @item overlap
  13508. Set window overlap. In range @code{[0, 1]}. Default is @code{1},
  13509. which means optimal overlap for selected window function will be picked.
  13510. @item orientation
  13511. Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
  13512. Default is @code{vertical}.
  13513. @end table
  13514. @subsection Examples
  13515. @itemize
  13516. @item
  13517. First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
  13518. then resynthesize videos back to audio with spectrumsynth:
  13519. @example
  13520. ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
  13521. ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
  13522. ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
  13523. @end example
  13524. @end itemize
  13525. @section split, asplit
  13526. Split input into several identical outputs.
  13527. @code{asplit} works with audio input, @code{split} with video.
  13528. The filter accepts a single parameter which specifies the number of outputs. If
  13529. unspecified, it defaults to 2.
  13530. @subsection Examples
  13531. @itemize
  13532. @item
  13533. Create two separate outputs from the same input:
  13534. @example
  13535. [in] split [out0][out1]
  13536. @end example
  13537. @item
  13538. To create 3 or more outputs, you need to specify the number of
  13539. outputs, like in:
  13540. @example
  13541. [in] asplit=3 [out0][out1][out2]
  13542. @end example
  13543. @item
  13544. Create two separate outputs from the same input, one cropped and
  13545. one padded:
  13546. @example
  13547. [in] split [splitout1][splitout2];
  13548. [splitout1] crop=100:100:0:0 [cropout];
  13549. [splitout2] pad=200:200:100:100 [padout];
  13550. @end example
  13551. @item
  13552. Create 5 copies of the input audio with @command{ffmpeg}:
  13553. @example
  13554. ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
  13555. @end example
  13556. @end itemize
  13557. @section zmq, azmq
  13558. Receive commands sent through a libzmq client, and forward them to
  13559. filters in the filtergraph.
  13560. @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
  13561. must be inserted between two video filters, @code{azmq} between two
  13562. audio filters.
  13563. To enable these filters you need to install the libzmq library and
  13564. headers and configure FFmpeg with @code{--enable-libzmq}.
  13565. For more information about libzmq see:
  13566. @url{http://www.zeromq.org/}
  13567. The @code{zmq} and @code{azmq} filters work as a libzmq server, which
  13568. receives messages sent through a network interface defined by the
  13569. @option{bind_address} option.
  13570. The received message must be in the form:
  13571. @example
  13572. @var{TARGET} @var{COMMAND} [@var{ARG}]
  13573. @end example
  13574. @var{TARGET} specifies the target of the command, usually the name of
  13575. the filter class or a specific filter instance name.
  13576. @var{COMMAND} specifies the name of the command for the target filter.
  13577. @var{ARG} is optional and specifies the optional argument list for the
  13578. given @var{COMMAND}.
  13579. Upon reception, the message is processed and the corresponding command
  13580. is injected into the filtergraph. Depending on the result, the filter
  13581. will send a reply to the client, adopting the format:
  13582. @example
  13583. @var{ERROR_CODE} @var{ERROR_REASON}
  13584. @var{MESSAGE}
  13585. @end example
  13586. @var{MESSAGE} is optional.
  13587. @subsection Examples
  13588. Look at @file{tools/zmqsend} for an example of a zmq client which can
  13589. be used to send commands processed by these filters.
  13590. Consider the following filtergraph generated by @command{ffplay}
  13591. @example
  13592. ffplay -dumpgraph 1 -f lavfi "
  13593. color=s=100x100:c=red [l];
  13594. color=s=100x100:c=blue [r];
  13595. nullsrc=s=200x100, zmq [bg];
  13596. [bg][l] overlay [bg+l];
  13597. [bg+l][r] overlay=x=100 "
  13598. @end example
  13599. To change the color of the left side of the video, the following
  13600. command can be used:
  13601. @example
  13602. echo Parsed_color_0 c yellow | tools/zmqsend
  13603. @end example
  13604. To change the right side:
  13605. @example
  13606. echo Parsed_color_1 c pink | tools/zmqsend
  13607. @end example
  13608. @c man end MULTIMEDIA FILTERS
  13609. @chapter Multimedia Sources
  13610. @c man begin MULTIMEDIA SOURCES
  13611. Below is a description of the currently available multimedia sources.
  13612. @section amovie
  13613. This is the same as @ref{movie} source, except it selects an audio
  13614. stream by default.
  13615. @anchor{movie}
  13616. @section movie
  13617. Read audio and/or video stream(s) from a movie container.
  13618. It accepts the following parameters:
  13619. @table @option
  13620. @item filename
  13621. The name of the resource to read (not necessarily a file; it can also be a
  13622. device or a stream accessed through some protocol).
  13623. @item format_name, f
  13624. Specifies the format assumed for the movie to read, and can be either
  13625. the name of a container or an input device. If not specified, the
  13626. format is guessed from @var{movie_name} or by probing.
  13627. @item seek_point, sp
  13628. Specifies the seek point in seconds. The frames will be output
  13629. starting from this seek point. The parameter is evaluated with
  13630. @code{av_strtod}, so the numerical value may be suffixed by an IS
  13631. postfix. The default value is "0".
  13632. @item streams, s
  13633. Specifies the streams to read. Several streams can be specified,
  13634. separated by "+". The source will then have as many outputs, in the
  13635. same order. The syntax is explained in the ``Stream specifiers''
  13636. section in the ffmpeg manual. Two special names, "dv" and "da" specify
  13637. respectively the default (best suited) video and audio stream. Default
  13638. is "dv", or "da" if the filter is called as "amovie".
  13639. @item stream_index, si
  13640. Specifies the index of the video stream to read. If the value is -1,
  13641. the most suitable video stream will be automatically selected. The default
  13642. value is "-1". Deprecated. If the filter is called "amovie", it will select
  13643. audio instead of video.
  13644. @item loop
  13645. Specifies how many times to read the stream in sequence.
  13646. If the value is less than 1, the stream will be read again and again.
  13647. Default value is "1".
  13648. Note that when the movie is looped the source timestamps are not
  13649. changed, so it will generate non monotonically increasing timestamps.
  13650. @item discontinuity
  13651. Specifies the time difference between frames above which the point is
  13652. considered a timestamp discontinuity which is removed by adjusting the later
  13653. timestamps.
  13654. @end table
  13655. It allows overlaying a second video on top of the main input of
  13656. a filtergraph, as shown in this graph:
  13657. @example
  13658. input -----------> deltapts0 --> overlay --> output
  13659. ^
  13660. |
  13661. movie --> scale--> deltapts1 -------+
  13662. @end example
  13663. @subsection Examples
  13664. @itemize
  13665. @item
  13666. Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
  13667. on top of the input labelled "in":
  13668. @example
  13669. movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
  13670. [in] setpts=PTS-STARTPTS [main];
  13671. [main][over] overlay=16:16 [out]
  13672. @end example
  13673. @item
  13674. Read from a video4linux2 device, and overlay it on top of the input
  13675. labelled "in":
  13676. @example
  13677. movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
  13678. [in] setpts=PTS-STARTPTS [main];
  13679. [main][over] overlay=16:16 [out]
  13680. @end example
  13681. @item
  13682. Read the first video stream and the audio stream with id 0x81 from
  13683. dvd.vob; the video is connected to the pad named "video" and the audio is
  13684. connected to the pad named "audio":
  13685. @example
  13686. movie=dvd.vob:s=v:0+#0x81 [video] [audio]
  13687. @end example
  13688. @end itemize
  13689. @subsection Commands
  13690. Both movie and amovie support the following commands:
  13691. @table @option
  13692. @item seek
  13693. Perform seek using "av_seek_frame".
  13694. The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
  13695. @itemize
  13696. @item
  13697. @var{stream_index}: If stream_index is -1, a default
  13698. stream is selected, and @var{timestamp} is automatically converted
  13699. from AV_TIME_BASE units to the stream specific time_base.
  13700. @item
  13701. @var{timestamp}: Timestamp in AVStream.time_base units
  13702. or, if no stream is specified, in AV_TIME_BASE units.
  13703. @item
  13704. @var{flags}: Flags which select direction and seeking mode.
  13705. @end itemize
  13706. @item get_duration
  13707. Get movie duration in AV_TIME_BASE units.
  13708. @end table
  13709. @c man end MULTIMEDIA SOURCES