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.

23003 lines
613KB

  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{id}=@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 optionally followed by "@@@var{id}".
  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{FILTER_NAME} ::= @var{NAME}["@@"@var{NAME}]
  173. @var{LINKLABEL} ::= "[" @var{NAME} "]"
  174. @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
  175. @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
  176. @var{FILTER} ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
  177. @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
  178. @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
  179. @end example
  180. @anchor{filtergraph escaping}
  181. @section Notes on filtergraph escaping
  182. Filtergraph description composition entails several levels of
  183. escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
  184. section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
  185. information about the employed escaping procedure.
  186. A first level escaping affects the content of each filter option
  187. value, which may contain the special character @code{:} used to
  188. separate values, or one of the escaping characters @code{\'}.
  189. A second level escaping affects the whole filter description, which
  190. may contain the escaping characters @code{\'} or the special
  191. characters @code{[],;} used by the filtergraph description.
  192. Finally, when you specify a filtergraph on a shell commandline, you
  193. need to perform a third level escaping for the shell special
  194. characters contained within it.
  195. For example, consider the following string to be embedded in
  196. the @ref{drawtext} filter description @option{text} value:
  197. @example
  198. this is a 'string': may contain one, or more, special characters
  199. @end example
  200. This string contains the @code{'} special escaping character, and the
  201. @code{:} special character, so it needs to be escaped in this way:
  202. @example
  203. text=this is a \'string\'\: may contain one, or more, special characters
  204. @end example
  205. A second level of escaping is required when embedding the filter
  206. description in a filtergraph description, in order to escape all the
  207. filtergraph special characters. Thus the example above becomes:
  208. @example
  209. drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
  210. @end example
  211. (note that in addition to the @code{\'} escaping special characters,
  212. also @code{,} needs to be escaped).
  213. Finally an additional level of escaping is needed when writing the
  214. filtergraph description in a shell command, which depends on the
  215. escaping rules of the adopted shell. For example, assuming that
  216. @code{\} is special and needs to be escaped with another @code{\}, the
  217. previous string will finally result in:
  218. @example
  219. -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
  220. @end example
  221. @chapter Timeline editing
  222. Some filters support a generic @option{enable} option. For the filters
  223. supporting timeline editing, this option can be set to an expression which is
  224. evaluated before sending a frame to the filter. If the evaluation is non-zero,
  225. the filter will be enabled, otherwise the frame will be sent unchanged to the
  226. next filter in the filtergraph.
  227. The expression accepts the following values:
  228. @table @samp
  229. @item t
  230. timestamp expressed in seconds, NAN if the input timestamp is unknown
  231. @item n
  232. sequential number of the input frame, starting from 0
  233. @item pos
  234. the position in the file of the input frame, NAN if unknown
  235. @item w
  236. @item h
  237. width and height of the input frame if video
  238. @end table
  239. Additionally, these filters support an @option{enable} command that can be used
  240. to re-define the expression.
  241. Like any other filtering option, the @option{enable} option follows the same
  242. rules.
  243. For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
  244. minutes, and a @ref{curves} filter starting at 3 seconds:
  245. @example
  246. smartblur = enable='between(t,10,3*60)',
  247. curves = enable='gte(t,3)' : preset=cross_process
  248. @end example
  249. See @code{ffmpeg -filters} to view which filters have timeline support.
  250. @c man end FILTERGRAPH DESCRIPTION
  251. @anchor{framesync}
  252. @chapter Options for filters with several inputs (framesync)
  253. @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
  254. Some filters with several inputs support a common set of options.
  255. These options can only be set by name, not with the short notation.
  256. @table @option
  257. @item eof_action
  258. The action to take when EOF is encountered on the secondary input; it accepts
  259. one of the following values:
  260. @table @option
  261. @item repeat
  262. Repeat the last frame (the default).
  263. @item endall
  264. End both streams.
  265. @item pass
  266. Pass the main input through.
  267. @end table
  268. @item shortest
  269. If set to 1, force the output to terminate when the shortest input
  270. terminates. Default value is 0.
  271. @item repeatlast
  272. If set to 1, force the filter to extend the last frame of secondary streams
  273. until the end of the primary stream. A value of 0 disables this behavior.
  274. Default value is 1.
  275. @end table
  276. @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
  277. @chapter Audio Filters
  278. @c man begin AUDIO FILTERS
  279. When you configure your FFmpeg build, you can disable any of the
  280. existing filters using @code{--disable-filters}.
  281. The configure output will show the audio filters included in your
  282. build.
  283. Below is a description of the currently available audio filters.
  284. @section acompressor
  285. A compressor is mainly used to reduce the dynamic range of a signal.
  286. Especially modern music is mostly compressed at a high ratio to
  287. improve the overall loudness. It's done to get the highest attention
  288. of a listener, "fatten" the sound and bring more "power" to the track.
  289. If a signal is compressed too much it may sound dull or "dead"
  290. afterwards or it may start to "pump" (which could be a powerful effect
  291. but can also destroy a track completely).
  292. The right compression is the key to reach a professional sound and is
  293. the high art of mixing and mastering. Because of its complex settings
  294. it may take a long time to get the right feeling for this kind of effect.
  295. Compression is done by detecting the volume above a chosen level
  296. @code{threshold} and dividing it by the factor set with @code{ratio}.
  297. So if you set the threshold to -12dB and your signal reaches -6dB a ratio
  298. of 2:1 will result in a signal at -9dB. Because an exact manipulation of
  299. the signal would cause distortion of the waveform the reduction can be
  300. levelled over the time. This is done by setting "Attack" and "Release".
  301. @code{attack} determines how long the signal has to rise above the threshold
  302. before any reduction will occur and @code{release} sets the time the signal
  303. has to fall below the threshold to reduce the reduction again. Shorter signals
  304. than the chosen attack time will be left untouched.
  305. The overall reduction of the signal can be made up afterwards with the
  306. @code{makeup} setting. So compressing the peaks of a signal about 6dB and
  307. raising the makeup to this level results in a signal twice as loud than the
  308. source. To gain a softer entry in the compression the @code{knee} flattens the
  309. hard edge at the threshold in the range of the chosen decibels.
  310. The filter accepts the following options:
  311. @table @option
  312. @item level_in
  313. Set input gain. Default is 1. Range is between 0.015625 and 64.
  314. @item mode
  315. Set mode of compressor operation. Can be @code{upward} or @code{downward}.
  316. Default is @code{downward}.
  317. @item threshold
  318. If a signal of stream rises above this level it will affect the gain
  319. reduction.
  320. By default it is 0.125. Range is between 0.00097563 and 1.
  321. @item ratio
  322. Set a ratio by which the signal is reduced. 1:2 means that if the level
  323. rose 4dB above the threshold, it will be only 2dB above after the reduction.
  324. Default is 2. Range is between 1 and 20.
  325. @item attack
  326. Amount of milliseconds the signal has to rise above the threshold before gain
  327. reduction starts. Default is 20. Range is between 0.01 and 2000.
  328. @item release
  329. Amount of milliseconds the signal has to fall below the threshold before
  330. reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
  331. @item makeup
  332. Set the amount by how much signal will be amplified after processing.
  333. Default is 1. Range is from 1 to 64.
  334. @item knee
  335. Curve the sharp knee around the threshold to enter gain reduction more softly.
  336. Default is 2.82843. Range is between 1 and 8.
  337. @item link
  338. Choose if the @code{average} level between all channels of input stream
  339. or the louder(@code{maximum}) channel of input stream affects the
  340. reduction. Default is @code{average}.
  341. @item detection
  342. Should the exact signal be taken in case of @code{peak} or an RMS one in case
  343. of @code{rms}. Default is @code{rms} which is mostly smoother.
  344. @item mix
  345. How much to use compressed signal in output. Default is 1.
  346. Range is between 0 and 1.
  347. @end table
  348. @section acontrast
  349. Simple audio dynamic range compression/expansion filter.
  350. The filter accepts the following options:
  351. @table @option
  352. @item contrast
  353. Set contrast. Default is 33. Allowed range is between 0 and 100.
  354. @end table
  355. @section acopy
  356. Copy the input audio source unchanged to the output. This is mainly useful for
  357. testing purposes.
  358. @section acrossfade
  359. Apply cross fade from one input audio stream to another input audio stream.
  360. The cross fade is applied for specified duration near the end of first stream.
  361. The filter accepts the following options:
  362. @table @option
  363. @item nb_samples, ns
  364. Specify the number of samples for which the cross fade effect has to last.
  365. At the end of the cross fade effect the first input audio will be completely
  366. silent. Default is 44100.
  367. @item duration, d
  368. Specify the duration of the cross fade effect. See
  369. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  370. for the accepted syntax.
  371. By default the duration is determined by @var{nb_samples}.
  372. If set this option is used instead of @var{nb_samples}.
  373. @item overlap, o
  374. Should first stream end overlap with second stream start. Default is enabled.
  375. @item curve1
  376. Set curve for cross fade transition for first stream.
  377. @item curve2
  378. Set curve for cross fade transition for second stream.
  379. For description of available curve types see @ref{afade} filter description.
  380. @end table
  381. @subsection Examples
  382. @itemize
  383. @item
  384. Cross fade from one input to another:
  385. @example
  386. ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
  387. @end example
  388. @item
  389. Cross fade from one input to another but without overlapping:
  390. @example
  391. ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
  392. @end example
  393. @end itemize
  394. @section acrossover
  395. Split audio stream into several bands.
  396. This filter splits audio stream into two or more frequency ranges.
  397. Summing all streams back will give flat output.
  398. The filter accepts the following options:
  399. @table @option
  400. @item split
  401. Set split frequencies. Those must be positive and increasing.
  402. @item order
  403. Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
  404. Default is @var{4th}.
  405. @end table
  406. @section acrusher
  407. Reduce audio bit resolution.
  408. This filter is bit crusher with enhanced functionality. A bit crusher
  409. is used to audibly reduce number of bits an audio signal is sampled
  410. with. This doesn't change the bit depth at all, it just produces the
  411. effect. Material reduced in bit depth sounds more harsh and "digital".
  412. This filter is able to even round to continuous values instead of discrete
  413. bit depths.
  414. Additionally it has a D/C offset which results in different crushing of
  415. the lower and the upper half of the signal.
  416. An Anti-Aliasing setting is able to produce "softer" crushing sounds.
  417. Another feature of this filter is the logarithmic mode.
  418. This setting switches from linear distances between bits to logarithmic ones.
  419. The result is a much more "natural" sounding crusher which doesn't gate low
  420. signals for example. The human ear has a logarithmic perception,
  421. so this kind of crushing is much more pleasant.
  422. Logarithmic crushing is also able to get anti-aliased.
  423. The filter accepts the following options:
  424. @table @option
  425. @item level_in
  426. Set level in.
  427. @item level_out
  428. Set level out.
  429. @item bits
  430. Set bit reduction.
  431. @item mix
  432. Set mixing amount.
  433. @item mode
  434. Can be linear: @code{lin} or logarithmic: @code{log}.
  435. @item dc
  436. Set DC.
  437. @item aa
  438. Set anti-aliasing.
  439. @item samples
  440. Set sample reduction.
  441. @item lfo
  442. Enable LFO. By default disabled.
  443. @item lforange
  444. Set LFO range.
  445. @item lforate
  446. Set LFO rate.
  447. @end table
  448. @section acue
  449. Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
  450. filter.
  451. @section adeclick
  452. Remove impulsive noise from input audio.
  453. Samples detected as impulsive noise are replaced by interpolated samples using
  454. autoregressive modelling.
  455. @table @option
  456. @item w
  457. Set window size, in milliseconds. Allowed range is from @code{10} to
  458. @code{100}. Default value is @code{55} milliseconds.
  459. This sets size of window which will be processed at once.
  460. @item o
  461. Set window overlap, in percentage of window size. Allowed range is from
  462. @code{50} to @code{95}. Default value is @code{75} percent.
  463. Setting this to a very high value increases impulsive noise removal but makes
  464. whole process much slower.
  465. @item a
  466. Set autoregression order, in percentage of window size. Allowed range is from
  467. @code{0} to @code{25}. Default value is @code{2} percent. This option also
  468. controls quality of interpolated samples using neighbour good samples.
  469. @item t
  470. Set threshold value. Allowed range is from @code{1} to @code{100}.
  471. Default value is @code{2}.
  472. This controls the strength of impulsive noise which is going to be removed.
  473. The lower value, the more samples will be detected as impulsive noise.
  474. @item b
  475. Set burst fusion, in percentage of window size. Allowed range is @code{0} to
  476. @code{10}. Default value is @code{2}.
  477. If any two samples detected as noise are spaced less than this value then any
  478. sample between those two samples will be also detected as noise.
  479. @item m
  480. Set overlap method.
  481. It accepts the following values:
  482. @table @option
  483. @item a
  484. Select overlap-add method. Even not interpolated samples are slightly
  485. changed with this method.
  486. @item s
  487. Select overlap-save method. Not interpolated samples remain unchanged.
  488. @end table
  489. Default value is @code{a}.
  490. @end table
  491. @section adeclip
  492. Remove clipped samples from input audio.
  493. Samples detected as clipped are replaced by interpolated samples using
  494. autoregressive modelling.
  495. @table @option
  496. @item w
  497. Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
  498. Default value is @code{55} milliseconds.
  499. This sets size of window which will be processed at once.
  500. @item o
  501. Set window overlap, in percentage of window size. Allowed range is from @code{50}
  502. to @code{95}. Default value is @code{75} percent.
  503. @item a
  504. Set autoregression order, in percentage of window size. Allowed range is from
  505. @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
  506. quality of interpolated samples using neighbour good samples.
  507. @item t
  508. Set threshold value. Allowed range is from @code{1} to @code{100}.
  509. Default value is @code{10}. Higher values make clip detection less aggressive.
  510. @item n
  511. Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
  512. Default value is @code{1000}. Higher values make clip detection less aggressive.
  513. @item m
  514. Set overlap method.
  515. It accepts the following values:
  516. @table @option
  517. @item a
  518. Select overlap-add method. Even not interpolated samples are slightly changed
  519. with this method.
  520. @item s
  521. Select overlap-save method. Not interpolated samples remain unchanged.
  522. @end table
  523. Default value is @code{a}.
  524. @end table
  525. @section adelay
  526. Delay one or more audio channels.
  527. Samples in delayed channel are filled with silence.
  528. The filter accepts the following option:
  529. @table @option
  530. @item delays
  531. Set list of delays in milliseconds for each channel separated by '|'.
  532. Unused delays will be silently ignored. If number of given delays is
  533. smaller than number of channels all remaining channels will not be delayed.
  534. If you want to delay exact number of samples, append 'S' to number.
  535. If you want instead to delay in seconds, append 's' to number.
  536. @end table
  537. @subsection Examples
  538. @itemize
  539. @item
  540. Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
  541. the second channel (and any other channels that may be present) unchanged.
  542. @example
  543. adelay=1500|0|500
  544. @end example
  545. @item
  546. Delay second channel by 500 samples, the third channel by 700 samples and leave
  547. the first channel (and any other channels that may be present) unchanged.
  548. @example
  549. adelay=0|500S|700S
  550. @end example
  551. @end itemize
  552. @section aderivative, aintegral
  553. Compute derivative/integral of audio stream.
  554. Applying both filters one after another produces original audio.
  555. @section aecho
  556. Apply echoing to the input audio.
  557. Echoes are reflected sound and can occur naturally amongst mountains
  558. (and sometimes large buildings) when talking or shouting; digital echo
  559. effects emulate this behaviour and are often used to help fill out the
  560. sound of a single instrument or vocal. The time difference between the
  561. original signal and the reflection is the @code{delay}, and the
  562. loudness of the reflected signal is the @code{decay}.
  563. Multiple echoes can have different delays and decays.
  564. A description of the accepted parameters follows.
  565. @table @option
  566. @item in_gain
  567. Set input gain of reflected signal. Default is @code{0.6}.
  568. @item out_gain
  569. Set output gain of reflected signal. Default is @code{0.3}.
  570. @item delays
  571. Set list of time intervals in milliseconds between original signal and reflections
  572. separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
  573. Default is @code{1000}.
  574. @item decays
  575. Set list of loudness of reflected signals separated by '|'.
  576. Allowed range for each @code{decay} is @code{(0 - 1.0]}.
  577. Default is @code{0.5}.
  578. @end table
  579. @subsection Examples
  580. @itemize
  581. @item
  582. Make it sound as if there are twice as many instruments as are actually playing:
  583. @example
  584. aecho=0.8:0.88:60:0.4
  585. @end example
  586. @item
  587. If delay is very short, then it sound like a (metallic) robot playing music:
  588. @example
  589. aecho=0.8:0.88:6:0.4
  590. @end example
  591. @item
  592. A longer delay will sound like an open air concert in the mountains:
  593. @example
  594. aecho=0.8:0.9:1000:0.3
  595. @end example
  596. @item
  597. Same as above but with one more mountain:
  598. @example
  599. aecho=0.8:0.9:1000|1800:0.3|0.25
  600. @end example
  601. @end itemize
  602. @section aemphasis
  603. Audio emphasis filter creates or restores material directly taken from LPs or
  604. emphased CDs with different filter curves. E.g. to store music on vinyl the
  605. signal has to be altered by a filter first to even out the disadvantages of
  606. this recording medium.
  607. Once the material is played back the inverse filter has to be applied to
  608. restore the distortion of the frequency response.
  609. The filter accepts the following options:
  610. @table @option
  611. @item level_in
  612. Set input gain.
  613. @item level_out
  614. Set output gain.
  615. @item mode
  616. Set filter mode. For restoring material use @code{reproduction} mode, otherwise
  617. use @code{production} mode. Default is @code{reproduction} mode.
  618. @item type
  619. Set filter type. Selects medium. Can be one of the following:
  620. @table @option
  621. @item col
  622. select Columbia.
  623. @item emi
  624. select EMI.
  625. @item bsi
  626. select BSI (78RPM).
  627. @item riaa
  628. select RIAA.
  629. @item cd
  630. select Compact Disc (CD).
  631. @item 50fm
  632. select 50µs (FM).
  633. @item 75fm
  634. select 75µs (FM).
  635. @item 50kf
  636. select 50µs (FM-KF).
  637. @item 75kf
  638. select 75µs (FM-KF).
  639. @end table
  640. @end table
  641. @section aeval
  642. Modify an audio signal according to the specified expressions.
  643. This filter accepts one or more expressions (one for each channel),
  644. which are evaluated and used to modify a corresponding audio signal.
  645. It accepts the following parameters:
  646. @table @option
  647. @item exprs
  648. Set the '|'-separated expressions list for each separate channel. If
  649. the number of input channels is greater than the number of
  650. expressions, the last specified expression is used for the remaining
  651. output channels.
  652. @item channel_layout, c
  653. Set output channel layout. If not specified, the channel layout is
  654. specified by the number of expressions. If set to @samp{same}, it will
  655. use by default the same input channel layout.
  656. @end table
  657. Each expression in @var{exprs} can contain the following constants and functions:
  658. @table @option
  659. @item ch
  660. channel number of the current expression
  661. @item n
  662. number of the evaluated sample, starting from 0
  663. @item s
  664. sample rate
  665. @item t
  666. time of the evaluated sample expressed in seconds
  667. @item nb_in_channels
  668. @item nb_out_channels
  669. input and output number of channels
  670. @item val(CH)
  671. the value of input channel with number @var{CH}
  672. @end table
  673. Note: this filter is slow. For faster processing you should use a
  674. dedicated filter.
  675. @subsection Examples
  676. @itemize
  677. @item
  678. Half volume:
  679. @example
  680. aeval=val(ch)/2:c=same
  681. @end example
  682. @item
  683. Invert phase of the second channel:
  684. @example
  685. aeval=val(0)|-val(1)
  686. @end example
  687. @end itemize
  688. @anchor{afade}
  689. @section afade
  690. Apply fade-in/out effect to input audio.
  691. A description of the accepted parameters follows.
  692. @table @option
  693. @item type, t
  694. Specify the effect type, can be either @code{in} for fade-in, or
  695. @code{out} for a fade-out effect. Default is @code{in}.
  696. @item start_sample, ss
  697. Specify the number of the start sample for starting to apply the fade
  698. effect. Default is 0.
  699. @item nb_samples, ns
  700. Specify the number of samples for which the fade effect has to last. At
  701. the end of the fade-in effect the output audio will have the same
  702. volume as the input audio, at the end of the fade-out transition
  703. the output audio will be silence. Default is 44100.
  704. @item start_time, st
  705. Specify the start time of the fade effect. Default is 0.
  706. The value must be specified as a time duration; see
  707. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  708. for the accepted syntax.
  709. If set this option is used instead of @var{start_sample}.
  710. @item duration, d
  711. Specify the duration of the fade effect. See
  712. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  713. for the accepted syntax.
  714. At the end of the fade-in effect the output audio will have the same
  715. volume as the input audio, at the end of the fade-out transition
  716. the output audio will be silence.
  717. By default the duration is determined by @var{nb_samples}.
  718. If set this option is used instead of @var{nb_samples}.
  719. @item curve
  720. Set curve for fade transition.
  721. It accepts the following values:
  722. @table @option
  723. @item tri
  724. select triangular, linear slope (default)
  725. @item qsin
  726. select quarter of sine wave
  727. @item hsin
  728. select half of sine wave
  729. @item esin
  730. select exponential sine wave
  731. @item log
  732. select logarithmic
  733. @item ipar
  734. select inverted parabola
  735. @item qua
  736. select quadratic
  737. @item cub
  738. select cubic
  739. @item squ
  740. select square root
  741. @item cbr
  742. select cubic root
  743. @item par
  744. select parabola
  745. @item exp
  746. select exponential
  747. @item iqsin
  748. select inverted quarter of sine wave
  749. @item ihsin
  750. select inverted half of sine wave
  751. @item dese
  752. select double-exponential seat
  753. @item desi
  754. select double-exponential sigmoid
  755. @item losi
  756. select logistic sigmoid
  757. @item nofade
  758. no fade applied
  759. @end table
  760. @end table
  761. @subsection Examples
  762. @itemize
  763. @item
  764. Fade in first 15 seconds of audio:
  765. @example
  766. afade=t=in:ss=0:d=15
  767. @end example
  768. @item
  769. Fade out last 25 seconds of a 900 seconds audio:
  770. @example
  771. afade=t=out:st=875:d=25
  772. @end example
  773. @end itemize
  774. @section afftdn
  775. Denoise audio samples with FFT.
  776. A description of the accepted parameters follows.
  777. @table @option
  778. @item nr
  779. Set the noise reduction in dB, allowed range is 0.01 to 97.
  780. Default value is 12 dB.
  781. @item nf
  782. Set the noise floor in dB, allowed range is -80 to -20.
  783. Default value is -50 dB.
  784. @item nt
  785. Set the noise type.
  786. It accepts the following values:
  787. @table @option
  788. @item w
  789. Select white noise.
  790. @item v
  791. Select vinyl noise.
  792. @item s
  793. Select shellac noise.
  794. @item c
  795. Select custom noise, defined in @code{bn} option.
  796. Default value is white noise.
  797. @end table
  798. @item bn
  799. Set custom band noise for every one of 15 bands.
  800. Bands are separated by ' ' or '|'.
  801. @item rf
  802. Set the residual floor in dB, allowed range is -80 to -20.
  803. Default value is -38 dB.
  804. @item tn
  805. Enable noise tracking. By default is disabled.
  806. With this enabled, noise floor is automatically adjusted.
  807. @item tr
  808. Enable residual tracking. By default is disabled.
  809. @item om
  810. Set the output mode.
  811. It accepts the following values:
  812. @table @option
  813. @item i
  814. Pass input unchanged.
  815. @item o
  816. Pass noise filtered out.
  817. @item n
  818. Pass only noise.
  819. Default value is @var{o}.
  820. @end table
  821. @end table
  822. @subsection Commands
  823. This filter supports the following commands:
  824. @table @option
  825. @item sample_noise, sn
  826. Start or stop measuring noise profile.
  827. Syntax for the command is : "start" or "stop" string.
  828. After measuring noise profile is stopped it will be
  829. automatically applied in filtering.
  830. @item noise_reduction, nr
  831. Change noise reduction. Argument is single float number.
  832. Syntax for the command is : "@var{noise_reduction}"
  833. @item noise_floor, nf
  834. Change noise floor. Argument is single float number.
  835. Syntax for the command is : "@var{noise_floor}"
  836. @item output_mode, om
  837. Change output mode operation.
  838. Syntax for the command is : "i", "o" or "n" string.
  839. @end table
  840. @section afftfilt
  841. Apply arbitrary expressions to samples in frequency domain.
  842. @table @option
  843. @item real
  844. Set frequency domain real expression for each separate channel separated
  845. by '|'. Default is "re".
  846. If the number of input channels is greater than the number of
  847. expressions, the last specified expression is used for the remaining
  848. output channels.
  849. @item imag
  850. Set frequency domain imaginary expression for each separate channel
  851. separated by '|'. Default is "im".
  852. Each expression in @var{real} and @var{imag} can contain the following
  853. constants and functions:
  854. @table @option
  855. @item sr
  856. sample rate
  857. @item b
  858. current frequency bin number
  859. @item nb
  860. number of available bins
  861. @item ch
  862. channel number of the current expression
  863. @item chs
  864. number of channels
  865. @item pts
  866. current frame pts
  867. @item re
  868. current real part of frequency bin of current channel
  869. @item im
  870. current imaginary part of frequency bin of current channel
  871. @item real(b, ch)
  872. Return the value of real part of frequency bin at location (@var{bin},@var{channel})
  873. @item imag(b, ch)
  874. Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
  875. @end table
  876. @item win_size
  877. Set window size.
  878. It accepts the following values:
  879. @table @samp
  880. @item w16
  881. @item w32
  882. @item w64
  883. @item w128
  884. @item w256
  885. @item w512
  886. @item w1024
  887. @item w2048
  888. @item w4096
  889. @item w8192
  890. @item w16384
  891. @item w32768
  892. @item w65536
  893. @end table
  894. Default is @code{w4096}
  895. @item win_func
  896. Set window function. Default is @code{hann}.
  897. @item overlap
  898. Set window overlap. If set to 1, the recommended overlap for selected
  899. window function will be picked. Default is @code{0.75}.
  900. @end table
  901. @subsection Examples
  902. @itemize
  903. @item
  904. Leave almost only low frequencies in audio:
  905. @example
  906. afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
  907. @end example
  908. @end itemize
  909. @anchor{afir}
  910. @section afir
  911. Apply an arbitrary Frequency Impulse Response filter.
  912. This filter is designed for applying long FIR filters,
  913. up to 60 seconds long.
  914. It can be used as component for digital crossover filters,
  915. room equalization, cross talk cancellation, wavefield synthesis,
  916. auralization, ambiophonics, ambisonics and spatialization.
  917. This filter uses second stream as FIR coefficients.
  918. If second stream holds single channel, it will be used
  919. for all input channels in first stream, otherwise
  920. number of channels in second stream must be same as
  921. number of channels in first stream.
  922. It accepts the following parameters:
  923. @table @option
  924. @item dry
  925. Set dry gain. This sets input gain.
  926. @item wet
  927. Set wet gain. This sets final output gain.
  928. @item length
  929. Set Impulse Response filter length. Default is 1, which means whole IR is processed.
  930. @item gtype
  931. Enable applying gain measured from power of IR.
  932. Set which approach to use for auto gain measurement.
  933. @table @option
  934. @item none
  935. Do not apply any gain.
  936. @item peak
  937. select peak gain, very conservative approach. This is default value.
  938. @item dc
  939. select DC gain, limited application.
  940. @item gn
  941. select gain to noise approach, this is most popular one.
  942. @end table
  943. @item irgain
  944. Set gain to be applied to IR coefficients before filtering.
  945. Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
  946. @item irfmt
  947. Set format of IR stream. Can be @code{mono} or @code{input}.
  948. Default is @code{input}.
  949. @item maxir
  950. Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
  951. Allowed range is 0.1 to 60 seconds.
  952. @item response
  953. Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
  954. By default it is disabled.
  955. @item channel
  956. Set for which IR channel to display frequency response. By default is first channel
  957. displayed. This option is used only when @var{response} is enabled.
  958. @item size
  959. Set video stream size. This option is used only when @var{response} is enabled.
  960. @item rate
  961. Set video stream frame rate. This option is used only when @var{response} is enabled.
  962. @item minp
  963. Set minimal partition size used for convolution. Default is @var{8192}.
  964. Allowed range is from @var{8} to @var{32768}.
  965. Lower values decreases latency at cost of higher CPU usage.
  966. @item maxp
  967. Set maximal partition size used for convolution. Default is @var{8192}.
  968. Allowed range is from @var{8} to @var{32768}.
  969. Lower values may increase CPU usage.
  970. @end table
  971. @subsection Examples
  972. @itemize
  973. @item
  974. Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
  975. @example
  976. ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
  977. @end example
  978. @end itemize
  979. @anchor{aformat}
  980. @section aformat
  981. Set output format constraints for the input audio. The framework will
  982. negotiate the most appropriate format to minimize conversions.
  983. It accepts the following parameters:
  984. @table @option
  985. @item sample_fmts
  986. A '|'-separated list of requested sample formats.
  987. @item sample_rates
  988. A '|'-separated list of requested sample rates.
  989. @item channel_layouts
  990. A '|'-separated list of requested channel layouts.
  991. See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  992. for the required syntax.
  993. @end table
  994. If a parameter is omitted, all values are allowed.
  995. Force the output to either unsigned 8-bit or signed 16-bit stereo
  996. @example
  997. aformat=sample_fmts=u8|s16:channel_layouts=stereo
  998. @end example
  999. @section agate
  1000. A gate is mainly used to reduce lower parts of a signal. This kind of signal
  1001. processing reduces disturbing noise between useful signals.
  1002. Gating is done by detecting the volume below a chosen level @var{threshold}
  1003. and dividing it by the factor set with @var{ratio}. The bottom of the noise
  1004. floor is set via @var{range}. Because an exact manipulation of the signal
  1005. would cause distortion of the waveform the reduction can be levelled over
  1006. time. This is done by setting @var{attack} and @var{release}.
  1007. @var{attack} determines how long the signal has to fall below the threshold
  1008. before any reduction will occur and @var{release} sets the time the signal
  1009. has to rise above the threshold to reduce the reduction again.
  1010. Shorter signals than the chosen attack time will be left untouched.
  1011. @table @option
  1012. @item level_in
  1013. Set input level before filtering.
  1014. Default is 1. Allowed range is from 0.015625 to 64.
  1015. @item mode
  1016. Set the mode of operation. Can be @code{upward} or @code{downward}.
  1017. Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
  1018. will be amplified, expanding dynamic range in upward direction.
  1019. Otherwise, in case of @code{downward} lower parts of signal will be reduced.
  1020. @item range
  1021. Set the level of gain reduction when the signal is below the threshold.
  1022. Default is 0.06125. Allowed range is from 0 to 1.
  1023. Setting this to 0 disables reduction and then filter behaves like expander.
  1024. @item threshold
  1025. If a signal rises above this level the gain reduction is released.
  1026. Default is 0.125. Allowed range is from 0 to 1.
  1027. @item ratio
  1028. Set a ratio by which the signal is reduced.
  1029. Default is 2. Allowed range is from 1 to 9000.
  1030. @item attack
  1031. Amount of milliseconds the signal has to rise above the threshold before gain
  1032. reduction stops.
  1033. Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
  1034. @item release
  1035. Amount of milliseconds the signal has to fall below the threshold before the
  1036. reduction is increased again. Default is 250 milliseconds.
  1037. Allowed range is from 0.01 to 9000.
  1038. @item makeup
  1039. Set amount of amplification of signal after processing.
  1040. Default is 1. Allowed range is from 1 to 64.
  1041. @item knee
  1042. Curve the sharp knee around the threshold to enter gain reduction more softly.
  1043. Default is 2.828427125. Allowed range is from 1 to 8.
  1044. @item detection
  1045. Choose if exact signal should be taken for detection or an RMS like one.
  1046. Default is @code{rms}. Can be @code{peak} or @code{rms}.
  1047. @item link
  1048. Choose if the average level between all channels or the louder channel affects
  1049. the reduction.
  1050. Default is @code{average}. Can be @code{average} or @code{maximum}.
  1051. @end table
  1052. @section aiir
  1053. Apply an arbitrary Infinite Impulse Response filter.
  1054. It accepts the following parameters:
  1055. @table @option
  1056. @item z
  1057. Set numerator/zeros coefficients.
  1058. @item p
  1059. Set denominator/poles coefficients.
  1060. @item k
  1061. Set channels gains.
  1062. @item dry_gain
  1063. Set input gain.
  1064. @item wet_gain
  1065. Set output gain.
  1066. @item f
  1067. Set coefficients format.
  1068. @table @samp
  1069. @item tf
  1070. transfer function
  1071. @item zp
  1072. Z-plane zeros/poles, cartesian (default)
  1073. @item pr
  1074. Z-plane zeros/poles, polar radians
  1075. @item pd
  1076. Z-plane zeros/poles, polar degrees
  1077. @end table
  1078. @item r
  1079. Set kind of processing.
  1080. Can be @code{d} - direct or @code{s} - serial cascading. Default is @code{s}.
  1081. @item e
  1082. Set filtering precision.
  1083. @table @samp
  1084. @item dbl
  1085. double-precision floating-point (default)
  1086. @item flt
  1087. single-precision floating-point
  1088. @item i32
  1089. 32-bit integers
  1090. @item i16
  1091. 16-bit integers
  1092. @end table
  1093. @item response
  1094. Show IR frequency response, magnitude and phase in additional video stream.
  1095. By default it is disabled.
  1096. @item channel
  1097. Set for which IR channel to display frequency response. By default is first channel
  1098. displayed. This option is used only when @var{response} is enabled.
  1099. @item size
  1100. Set video stream size. This option is used only when @var{response} is enabled.
  1101. @end table
  1102. Coefficients in @code{tf} format are separated by spaces and are in ascending
  1103. order.
  1104. Coefficients in @code{zp} format are separated by spaces and order of coefficients
  1105. doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
  1106. imaginary unit.
  1107. Different coefficients and gains can be provided for every channel, in such case
  1108. use '|' to separate coefficients or gains. Last provided coefficients will be
  1109. used for all remaining channels.
  1110. @subsection Examples
  1111. @itemize
  1112. @item
  1113. Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
  1114. @example
  1115. aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
  1116. @end example
  1117. @item
  1118. Same as above but in @code{zp} format:
  1119. @example
  1120. aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
  1121. @end example
  1122. @end itemize
  1123. @section alimiter
  1124. The limiter prevents an input signal from rising over a desired threshold.
  1125. This limiter uses lookahead technology to prevent your signal from distorting.
  1126. It means that there is a small delay after the signal is processed. Keep in mind
  1127. that the delay it produces is the attack time you set.
  1128. The filter accepts the following options:
  1129. @table @option
  1130. @item level_in
  1131. Set input gain. Default is 1.
  1132. @item level_out
  1133. Set output gain. Default is 1.
  1134. @item limit
  1135. Don't let signals above this level pass the limiter. Default is 1.
  1136. @item attack
  1137. The limiter will reach its attenuation level in this amount of time in
  1138. milliseconds. Default is 5 milliseconds.
  1139. @item release
  1140. Come back from limiting to attenuation 1.0 in this amount of milliseconds.
  1141. Default is 50 milliseconds.
  1142. @item asc
  1143. When gain reduction is always needed ASC takes care of releasing to an
  1144. average reduction level rather than reaching a reduction of 0 in the release
  1145. time.
  1146. @item asc_level
  1147. Select how much the release time is affected by ASC, 0 means nearly no changes
  1148. in release time while 1 produces higher release times.
  1149. @item level
  1150. Auto level output signal. Default is enabled.
  1151. This normalizes audio back to 0dB if enabled.
  1152. @end table
  1153. Depending on picked setting it is recommended to upsample input 2x or 4x times
  1154. with @ref{aresample} before applying this filter.
  1155. @section allpass
  1156. Apply a two-pole all-pass filter with central frequency (in Hz)
  1157. @var{frequency}, and filter-width @var{width}.
  1158. An all-pass filter changes the audio's frequency to phase relationship
  1159. without changing its frequency to amplitude relationship.
  1160. The filter accepts the following options:
  1161. @table @option
  1162. @item frequency, f
  1163. Set frequency in Hz.
  1164. @item width_type, t
  1165. Set method to specify band-width of filter.
  1166. @table @option
  1167. @item h
  1168. Hz
  1169. @item q
  1170. Q-Factor
  1171. @item o
  1172. octave
  1173. @item s
  1174. slope
  1175. @item k
  1176. kHz
  1177. @end table
  1178. @item width, w
  1179. Specify the band-width of a filter in width_type units.
  1180. @item channels, c
  1181. Specify which channels to filter, by default all available are filtered.
  1182. @end table
  1183. @subsection Commands
  1184. This filter supports the following commands:
  1185. @table @option
  1186. @item frequency, f
  1187. Change allpass frequency.
  1188. Syntax for the command is : "@var{frequency}"
  1189. @item width_type, t
  1190. Change allpass width_type.
  1191. Syntax for the command is : "@var{width_type}"
  1192. @item width, w
  1193. Change allpass width.
  1194. Syntax for the command is : "@var{width}"
  1195. @end table
  1196. @section aloop
  1197. Loop audio samples.
  1198. The filter accepts the following options:
  1199. @table @option
  1200. @item loop
  1201. Set the number of loops. Setting this value to -1 will result in infinite loops.
  1202. Default is 0.
  1203. @item size
  1204. Set maximal number of samples. Default is 0.
  1205. @item start
  1206. Set first sample of loop. Default is 0.
  1207. @end table
  1208. @anchor{amerge}
  1209. @section amerge
  1210. Merge two or more audio streams into a single multi-channel stream.
  1211. The filter accepts the following options:
  1212. @table @option
  1213. @item inputs
  1214. Set the number of inputs. Default is 2.
  1215. @end table
  1216. If the channel layouts of the inputs are disjoint, and therefore compatible,
  1217. the channel layout of the output will be set accordingly and the channels
  1218. will be reordered as necessary. If the channel layouts of the inputs are not
  1219. disjoint, the output will have all the channels of the first input then all
  1220. the channels of the second input, in that order, and the channel layout of
  1221. the output will be the default value corresponding to the total number of
  1222. channels.
  1223. For example, if the first input is in 2.1 (FL+FR+LF) and the second input
  1224. is FC+BL+BR, then the output will be in 5.1, with the channels in the
  1225. following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
  1226. first input, b1 is the first channel of the second input).
  1227. On the other hand, if both input are in stereo, the output channels will be
  1228. in the default order: a1, a2, b1, b2, and the channel layout will be
  1229. arbitrarily set to 4.0, which may or may not be the expected value.
  1230. All inputs must have the same sample rate, and format.
  1231. If inputs do not have the same duration, the output will stop with the
  1232. shortest.
  1233. @subsection Examples
  1234. @itemize
  1235. @item
  1236. Merge two mono files into a stereo stream:
  1237. @example
  1238. amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
  1239. @end example
  1240. @item
  1241. Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
  1242. @example
  1243. 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
  1244. @end example
  1245. @end itemize
  1246. @section amix
  1247. Mixes multiple audio inputs into a single output.
  1248. Note that this filter only supports float samples (the @var{amerge}
  1249. and @var{pan} audio filters support many formats). If the @var{amix}
  1250. input has integer samples then @ref{aresample} will be automatically
  1251. inserted to perform the conversion to float samples.
  1252. For example
  1253. @example
  1254. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
  1255. @end example
  1256. will mix 3 input audio streams to a single output with the same duration as the
  1257. first input and a dropout transition time of 3 seconds.
  1258. It accepts the following parameters:
  1259. @table @option
  1260. @item inputs
  1261. The number of inputs. If unspecified, it defaults to 2.
  1262. @item duration
  1263. How to determine the end-of-stream.
  1264. @table @option
  1265. @item longest
  1266. The duration of the longest input. (default)
  1267. @item shortest
  1268. The duration of the shortest input.
  1269. @item first
  1270. The duration of the first input.
  1271. @end table
  1272. @item dropout_transition
  1273. The transition time, in seconds, for volume renormalization when an input
  1274. stream ends. The default value is 2 seconds.
  1275. @item weights
  1276. Specify weight of each input audio stream as sequence.
  1277. Each weight is separated by space. By default all inputs have same weight.
  1278. @end table
  1279. @section amultiply
  1280. Multiply first audio stream with second audio stream and store result
  1281. in output audio stream. Multiplication is done by multiplying each
  1282. sample from first stream with sample at same position from second stream.
  1283. With this element-wise multiplication one can create amplitude fades and
  1284. amplitude modulations.
  1285. @section anequalizer
  1286. High-order parametric multiband equalizer for each channel.
  1287. It accepts the following parameters:
  1288. @table @option
  1289. @item params
  1290. This option string is in format:
  1291. "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
  1292. Each equalizer band is separated by '|'.
  1293. @table @option
  1294. @item chn
  1295. Set channel number to which equalization will be applied.
  1296. If input doesn't have that channel the entry is ignored.
  1297. @item f
  1298. Set central frequency for band.
  1299. If input doesn't have that frequency the entry is ignored.
  1300. @item w
  1301. Set band width in hertz.
  1302. @item g
  1303. Set band gain in dB.
  1304. @item t
  1305. Set filter type for band, optional, can be:
  1306. @table @samp
  1307. @item 0
  1308. Butterworth, this is default.
  1309. @item 1
  1310. Chebyshev type 1.
  1311. @item 2
  1312. Chebyshev type 2.
  1313. @end table
  1314. @end table
  1315. @item curves
  1316. With this option activated frequency response of anequalizer is displayed
  1317. in video stream.
  1318. @item size
  1319. Set video stream size. Only useful if curves option is activated.
  1320. @item mgain
  1321. Set max gain that will be displayed. Only useful if curves option is activated.
  1322. Setting this to a reasonable value makes it possible to display gain which is derived from
  1323. neighbour bands which are too close to each other and thus produce higher gain
  1324. when both are activated.
  1325. @item fscale
  1326. Set frequency scale used to draw frequency response in video output.
  1327. Can be linear or logarithmic. Default is logarithmic.
  1328. @item colors
  1329. Set color for each channel curve which is going to be displayed in video stream.
  1330. This is list of color names separated by space or by '|'.
  1331. Unrecognised or missing colors will be replaced by white color.
  1332. @end table
  1333. @subsection Examples
  1334. @itemize
  1335. @item
  1336. Lower gain by 10 of central frequency 200Hz and width 100 Hz
  1337. for first 2 channels using Chebyshev type 1 filter:
  1338. @example
  1339. anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
  1340. @end example
  1341. @end itemize
  1342. @subsection Commands
  1343. This filter supports the following commands:
  1344. @table @option
  1345. @item change
  1346. Alter existing filter parameters.
  1347. Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
  1348. @var{fN} is existing filter number, starting from 0, if no such filter is available
  1349. error is returned.
  1350. @var{freq} set new frequency parameter.
  1351. @var{width} set new width parameter in herz.
  1352. @var{gain} set new gain parameter in dB.
  1353. Full filter invocation with asendcmd may look like this:
  1354. asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
  1355. @end table
  1356. @section anlmdn
  1357. Reduce broadband noise in audio samples using Non-Local Means algorithm.
  1358. Each sample is adjusted by looking for other samples with similar contexts. This
  1359. context similarity is defined by comparing their surrounding patches of size
  1360. @option{p}. Patches are searched in an area of @option{r} around the sample.
  1361. The filter accepts the following options.
  1362. @table @option
  1363. @item s
  1364. Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
  1365. @item p
  1366. Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
  1367. Default value is 2 milliseconds.
  1368. @item r
  1369. Set research radius duration. Allowed range is from 2 to 300 milliseconds.
  1370. Default value is 6 milliseconds.
  1371. @item o
  1372. Set the output mode.
  1373. It accepts the following values:
  1374. @table @option
  1375. @item i
  1376. Pass input unchanged.
  1377. @item o
  1378. Pass noise filtered out.
  1379. @item n
  1380. Pass only noise.
  1381. Default value is @var{o}.
  1382. @end table
  1383. @end table
  1384. @section anull
  1385. Pass the audio source unchanged to the output.
  1386. @section apad
  1387. Pad the end of an audio stream with silence.
  1388. This can be used together with @command{ffmpeg} @option{-shortest} to
  1389. extend audio streams to the same length as the video stream.
  1390. A description of the accepted options follows.
  1391. @table @option
  1392. @item packet_size
  1393. Set silence packet size. Default value is 4096.
  1394. @item pad_len
  1395. Set the number of samples of silence to add to the end. After the
  1396. value is reached, the stream is terminated. This option is mutually
  1397. exclusive with @option{whole_len}.
  1398. @item whole_len
  1399. Set the minimum total number of samples in the output audio stream. If
  1400. the value is longer than the input audio length, silence is added to
  1401. the end, until the value is reached. This option is mutually exclusive
  1402. with @option{pad_len}.
  1403. @item pad_dur
  1404. Specify the duration of samples of silence to add. See
  1405. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  1406. for the accepted syntax. Used only if set to non-zero value.
  1407. @item whole_dur
  1408. Specify the minimum total duration in the output audio stream. See
  1409. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  1410. for the accepted syntax. Used only if set to non-zero value. If the value is longer than
  1411. the input audio length, silence is added to the end, until the value is reached.
  1412. This option is mutually exclusive with @option{pad_dur}
  1413. @end table
  1414. If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
  1415. nor @option{whole_dur} option is set, the filter will add silence to the end of
  1416. the input stream indefinitely.
  1417. @subsection Examples
  1418. @itemize
  1419. @item
  1420. Add 1024 samples of silence to the end of the input:
  1421. @example
  1422. apad=pad_len=1024
  1423. @end example
  1424. @item
  1425. Make sure the audio output will contain at least 10000 samples, pad
  1426. the input with silence if required:
  1427. @example
  1428. apad=whole_len=10000
  1429. @end example
  1430. @item
  1431. Use @command{ffmpeg} to pad the audio input with silence, so that the
  1432. video stream will always result the shortest and will be converted
  1433. until the end in the output file when using the @option{shortest}
  1434. option:
  1435. @example
  1436. ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
  1437. @end example
  1438. @end itemize
  1439. @section aphaser
  1440. Add a phasing effect to the input audio.
  1441. A phaser filter creates series of peaks and troughs in the frequency spectrum.
  1442. The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
  1443. A description of the accepted parameters follows.
  1444. @table @option
  1445. @item in_gain
  1446. Set input gain. Default is 0.4.
  1447. @item out_gain
  1448. Set output gain. Default is 0.74
  1449. @item delay
  1450. Set delay in milliseconds. Default is 3.0.
  1451. @item decay
  1452. Set decay. Default is 0.4.
  1453. @item speed
  1454. Set modulation speed in Hz. Default is 0.5.
  1455. @item type
  1456. Set modulation type. Default is triangular.
  1457. It accepts the following values:
  1458. @table @samp
  1459. @item triangular, t
  1460. @item sinusoidal, s
  1461. @end table
  1462. @end table
  1463. @section apulsator
  1464. Audio pulsator is something between an autopanner and a tremolo.
  1465. But it can produce funny stereo effects as well. Pulsator changes the volume
  1466. of the left and right channel based on a LFO (low frequency oscillator) with
  1467. different waveforms and shifted phases.
  1468. This filter have the ability to define an offset between left and right
  1469. channel. An offset of 0 means that both LFO shapes match each other.
  1470. The left and right channel are altered equally - a conventional tremolo.
  1471. An offset of 50% means that the shape of the right channel is exactly shifted
  1472. in phase (or moved backwards about half of the frequency) - pulsator acts as
  1473. an autopanner. At 1 both curves match again. Every setting in between moves the
  1474. phase shift gapless between all stages and produces some "bypassing" sounds with
  1475. sine and triangle waveforms. The more you set the offset near 1 (starting from
  1476. the 0.5) the faster the signal passes from the left to the right speaker.
  1477. The filter accepts the following options:
  1478. @table @option
  1479. @item level_in
  1480. Set input gain. By default it is 1. Range is [0.015625 - 64].
  1481. @item level_out
  1482. Set output gain. By default it is 1. Range is [0.015625 - 64].
  1483. @item mode
  1484. Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
  1485. sawup or sawdown. Default is sine.
  1486. @item amount
  1487. Set modulation. Define how much of original signal is affected by the LFO.
  1488. @item offset_l
  1489. Set left channel offset. Default is 0. Allowed range is [0 - 1].
  1490. @item offset_r
  1491. Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
  1492. @item width
  1493. Set pulse width. Default is 1. Allowed range is [0 - 2].
  1494. @item timing
  1495. Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
  1496. @item bpm
  1497. Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
  1498. is set to bpm.
  1499. @item ms
  1500. Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
  1501. is set to ms.
  1502. @item hz
  1503. Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
  1504. if timing is set to hz.
  1505. @end table
  1506. @anchor{aresample}
  1507. @section aresample
  1508. Resample the input audio to the specified parameters, using the
  1509. libswresample library. If none are specified then the filter will
  1510. automatically convert between its input and output.
  1511. This filter is also able to stretch/squeeze the audio data to make it match
  1512. the timestamps or to inject silence / cut out audio to make it match the
  1513. timestamps, do a combination of both or do neither.
  1514. The filter accepts the syntax
  1515. [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
  1516. expresses a sample rate and @var{resampler_options} is a list of
  1517. @var{key}=@var{value} pairs, separated by ":". See the
  1518. @ref{Resampler Options,,"Resampler Options" section in the
  1519. ffmpeg-resampler(1) manual,ffmpeg-resampler}
  1520. for the complete list of supported options.
  1521. @subsection Examples
  1522. @itemize
  1523. @item
  1524. Resample the input audio to 44100Hz:
  1525. @example
  1526. aresample=44100
  1527. @end example
  1528. @item
  1529. Stretch/squeeze samples to the given timestamps, with a maximum of 1000
  1530. samples per second compensation:
  1531. @example
  1532. aresample=async=1000
  1533. @end example
  1534. @end itemize
  1535. @section areverse
  1536. Reverse an audio clip.
  1537. Warning: This filter requires memory to buffer the entire clip, so trimming
  1538. is suggested.
  1539. @subsection Examples
  1540. @itemize
  1541. @item
  1542. Take the first 5 seconds of a clip, and reverse it.
  1543. @example
  1544. atrim=end=5,areverse
  1545. @end example
  1546. @end itemize
  1547. @section asetnsamples
  1548. Set the number of samples per each output audio frame.
  1549. The last output packet may contain a different number of samples, as
  1550. the filter will flush all the remaining samples when the input audio
  1551. signals its end.
  1552. The filter accepts the following options:
  1553. @table @option
  1554. @item nb_out_samples, n
  1555. Set the number of frames per each output audio frame. The number is
  1556. intended as the number of samples @emph{per each channel}.
  1557. Default value is 1024.
  1558. @item pad, p
  1559. If set to 1, the filter will pad the last audio frame with zeroes, so
  1560. that the last frame will contain the same number of samples as the
  1561. previous ones. Default value is 1.
  1562. @end table
  1563. For example, to set the number of per-frame samples to 1234 and
  1564. disable padding for the last frame, use:
  1565. @example
  1566. asetnsamples=n=1234:p=0
  1567. @end example
  1568. @section asetrate
  1569. Set the sample rate without altering the PCM data.
  1570. This will result in a change of speed and pitch.
  1571. The filter accepts the following options:
  1572. @table @option
  1573. @item sample_rate, r
  1574. Set the output sample rate. Default is 44100 Hz.
  1575. @end table
  1576. @section ashowinfo
  1577. Show a line containing various information for each input audio frame.
  1578. The input audio is not modified.
  1579. The shown line contains a sequence of key/value pairs of the form
  1580. @var{key}:@var{value}.
  1581. The following values are shown in the output:
  1582. @table @option
  1583. @item n
  1584. The (sequential) number of the input frame, starting from 0.
  1585. @item pts
  1586. The presentation timestamp of the input frame, in time base units; the time base
  1587. depends on the filter input pad, and is usually 1/@var{sample_rate}.
  1588. @item pts_time
  1589. The presentation timestamp of the input frame in seconds.
  1590. @item pos
  1591. position of the frame in the input stream, -1 if this information in
  1592. unavailable and/or meaningless (for example in case of synthetic audio)
  1593. @item fmt
  1594. The sample format.
  1595. @item chlayout
  1596. The channel layout.
  1597. @item rate
  1598. The sample rate for the audio frame.
  1599. @item nb_samples
  1600. The number of samples (per channel) in the frame.
  1601. @item checksum
  1602. The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
  1603. audio, the data is treated as if all the planes were concatenated.
  1604. @item plane_checksums
  1605. A list of Adler-32 checksums for each data plane.
  1606. @end table
  1607. @anchor{astats}
  1608. @section astats
  1609. Display time domain statistical information about the audio channels.
  1610. Statistics are calculated and displayed for each audio channel and,
  1611. where applicable, an overall figure is also given.
  1612. It accepts the following option:
  1613. @table @option
  1614. @item length
  1615. Short window length in seconds, used for peak and trough RMS measurement.
  1616. Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
  1617. @item metadata
  1618. Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
  1619. where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
  1620. disabled.
  1621. Available keys for each channel are:
  1622. DC_offset
  1623. Min_level
  1624. Max_level
  1625. Min_difference
  1626. Max_difference
  1627. Mean_difference
  1628. RMS_difference
  1629. Peak_level
  1630. RMS_peak
  1631. RMS_trough
  1632. Crest_factor
  1633. Flat_factor
  1634. Peak_count
  1635. Bit_depth
  1636. Dynamic_range
  1637. Zero_crossings
  1638. Zero_crossings_rate
  1639. and for Overall:
  1640. DC_offset
  1641. Min_level
  1642. Max_level
  1643. Min_difference
  1644. Max_difference
  1645. Mean_difference
  1646. RMS_difference
  1647. Peak_level
  1648. RMS_level
  1649. RMS_peak
  1650. RMS_trough
  1651. Flat_factor
  1652. Peak_count
  1653. Bit_depth
  1654. Number_of_samples
  1655. For example full key look like this @code{lavfi.astats.1.DC_offset} or
  1656. this @code{lavfi.astats.Overall.Peak_count}.
  1657. For description what each key means read below.
  1658. @item reset
  1659. Set number of frame after which stats are going to be recalculated.
  1660. Default is disabled.
  1661. @item measure_perchannel
  1662. Select the entries which need to be measured per channel. The metadata keys can
  1663. be used as flags, default is @option{all} which measures everything.
  1664. @option{none} disables all per channel measurement.
  1665. @item measure_overall
  1666. Select the entries which need to be measured overall. The metadata keys can
  1667. be used as flags, default is @option{all} which measures everything.
  1668. @option{none} disables all overall measurement.
  1669. @end table
  1670. A description of each shown parameter follows:
  1671. @table @option
  1672. @item DC offset
  1673. Mean amplitude displacement from zero.
  1674. @item Min level
  1675. Minimal sample level.
  1676. @item Max level
  1677. Maximal sample level.
  1678. @item Min difference
  1679. Minimal difference between two consecutive samples.
  1680. @item Max difference
  1681. Maximal difference between two consecutive samples.
  1682. @item Mean difference
  1683. Mean difference between two consecutive samples.
  1684. The average of each difference between two consecutive samples.
  1685. @item RMS difference
  1686. Root Mean Square difference between two consecutive samples.
  1687. @item Peak level dB
  1688. @item RMS level dB
  1689. Standard peak and RMS level measured in dBFS.
  1690. @item RMS peak dB
  1691. @item RMS trough dB
  1692. Peak and trough values for RMS level measured over a short window.
  1693. @item Crest factor
  1694. Standard ratio of peak to RMS level (note: not in dB).
  1695. @item Flat factor
  1696. Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
  1697. (i.e. either @var{Min level} or @var{Max level}).
  1698. @item Peak count
  1699. Number of occasions (not the number of samples) that the signal attained either
  1700. @var{Min level} or @var{Max level}.
  1701. @item Bit depth
  1702. Overall bit depth of audio. Number of bits used for each sample.
  1703. @item Dynamic range
  1704. Measured dynamic range of audio in dB.
  1705. @item Zero crossings
  1706. Number of points where the waveform crosses the zero level axis.
  1707. @item Zero crossings rate
  1708. Rate of Zero crossings and number of audio samples.
  1709. @end table
  1710. @section atempo
  1711. Adjust audio tempo.
  1712. The filter accepts exactly one parameter, the audio tempo. If not
  1713. specified then the filter will assume nominal 1.0 tempo. Tempo must
  1714. be in the [0.5, 100.0] range.
  1715. Note that tempo greater than 2 will skip some samples rather than
  1716. blend them in. If for any reason this is a concern it is always
  1717. possible to daisy-chain several instances of atempo to achieve the
  1718. desired product tempo.
  1719. @subsection Examples
  1720. @itemize
  1721. @item
  1722. Slow down audio to 80% tempo:
  1723. @example
  1724. atempo=0.8
  1725. @end example
  1726. @item
  1727. To speed up audio to 300% tempo:
  1728. @example
  1729. atempo=3
  1730. @end example
  1731. @item
  1732. To speed up audio to 300% tempo by daisy-chaining two atempo instances:
  1733. @example
  1734. atempo=sqrt(3),atempo=sqrt(3)
  1735. @end example
  1736. @end itemize
  1737. @section atrim
  1738. Trim the input so that the output contains one continuous subpart of the input.
  1739. It accepts the following parameters:
  1740. @table @option
  1741. @item start
  1742. Timestamp (in seconds) of the start of the section to keep. I.e. the audio
  1743. sample with the timestamp @var{start} will be the first sample in the output.
  1744. @item end
  1745. Specify time of the first audio sample that will be dropped, i.e. the
  1746. audio sample immediately preceding the one with the timestamp @var{end} will be
  1747. the last sample in the output.
  1748. @item start_pts
  1749. Same as @var{start}, except this option sets the start timestamp in samples
  1750. instead of seconds.
  1751. @item end_pts
  1752. Same as @var{end}, except this option sets the end timestamp in samples instead
  1753. of seconds.
  1754. @item duration
  1755. The maximum duration of the output in seconds.
  1756. @item start_sample
  1757. The number of the first sample that should be output.
  1758. @item end_sample
  1759. The number of the first sample that should be dropped.
  1760. @end table
  1761. @option{start}, @option{end}, and @option{duration} are expressed as time
  1762. duration specifications; see
  1763. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  1764. Note that the first two sets of the start/end options and the @option{duration}
  1765. option look at the frame timestamp, while the _sample options simply count the
  1766. samples that pass through the filter. So start/end_pts and start/end_sample will
  1767. give different results when the timestamps are wrong, inexact or do not start at
  1768. zero. Also note that this filter does not modify the timestamps. If you wish
  1769. to have the output timestamps start at zero, insert the asetpts filter after the
  1770. atrim filter.
  1771. If multiple start or end options are set, this filter tries to be greedy and
  1772. keep all samples that match at least one of the specified constraints. To keep
  1773. only the part that matches all the constraints at once, chain multiple atrim
  1774. filters.
  1775. The defaults are such that all the input is kept. So it is possible to set e.g.
  1776. just the end values to keep everything before the specified time.
  1777. Examples:
  1778. @itemize
  1779. @item
  1780. Drop everything except the second minute of input:
  1781. @example
  1782. ffmpeg -i INPUT -af atrim=60:120
  1783. @end example
  1784. @item
  1785. Keep only the first 1000 samples:
  1786. @example
  1787. ffmpeg -i INPUT -af atrim=end_sample=1000
  1788. @end example
  1789. @end itemize
  1790. @section bandpass
  1791. Apply a two-pole Butterworth band-pass filter with central
  1792. frequency @var{frequency}, and (3dB-point) band-width width.
  1793. The @var{csg} option selects a constant skirt gain (peak gain = Q)
  1794. instead of the default: constant 0dB peak gain.
  1795. The filter roll off at 6dB per octave (20dB per decade).
  1796. The filter accepts the following options:
  1797. @table @option
  1798. @item frequency, f
  1799. Set the filter's central frequency. Default is @code{3000}.
  1800. @item csg
  1801. Constant skirt gain if set to 1. Defaults to 0.
  1802. @item width_type, t
  1803. Set method to specify band-width of filter.
  1804. @table @option
  1805. @item h
  1806. Hz
  1807. @item q
  1808. Q-Factor
  1809. @item o
  1810. octave
  1811. @item s
  1812. slope
  1813. @item k
  1814. kHz
  1815. @end table
  1816. @item width, w
  1817. Specify the band-width of a filter in width_type units.
  1818. @item channels, c
  1819. Specify which channels to filter, by default all available are filtered.
  1820. @end table
  1821. @subsection Commands
  1822. This filter supports the following commands:
  1823. @table @option
  1824. @item frequency, f
  1825. Change bandpass frequency.
  1826. Syntax for the command is : "@var{frequency}"
  1827. @item width_type, t
  1828. Change bandpass width_type.
  1829. Syntax for the command is : "@var{width_type}"
  1830. @item width, w
  1831. Change bandpass width.
  1832. Syntax for the command is : "@var{width}"
  1833. @end table
  1834. @section bandreject
  1835. Apply a two-pole Butterworth band-reject filter with central
  1836. frequency @var{frequency}, and (3dB-point) band-width @var{width}.
  1837. The filter roll off at 6dB per octave (20dB per decade).
  1838. The filter accepts the following options:
  1839. @table @option
  1840. @item frequency, f
  1841. Set the filter's central frequency. Default is @code{3000}.
  1842. @item width_type, t
  1843. Set method to specify band-width of filter.
  1844. @table @option
  1845. @item h
  1846. Hz
  1847. @item q
  1848. Q-Factor
  1849. @item o
  1850. octave
  1851. @item s
  1852. slope
  1853. @item k
  1854. kHz
  1855. @end table
  1856. @item width, w
  1857. Specify the band-width of a filter in width_type units.
  1858. @item channels, c
  1859. Specify which channels to filter, by default all available are filtered.
  1860. @end table
  1861. @subsection Commands
  1862. This filter supports the following commands:
  1863. @table @option
  1864. @item frequency, f
  1865. Change bandreject frequency.
  1866. Syntax for the command is : "@var{frequency}"
  1867. @item width_type, t
  1868. Change bandreject width_type.
  1869. Syntax for the command is : "@var{width_type}"
  1870. @item width, w
  1871. Change bandreject width.
  1872. Syntax for the command is : "@var{width}"
  1873. @end table
  1874. @section bass, lowshelf
  1875. Boost or cut the bass (lower) frequencies of the audio using a two-pole
  1876. shelving filter with a response similar to that of a standard
  1877. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  1878. The filter accepts the following options:
  1879. @table @option
  1880. @item gain, g
  1881. Give the gain at 0 Hz. Its useful range is about -20
  1882. (for a large cut) to +20 (for a large boost).
  1883. Beware of clipping when using a positive gain.
  1884. @item frequency, f
  1885. Set the filter's central frequency and so can be used
  1886. to extend or reduce the frequency range to be boosted or cut.
  1887. The default value is @code{100} Hz.
  1888. @item width_type, t
  1889. Set method to specify band-width of filter.
  1890. @table @option
  1891. @item h
  1892. Hz
  1893. @item q
  1894. Q-Factor
  1895. @item o
  1896. octave
  1897. @item s
  1898. slope
  1899. @item k
  1900. kHz
  1901. @end table
  1902. @item width, w
  1903. Determine how steep is the filter's shelf transition.
  1904. @item channels, c
  1905. Specify which channels to filter, by default all available are filtered.
  1906. @end table
  1907. @subsection Commands
  1908. This filter supports the following commands:
  1909. @table @option
  1910. @item frequency, f
  1911. Change bass frequency.
  1912. Syntax for the command is : "@var{frequency}"
  1913. @item width_type, t
  1914. Change bass width_type.
  1915. Syntax for the command is : "@var{width_type}"
  1916. @item width, w
  1917. Change bass width.
  1918. Syntax for the command is : "@var{width}"
  1919. @item gain, g
  1920. Change bass gain.
  1921. Syntax for the command is : "@var{gain}"
  1922. @end table
  1923. @section biquad
  1924. Apply a biquad IIR filter with the given coefficients.
  1925. Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
  1926. are the numerator and denominator coefficients respectively.
  1927. and @var{channels}, @var{c} specify which channels to filter, by default all
  1928. available are filtered.
  1929. @subsection Commands
  1930. This filter supports the following commands:
  1931. @table @option
  1932. @item a0
  1933. @item a1
  1934. @item a2
  1935. @item b0
  1936. @item b1
  1937. @item b2
  1938. Change biquad parameter.
  1939. Syntax for the command is : "@var{value}"
  1940. @end table
  1941. @section bs2b
  1942. Bauer stereo to binaural transformation, which improves headphone listening of
  1943. stereo audio records.
  1944. To enable compilation of this filter you need to configure FFmpeg with
  1945. @code{--enable-libbs2b}.
  1946. It accepts the following parameters:
  1947. @table @option
  1948. @item profile
  1949. Pre-defined crossfeed level.
  1950. @table @option
  1951. @item default
  1952. Default level (fcut=700, feed=50).
  1953. @item cmoy
  1954. Chu Moy circuit (fcut=700, feed=60).
  1955. @item jmeier
  1956. Jan Meier circuit (fcut=650, feed=95).
  1957. @end table
  1958. @item fcut
  1959. Cut frequency (in Hz).
  1960. @item feed
  1961. Feed level (in Hz).
  1962. @end table
  1963. @section channelmap
  1964. Remap input channels to new locations.
  1965. It accepts the following parameters:
  1966. @table @option
  1967. @item map
  1968. Map channels from input to output. The argument is a '|'-separated list of
  1969. mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
  1970. @var{in_channel} form. @var{in_channel} can be either the name of the input
  1971. channel (e.g. FL for front left) or its index in the input channel layout.
  1972. @var{out_channel} is the name of the output channel or its index in the output
  1973. channel layout. If @var{out_channel} is not given then it is implicitly an
  1974. index, starting with zero and increasing by one for each mapping.
  1975. @item channel_layout
  1976. The channel layout of the output stream.
  1977. @end table
  1978. If no mapping is present, the filter will implicitly map input channels to
  1979. output channels, preserving indices.
  1980. @subsection Examples
  1981. @itemize
  1982. @item
  1983. For example, assuming a 5.1+downmix input MOV file,
  1984. @example
  1985. ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
  1986. @end example
  1987. will create an output WAV file tagged as stereo from the downmix channels of
  1988. the input.
  1989. @item
  1990. To fix a 5.1 WAV improperly encoded in AAC's native channel order
  1991. @example
  1992. ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
  1993. @end example
  1994. @end itemize
  1995. @section channelsplit
  1996. Split each channel from an input audio stream into a separate output stream.
  1997. It accepts the following parameters:
  1998. @table @option
  1999. @item channel_layout
  2000. The channel layout of the input stream. The default is "stereo".
  2001. @item channels
  2002. A channel layout describing the channels to be extracted as separate output streams
  2003. or "all" to extract each input channel as a separate stream. The default is "all".
  2004. Choosing channels not present in channel layout in the input will result in an error.
  2005. @end table
  2006. @subsection Examples
  2007. @itemize
  2008. @item
  2009. For example, assuming a stereo input MP3 file,
  2010. @example
  2011. ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
  2012. @end example
  2013. will create an output Matroska file with two audio streams, one containing only
  2014. the left channel and the other the right channel.
  2015. @item
  2016. Split a 5.1 WAV file into per-channel files:
  2017. @example
  2018. ffmpeg -i in.wav -filter_complex
  2019. 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
  2020. -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
  2021. front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
  2022. side_right.wav
  2023. @end example
  2024. @item
  2025. Extract only LFE from a 5.1 WAV file:
  2026. @example
  2027. ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
  2028. -map '[LFE]' lfe.wav
  2029. @end example
  2030. @end itemize
  2031. @section chorus
  2032. Add a chorus effect to the audio.
  2033. Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
  2034. Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
  2035. constant, with chorus, it is varied using using sinusoidal or triangular modulation.
  2036. The modulation depth defines the range the modulated delay is played before or after
  2037. the delay. Hence the delayed sound will sound slower or faster, that is the delayed
  2038. sound tuned around the original one, like in a chorus where some vocals are slightly
  2039. off key.
  2040. It accepts the following parameters:
  2041. @table @option
  2042. @item in_gain
  2043. Set input gain. Default is 0.4.
  2044. @item out_gain
  2045. Set output gain. Default is 0.4.
  2046. @item delays
  2047. Set delays. A typical delay is around 40ms to 60ms.
  2048. @item decays
  2049. Set decays.
  2050. @item speeds
  2051. Set speeds.
  2052. @item depths
  2053. Set depths.
  2054. @end table
  2055. @subsection Examples
  2056. @itemize
  2057. @item
  2058. A single delay:
  2059. @example
  2060. chorus=0.7:0.9:55:0.4:0.25:2
  2061. @end example
  2062. @item
  2063. Two delays:
  2064. @example
  2065. chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
  2066. @end example
  2067. @item
  2068. Fuller sounding chorus with three delays:
  2069. @example
  2070. 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
  2071. @end example
  2072. @end itemize
  2073. @section compand
  2074. Compress or expand the audio's dynamic range.
  2075. It accepts the following parameters:
  2076. @table @option
  2077. @item attacks
  2078. @item decays
  2079. A list of times in seconds for each channel over which the instantaneous level
  2080. of the input signal is averaged to determine its volume. @var{attacks} refers to
  2081. increase of volume and @var{decays} refers to decrease of volume. For most
  2082. situations, the attack time (response to the audio getting louder) should be
  2083. shorter than the decay time, because the human ear is more sensitive to sudden
  2084. loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
  2085. a typical value for decay is 0.8 seconds.
  2086. If specified number of attacks & decays is lower than number of channels, the last
  2087. set attack/decay will be used for all remaining channels.
  2088. @item points
  2089. A list of points for the transfer function, specified in dB relative to the
  2090. maximum possible signal amplitude. Each key points list must be defined using
  2091. the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
  2092. @code{x0/y0 x1/y1 x2/y2 ....}
  2093. The input values must be in strictly increasing order but the transfer function
  2094. does not have to be monotonically rising. The point @code{0/0} is assumed but
  2095. may be overridden (by @code{0/out-dBn}). Typical values for the transfer
  2096. function are @code{-70/-70|-60/-20|1/0}.
  2097. @item soft-knee
  2098. Set the curve radius in dB for all joints. It defaults to 0.01.
  2099. @item gain
  2100. Set the additional gain in dB to be applied at all points on the transfer
  2101. function. This allows for easy adjustment of the overall gain.
  2102. It defaults to 0.
  2103. @item volume
  2104. Set an initial volume, in dB, to be assumed for each channel when filtering
  2105. starts. This permits the user to supply a nominal level initially, so that, for
  2106. example, a very large gain is not applied to initial signal levels before the
  2107. companding has begun to operate. A typical value for audio which is initially
  2108. quiet is -90 dB. It defaults to 0.
  2109. @item delay
  2110. Set a delay, in seconds. The input audio is analyzed immediately, but audio is
  2111. delayed before being fed to the volume adjuster. Specifying a delay
  2112. approximately equal to the attack/decay times allows the filter to effectively
  2113. operate in predictive rather than reactive mode. It defaults to 0.
  2114. @end table
  2115. @subsection Examples
  2116. @itemize
  2117. @item
  2118. Make music with both quiet and loud passages suitable for listening to in a
  2119. noisy environment:
  2120. @example
  2121. compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
  2122. @end example
  2123. Another example for audio with whisper and explosion parts:
  2124. @example
  2125. compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
  2126. @end example
  2127. @item
  2128. A noise gate for when the noise is at a lower level than the signal:
  2129. @example
  2130. compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
  2131. @end example
  2132. @item
  2133. Here is another noise gate, this time for when the noise is at a higher level
  2134. than the signal (making it, in some ways, similar to squelch):
  2135. @example
  2136. compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
  2137. @end example
  2138. @item
  2139. 2:1 compression starting at -6dB:
  2140. @example
  2141. compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
  2142. @end example
  2143. @item
  2144. 2:1 compression starting at -9dB:
  2145. @example
  2146. compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
  2147. @end example
  2148. @item
  2149. 2:1 compression starting at -12dB:
  2150. @example
  2151. compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
  2152. @end example
  2153. @item
  2154. 2:1 compression starting at -18dB:
  2155. @example
  2156. compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
  2157. @end example
  2158. @item
  2159. 3:1 compression starting at -15dB:
  2160. @example
  2161. compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
  2162. @end example
  2163. @item
  2164. Compressor/Gate:
  2165. @example
  2166. compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
  2167. @end example
  2168. @item
  2169. Expander:
  2170. @example
  2171. 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
  2172. @end example
  2173. @item
  2174. Hard limiter at -6dB:
  2175. @example
  2176. compand=attacks=0:points=-80/-80|-6/-6|20/-6
  2177. @end example
  2178. @item
  2179. Hard limiter at -12dB:
  2180. @example
  2181. compand=attacks=0:points=-80/-80|-12/-12|20/-12
  2182. @end example
  2183. @item
  2184. Hard noise gate at -35 dB:
  2185. @example
  2186. compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
  2187. @end example
  2188. @item
  2189. Soft limiter:
  2190. @example
  2191. compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
  2192. @end example
  2193. @end itemize
  2194. @section compensationdelay
  2195. Compensation Delay Line is a metric based delay to compensate differing
  2196. positions of microphones or speakers.
  2197. For example, you have recorded guitar with two microphones placed in
  2198. different location. Because the front of sound wave has fixed speed in
  2199. normal conditions, the phasing of microphones can vary and depends on
  2200. their location and interposition. The best sound mix can be achieved when
  2201. these microphones are in phase (synchronized). Note that distance of
  2202. ~30 cm between microphones makes one microphone to capture signal in
  2203. antiphase to another microphone. That makes the final mix sounding moody.
  2204. This filter helps to solve phasing problems by adding different delays
  2205. to each microphone track and make them synchronized.
  2206. The best result can be reached when you take one track as base and
  2207. synchronize other tracks one by one with it.
  2208. Remember that synchronization/delay tolerance depends on sample rate, too.
  2209. Higher sample rates will give more tolerance.
  2210. It accepts the following parameters:
  2211. @table @option
  2212. @item mm
  2213. Set millimeters distance. This is compensation distance for fine tuning.
  2214. Default is 0.
  2215. @item cm
  2216. Set cm distance. This is compensation distance for tightening distance setup.
  2217. Default is 0.
  2218. @item m
  2219. Set meters distance. This is compensation distance for hard distance setup.
  2220. Default is 0.
  2221. @item dry
  2222. Set dry amount. Amount of unprocessed (dry) signal.
  2223. Default is 0.
  2224. @item wet
  2225. Set wet amount. Amount of processed (wet) signal.
  2226. Default is 1.
  2227. @item temp
  2228. Set temperature degree in Celsius. This is the temperature of the environment.
  2229. Default is 20.
  2230. @end table
  2231. @section crossfeed
  2232. Apply headphone crossfeed filter.
  2233. Crossfeed is the process of blending the left and right channels of stereo
  2234. audio recording.
  2235. It is mainly used to reduce extreme stereo separation of low frequencies.
  2236. The intent is to produce more speaker like sound to the listener.
  2237. The filter accepts the following options:
  2238. @table @option
  2239. @item strength
  2240. Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
  2241. This sets gain of low shelf filter for side part of stereo image.
  2242. Default is -6dB. Max allowed is -30db when strength is set to 1.
  2243. @item range
  2244. Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
  2245. This sets cut off frequency of low shelf filter. Default is cut off near
  2246. 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
  2247. @item level_in
  2248. Set input gain. Default is 0.9.
  2249. @item level_out
  2250. Set output gain. Default is 1.
  2251. @end table
  2252. @section crystalizer
  2253. Simple algorithm to expand audio dynamic range.
  2254. The filter accepts the following options:
  2255. @table @option
  2256. @item i
  2257. Sets the intensity of effect (default: 2.0). Must be in range between 0.0
  2258. (unchanged sound) to 10.0 (maximum effect).
  2259. @item c
  2260. Enable clipping. By default is enabled.
  2261. @end table
  2262. @section dcshift
  2263. Apply a DC shift to the audio.
  2264. This can be useful to remove a DC offset (caused perhaps by a hardware problem
  2265. in the recording chain) from the audio. The effect of a DC offset is reduced
  2266. headroom and hence volume. The @ref{astats} filter can be used to determine if
  2267. a signal has a DC offset.
  2268. @table @option
  2269. @item shift
  2270. Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
  2271. the audio.
  2272. @item limitergain
  2273. Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
  2274. used to prevent clipping.
  2275. @end table
  2276. @section drmeter
  2277. Measure audio dynamic range.
  2278. DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
  2279. is found in transition material. And anything less that 8 have very poor dynamics
  2280. and is very compressed.
  2281. The filter accepts the following options:
  2282. @table @option
  2283. @item length
  2284. Set window length in seconds used to split audio into segments of equal length.
  2285. Default is 3 seconds.
  2286. @end table
  2287. @section dynaudnorm
  2288. Dynamic Audio Normalizer.
  2289. This filter applies a certain amount of gain to the input audio in order
  2290. to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
  2291. contrast to more "simple" normalization algorithms, the Dynamic Audio
  2292. Normalizer *dynamically* re-adjusts the gain factor to the input audio.
  2293. This allows for applying extra gain to the "quiet" sections of the audio
  2294. while avoiding distortions or clipping the "loud" sections. In other words:
  2295. The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
  2296. sections, in the sense that the volume of each section is brought to the
  2297. same target level. Note, however, that the Dynamic Audio Normalizer achieves
  2298. this goal *without* applying "dynamic range compressing". It will retain 100%
  2299. of the dynamic range *within* each section of the audio file.
  2300. @table @option
  2301. @item f
  2302. Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
  2303. Default is 500 milliseconds.
  2304. The Dynamic Audio Normalizer processes the input audio in small chunks,
  2305. referred to as frames. This is required, because a peak magnitude has no
  2306. meaning for just a single sample value. Instead, we need to determine the
  2307. peak magnitude for a contiguous sequence of sample values. While a "standard"
  2308. normalizer would simply use the peak magnitude of the complete file, the
  2309. Dynamic Audio Normalizer determines the peak magnitude individually for each
  2310. frame. The length of a frame is specified in milliseconds. By default, the
  2311. Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
  2312. been found to give good results with most files.
  2313. Note that the exact frame length, in number of samples, will be determined
  2314. automatically, based on the sampling rate of the individual input audio file.
  2315. @item g
  2316. Set the Gaussian filter window size. In range from 3 to 301, must be odd
  2317. number. Default is 31.
  2318. Probably the most important parameter of the Dynamic Audio Normalizer is the
  2319. @code{window size} of the Gaussian smoothing filter. The filter's window size
  2320. is specified in frames, centered around the current frame. For the sake of
  2321. simplicity, this must be an odd number. Consequently, the default value of 31
  2322. takes into account the current frame, as well as the 15 preceding frames and
  2323. the 15 subsequent frames. Using a larger window results in a stronger
  2324. smoothing effect and thus in less gain variation, i.e. slower gain
  2325. adaptation. Conversely, using a smaller window results in a weaker smoothing
  2326. effect and thus in more gain variation, i.e. faster gain adaptation.
  2327. In other words, the more you increase this value, the more the Dynamic Audio
  2328. Normalizer will behave like a "traditional" normalization filter. On the
  2329. contrary, the more you decrease this value, the more the Dynamic Audio
  2330. Normalizer will behave like a dynamic range compressor.
  2331. @item p
  2332. Set the target peak value. This specifies the highest permissible magnitude
  2333. level for the normalized audio input. This filter will try to approach the
  2334. target peak magnitude as closely as possible, but at the same time it also
  2335. makes sure that the normalized signal will never exceed the peak magnitude.
  2336. A frame's maximum local gain factor is imposed directly by the target peak
  2337. magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
  2338. It is not recommended to go above this value.
  2339. @item m
  2340. Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
  2341. The Dynamic Audio Normalizer determines the maximum possible (local) gain
  2342. factor for each input frame, i.e. the maximum gain factor that does not
  2343. result in clipping or distortion. The maximum gain factor is determined by
  2344. the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
  2345. additionally bounds the frame's maximum gain factor by a predetermined
  2346. (global) maximum gain factor. This is done in order to avoid excessive gain
  2347. factors in "silent" or almost silent frames. By default, the maximum gain
  2348. factor is 10.0, For most inputs the default value should be sufficient and
  2349. it usually is not recommended to increase this value. Though, for input
  2350. with an extremely low overall volume level, it may be necessary to allow even
  2351. higher gain factors. Note, however, that the Dynamic Audio Normalizer does
  2352. not simply apply a "hard" threshold (i.e. cut off values above the threshold).
  2353. Instead, a "sigmoid" threshold function will be applied. This way, the
  2354. gain factors will smoothly approach the threshold value, but never exceed that
  2355. value.
  2356. @item r
  2357. Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
  2358. By default, the Dynamic Audio Normalizer performs "peak" normalization.
  2359. This means that the maximum local gain factor for each frame is defined
  2360. (only) by the frame's highest magnitude sample. This way, the samples can
  2361. be amplified as much as possible without exceeding the maximum signal
  2362. level, i.e. without clipping. Optionally, however, the Dynamic Audio
  2363. Normalizer can also take into account the frame's root mean square,
  2364. abbreviated RMS. In electrical engineering, the RMS is commonly used to
  2365. determine the power of a time-varying signal. It is therefore considered
  2366. that the RMS is a better approximation of the "perceived loudness" than
  2367. just looking at the signal's peak magnitude. Consequently, by adjusting all
  2368. frames to a constant RMS value, a uniform "perceived loudness" can be
  2369. established. If a target RMS value has been specified, a frame's local gain
  2370. factor is defined as the factor that would result in exactly that RMS value.
  2371. Note, however, that the maximum local gain factor is still restricted by the
  2372. frame's highest magnitude sample, in order to prevent clipping.
  2373. @item n
  2374. Enable channels coupling. By default is enabled.
  2375. By default, the Dynamic Audio Normalizer will amplify all channels by the same
  2376. amount. This means the same gain factor will be applied to all channels, i.e.
  2377. the maximum possible gain factor is determined by the "loudest" channel.
  2378. However, in some recordings, it may happen that the volume of the different
  2379. channels is uneven, e.g. one channel may be "quieter" than the other one(s).
  2380. In this case, this option can be used to disable the channel coupling. This way,
  2381. the gain factor will be determined independently for each channel, depending
  2382. only on the individual channel's highest magnitude sample. This allows for
  2383. harmonizing the volume of the different channels.
  2384. @item c
  2385. Enable DC bias correction. By default is disabled.
  2386. An audio signal (in the time domain) is a sequence of sample values.
  2387. In the Dynamic Audio Normalizer these sample values are represented in the
  2388. -1.0 to 1.0 range, regardless of the original input format. Normally, the
  2389. audio signal, or "waveform", should be centered around the zero point.
  2390. That means if we calculate the mean value of all samples in a file, or in a
  2391. single frame, then the result should be 0.0 or at least very close to that
  2392. value. If, however, there is a significant deviation of the mean value from
  2393. 0.0, in either positive or negative direction, this is referred to as a
  2394. DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
  2395. Audio Normalizer provides optional DC bias correction.
  2396. With DC bias correction enabled, the Dynamic Audio Normalizer will determine
  2397. the mean value, or "DC correction" offset, of each input frame and subtract
  2398. that value from all of the frame's sample values which ensures those samples
  2399. are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
  2400. boundaries, the DC correction offset values will be interpolated smoothly
  2401. between neighbouring frames.
  2402. @item b
  2403. Enable alternative boundary mode. By default is disabled.
  2404. The Dynamic Audio Normalizer takes into account a certain neighbourhood
  2405. around each frame. This includes the preceding frames as well as the
  2406. subsequent frames. However, for the "boundary" frames, located at the very
  2407. beginning and at the very end of the audio file, not all neighbouring
  2408. frames are available. In particular, for the first few frames in the audio
  2409. file, the preceding frames are not known. And, similarly, for the last few
  2410. frames in the audio file, the subsequent frames are not known. Thus, the
  2411. question arises which gain factors should be assumed for the missing frames
  2412. in the "boundary" region. The Dynamic Audio Normalizer implements two modes
  2413. to deal with this situation. The default boundary mode assumes a gain factor
  2414. of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
  2415. "fade out" at the beginning and at the end of the input, respectively.
  2416. @item s
  2417. Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
  2418. By default, the Dynamic Audio Normalizer does not apply "traditional"
  2419. compression. This means that signal peaks will not be pruned and thus the
  2420. full dynamic range will be retained within each local neighbourhood. However,
  2421. in some cases it may be desirable to combine the Dynamic Audio Normalizer's
  2422. normalization algorithm with a more "traditional" compression.
  2423. For this purpose, the Dynamic Audio Normalizer provides an optional compression
  2424. (thresholding) function. If (and only if) the compression feature is enabled,
  2425. all input frames will be processed by a soft knee thresholding function prior
  2426. to the actual normalization process. Put simply, the thresholding function is
  2427. going to prune all samples whose magnitude exceeds a certain threshold value.
  2428. However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
  2429. value. Instead, the threshold value will be adjusted for each individual
  2430. frame.
  2431. In general, smaller parameters result in stronger compression, and vice versa.
  2432. Values below 3.0 are not recommended, because audible distortion may appear.
  2433. @end table
  2434. @section earwax
  2435. Make audio easier to listen to on headphones.
  2436. This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
  2437. so that when listened to on headphones the stereo image is moved from
  2438. inside your head (standard for headphones) to outside and in front of
  2439. the listener (standard for speakers).
  2440. Ported from SoX.
  2441. @section equalizer
  2442. Apply a two-pole peaking equalisation (EQ) filter. With this
  2443. filter, the signal-level at and around a selected frequency can
  2444. be increased or decreased, whilst (unlike bandpass and bandreject
  2445. filters) that at all other frequencies is unchanged.
  2446. In order to produce complex equalisation curves, this filter can
  2447. be given several times, each with a different central frequency.
  2448. The filter accepts the following options:
  2449. @table @option
  2450. @item frequency, f
  2451. Set the filter's central frequency in Hz.
  2452. @item width_type, t
  2453. Set method to specify band-width of filter.
  2454. @table @option
  2455. @item h
  2456. Hz
  2457. @item q
  2458. Q-Factor
  2459. @item o
  2460. octave
  2461. @item s
  2462. slope
  2463. @item k
  2464. kHz
  2465. @end table
  2466. @item width, w
  2467. Specify the band-width of a filter in width_type units.
  2468. @item gain, g
  2469. Set the required gain or attenuation in dB.
  2470. Beware of clipping when using a positive gain.
  2471. @item channels, c
  2472. Specify which channels to filter, by default all available are filtered.
  2473. @end table
  2474. @subsection Examples
  2475. @itemize
  2476. @item
  2477. Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
  2478. @example
  2479. equalizer=f=1000:t=h:width=200:g=-10
  2480. @end example
  2481. @item
  2482. Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
  2483. @example
  2484. equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
  2485. @end example
  2486. @end itemize
  2487. @subsection Commands
  2488. This filter supports the following commands:
  2489. @table @option
  2490. @item frequency, f
  2491. Change equalizer frequency.
  2492. Syntax for the command is : "@var{frequency}"
  2493. @item width_type, t
  2494. Change equalizer width_type.
  2495. Syntax for the command is : "@var{width_type}"
  2496. @item width, w
  2497. Change equalizer width.
  2498. Syntax for the command is : "@var{width}"
  2499. @item gain, g
  2500. Change equalizer gain.
  2501. Syntax for the command is : "@var{gain}"
  2502. @end table
  2503. @section extrastereo
  2504. Linearly increases the difference between left and right channels which
  2505. adds some sort of "live" effect to playback.
  2506. The filter accepts the following options:
  2507. @table @option
  2508. @item m
  2509. Sets the difference coefficient (default: 2.5). 0.0 means mono sound
  2510. (average of both channels), with 1.0 sound will be unchanged, with
  2511. -1.0 left and right channels will be swapped.
  2512. @item c
  2513. Enable clipping. By default is enabled.
  2514. @end table
  2515. @section firequalizer
  2516. Apply FIR Equalization using arbitrary frequency response.
  2517. The filter accepts the following option:
  2518. @table @option
  2519. @item gain
  2520. Set gain curve equation (in dB). The expression can contain variables:
  2521. @table @option
  2522. @item f
  2523. the evaluated frequency
  2524. @item sr
  2525. sample rate
  2526. @item ch
  2527. channel number, set to 0 when multichannels evaluation is disabled
  2528. @item chid
  2529. channel id, see libavutil/channel_layout.h, set to the first channel id when
  2530. multichannels evaluation is disabled
  2531. @item chs
  2532. number of channels
  2533. @item chlayout
  2534. channel_layout, see libavutil/channel_layout.h
  2535. @end table
  2536. and functions:
  2537. @table @option
  2538. @item gain_interpolate(f)
  2539. interpolate gain on frequency f based on gain_entry
  2540. @item cubic_interpolate(f)
  2541. same as gain_interpolate, but smoother
  2542. @end table
  2543. This option is also available as command. Default is @code{gain_interpolate(f)}.
  2544. @item gain_entry
  2545. Set gain entry for gain_interpolate function. The expression can
  2546. contain functions:
  2547. @table @option
  2548. @item entry(f, g)
  2549. store gain entry at frequency f with value g
  2550. @end table
  2551. This option is also available as command.
  2552. @item delay
  2553. Set filter delay in seconds. Higher value means more accurate.
  2554. Default is @code{0.01}.
  2555. @item accuracy
  2556. Set filter accuracy in Hz. Lower value means more accurate.
  2557. Default is @code{5}.
  2558. @item wfunc
  2559. Set window function. Acceptable values are:
  2560. @table @option
  2561. @item rectangular
  2562. rectangular window, useful when gain curve is already smooth
  2563. @item hann
  2564. hann window (default)
  2565. @item hamming
  2566. hamming window
  2567. @item blackman
  2568. blackman window
  2569. @item nuttall3
  2570. 3-terms continuous 1st derivative nuttall window
  2571. @item mnuttall3
  2572. minimum 3-terms discontinuous nuttall window
  2573. @item nuttall
  2574. 4-terms continuous 1st derivative nuttall window
  2575. @item bnuttall
  2576. minimum 4-terms discontinuous nuttall (blackman-nuttall) window
  2577. @item bharris
  2578. blackman-harris window
  2579. @item tukey
  2580. tukey window
  2581. @end table
  2582. @item fixed
  2583. If enabled, use fixed number of audio samples. This improves speed when
  2584. filtering with large delay. Default is disabled.
  2585. @item multi
  2586. Enable multichannels evaluation on gain. Default is disabled.
  2587. @item zero_phase
  2588. Enable zero phase mode by subtracting timestamp to compensate delay.
  2589. Default is disabled.
  2590. @item scale
  2591. Set scale used by gain. Acceptable values are:
  2592. @table @option
  2593. @item linlin
  2594. linear frequency, linear gain
  2595. @item linlog
  2596. linear frequency, logarithmic (in dB) gain (default)
  2597. @item loglin
  2598. logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
  2599. @item loglog
  2600. logarithmic frequency, logarithmic gain
  2601. @end table
  2602. @item dumpfile
  2603. Set file for dumping, suitable for gnuplot.
  2604. @item dumpscale
  2605. Set scale for dumpfile. Acceptable values are same with scale option.
  2606. Default is linlog.
  2607. @item fft2
  2608. Enable 2-channel convolution using complex FFT. This improves speed significantly.
  2609. Default is disabled.
  2610. @item min_phase
  2611. Enable minimum phase impulse response. Default is disabled.
  2612. @end table
  2613. @subsection Examples
  2614. @itemize
  2615. @item
  2616. lowpass at 1000 Hz:
  2617. @example
  2618. firequalizer=gain='if(lt(f,1000), 0, -INF)'
  2619. @end example
  2620. @item
  2621. lowpass at 1000 Hz with gain_entry:
  2622. @example
  2623. firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
  2624. @end example
  2625. @item
  2626. custom equalization:
  2627. @example
  2628. firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
  2629. @end example
  2630. @item
  2631. higher delay with zero phase to compensate delay:
  2632. @example
  2633. firequalizer=delay=0.1:fixed=on:zero_phase=on
  2634. @end example
  2635. @item
  2636. lowpass on left channel, highpass on right channel:
  2637. @example
  2638. firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
  2639. :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
  2640. @end example
  2641. @end itemize
  2642. @section flanger
  2643. Apply a flanging effect to the audio.
  2644. The filter accepts the following options:
  2645. @table @option
  2646. @item delay
  2647. Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
  2648. @item depth
  2649. Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
  2650. @item regen
  2651. Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
  2652. Default value is 0.
  2653. @item width
  2654. Set percentage of delayed signal mixed with original. Range from 0 to 100.
  2655. Default value is 71.
  2656. @item speed
  2657. Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
  2658. @item shape
  2659. Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
  2660. Default value is @var{sinusoidal}.
  2661. @item phase
  2662. Set swept wave percentage-shift for multi channel. Range from 0 to 100.
  2663. Default value is 25.
  2664. @item interp
  2665. Set delay-line interpolation, @var{linear} or @var{quadratic}.
  2666. Default is @var{linear}.
  2667. @end table
  2668. @section haas
  2669. Apply Haas effect to audio.
  2670. Note that this makes most sense to apply on mono signals.
  2671. With this filter applied to mono signals it give some directionality and
  2672. stretches its stereo image.
  2673. The filter accepts the following options:
  2674. @table @option
  2675. @item level_in
  2676. Set input level. By default is @var{1}, or 0dB
  2677. @item level_out
  2678. Set output level. By default is @var{1}, or 0dB.
  2679. @item side_gain
  2680. Set gain applied to side part of signal. By default is @var{1}.
  2681. @item middle_source
  2682. Set kind of middle source. Can be one of the following:
  2683. @table @samp
  2684. @item left
  2685. Pick left channel.
  2686. @item right
  2687. Pick right channel.
  2688. @item mid
  2689. Pick middle part signal of stereo image.
  2690. @item side
  2691. Pick side part signal of stereo image.
  2692. @end table
  2693. @item middle_phase
  2694. Change middle phase. By default is disabled.
  2695. @item left_delay
  2696. Set left channel delay. By default is @var{2.05} milliseconds.
  2697. @item left_balance
  2698. Set left channel balance. By default is @var{-1}.
  2699. @item left_gain
  2700. Set left channel gain. By default is @var{1}.
  2701. @item left_phase
  2702. Change left phase. By default is disabled.
  2703. @item right_delay
  2704. Set right channel delay. By defaults is @var{2.12} milliseconds.
  2705. @item right_balance
  2706. Set right channel balance. By default is @var{1}.
  2707. @item right_gain
  2708. Set right channel gain. By default is @var{1}.
  2709. @item right_phase
  2710. Change right phase. By default is enabled.
  2711. @end table
  2712. @section hdcd
  2713. Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
  2714. embedded HDCD codes is expanded into a 20-bit PCM stream.
  2715. The filter supports the Peak Extend and Low-level Gain Adjustment features
  2716. of HDCD, and detects the Transient Filter flag.
  2717. @example
  2718. ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
  2719. @end example
  2720. When using the filter with wav, note the default encoding for wav is 16-bit,
  2721. so the resulting 20-bit stream will be truncated back to 16-bit. Use something
  2722. like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
  2723. @example
  2724. ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
  2725. ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
  2726. @end example
  2727. The filter accepts the following options:
  2728. @table @option
  2729. @item disable_autoconvert
  2730. Disable any automatic format conversion or resampling in the filter graph.
  2731. @item process_stereo
  2732. Process the stereo channels together. If target_gain does not match between
  2733. channels, consider it invalid and use the last valid target_gain.
  2734. @item cdt_ms
  2735. Set the code detect timer period in ms.
  2736. @item force_pe
  2737. Always extend peaks above -3dBFS even if PE isn't signaled.
  2738. @item analyze_mode
  2739. Replace audio with a solid tone and adjust the amplitude to signal some
  2740. specific aspect of the decoding process. The output file can be loaded in
  2741. an audio editor alongside the original to aid analysis.
  2742. @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
  2743. Modes are:
  2744. @table @samp
  2745. @item 0, off
  2746. Disabled
  2747. @item 1, lle
  2748. Gain adjustment level at each sample
  2749. @item 2, pe
  2750. Samples where peak extend occurs
  2751. @item 3, cdt
  2752. Samples where the code detect timer is active
  2753. @item 4, tgm
  2754. Samples where the target gain does not match between channels
  2755. @end table
  2756. @end table
  2757. @section headphone
  2758. Apply head-related transfer functions (HRTFs) to create virtual
  2759. loudspeakers around the user for binaural listening via headphones.
  2760. The HRIRs are provided via additional streams, for each channel
  2761. one stereo input stream is needed.
  2762. The filter accepts the following options:
  2763. @table @option
  2764. @item map
  2765. Set mapping of input streams for convolution.
  2766. The argument is a '|'-separated list of channel names in order as they
  2767. are given as additional stream inputs for filter.
  2768. This also specify number of input streams. Number of input streams
  2769. must be not less than number of channels in first stream plus one.
  2770. @item gain
  2771. Set gain applied to audio. Value is in dB. Default is 0.
  2772. @item type
  2773. Set processing type. Can be @var{time} or @var{freq}. @var{time} is
  2774. processing audio in time domain which is slow.
  2775. @var{freq} is processing audio in frequency domain which is fast.
  2776. Default is @var{freq}.
  2777. @item lfe
  2778. Set custom gain for LFE channels. Value is in dB. Default is 0.
  2779. @item size
  2780. Set size of frame in number of samples which will be processed at once.
  2781. Default value is @var{1024}. Allowed range is from 1024 to 96000.
  2782. @item hrir
  2783. Set format of hrir stream.
  2784. Default value is @var{stereo}. Alternative value is @var{multich}.
  2785. If value is set to @var{stereo}, number of additional streams should
  2786. be greater or equal to number of input channels in first input stream.
  2787. Also each additional stream should have stereo number of channels.
  2788. If value is set to @var{multich}, number of additional streams should
  2789. be exactly one. Also number of input channels of additional stream
  2790. should be equal or greater than twice number of channels of first input
  2791. stream.
  2792. @end table
  2793. @subsection Examples
  2794. @itemize
  2795. @item
  2796. Full example using wav files as coefficients with amovie filters for 7.1 downmix,
  2797. each amovie filter use stereo file with IR coefficients as input.
  2798. The files give coefficients for each position of virtual loudspeaker:
  2799. @example
  2800. ffmpeg -i input.wav
  2801. -filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
  2802. output.wav
  2803. @end example
  2804. @item
  2805. Full example using wav files as coefficients with amovie filters for 7.1 downmix,
  2806. but now in @var{multich} @var{hrir} format.
  2807. @example
  2808. ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
  2809. output.wav
  2810. @end example
  2811. @end itemize
  2812. @section highpass
  2813. Apply a high-pass filter with 3dB point frequency.
  2814. The filter can be either single-pole, or double-pole (the default).
  2815. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  2816. The filter accepts the following options:
  2817. @table @option
  2818. @item frequency, f
  2819. Set frequency in Hz. Default is 3000.
  2820. @item poles, p
  2821. Set number of poles. Default is 2.
  2822. @item width_type, t
  2823. Set method to specify band-width of filter.
  2824. @table @option
  2825. @item h
  2826. Hz
  2827. @item q
  2828. Q-Factor
  2829. @item o
  2830. octave
  2831. @item s
  2832. slope
  2833. @item k
  2834. kHz
  2835. @end table
  2836. @item width, w
  2837. Specify the band-width of a filter in width_type units.
  2838. Applies only to double-pole filter.
  2839. The default is 0.707q and gives a Butterworth response.
  2840. @item channels, c
  2841. Specify which channels to filter, by default all available are filtered.
  2842. @end table
  2843. @subsection Commands
  2844. This filter supports the following commands:
  2845. @table @option
  2846. @item frequency, f
  2847. Change highpass frequency.
  2848. Syntax for the command is : "@var{frequency}"
  2849. @item width_type, t
  2850. Change highpass width_type.
  2851. Syntax for the command is : "@var{width_type}"
  2852. @item width, w
  2853. Change highpass width.
  2854. Syntax for the command is : "@var{width}"
  2855. @end table
  2856. @section join
  2857. Join multiple input streams into one multi-channel stream.
  2858. It accepts the following parameters:
  2859. @table @option
  2860. @item inputs
  2861. The number of input streams. It defaults to 2.
  2862. @item channel_layout
  2863. The desired output channel layout. It defaults to stereo.
  2864. @item map
  2865. Map channels from inputs to output. The argument is a '|'-separated list of
  2866. mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
  2867. form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
  2868. can be either the name of the input channel (e.g. FL for front left) or its
  2869. index in the specified input stream. @var{out_channel} is the name of the output
  2870. channel.
  2871. @end table
  2872. The filter will attempt to guess the mappings when they are not specified
  2873. explicitly. It does so by first trying to find an unused matching input channel
  2874. and if that fails it picks the first unused input channel.
  2875. Join 3 inputs (with properly set channel layouts):
  2876. @example
  2877. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
  2878. @end example
  2879. Build a 5.1 output from 6 single-channel streams:
  2880. @example
  2881. ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
  2882. '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'
  2883. out
  2884. @end example
  2885. @section ladspa
  2886. Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
  2887. To enable compilation of this filter you need to configure FFmpeg with
  2888. @code{--enable-ladspa}.
  2889. @table @option
  2890. @item file, f
  2891. Specifies the name of LADSPA plugin library to load. If the environment
  2892. variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
  2893. each one of the directories specified by the colon separated list in
  2894. @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
  2895. this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
  2896. @file{/usr/lib/ladspa/}.
  2897. @item plugin, p
  2898. Specifies the plugin within the library. Some libraries contain only
  2899. one plugin, but others contain many of them. If this is not set filter
  2900. will list all available plugins within the specified library.
  2901. @item controls, c
  2902. Set the '|' separated list of controls which are zero or more floating point
  2903. values that determine the behavior of the loaded plugin (for example delay,
  2904. threshold or gain).
  2905. Controls need to be defined using the following syntax:
  2906. c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
  2907. @var{valuei} is the value set on the @var{i}-th control.
  2908. Alternatively they can be also defined using the following syntax:
  2909. @var{value0}|@var{value1}|@var{value2}|..., where
  2910. @var{valuei} is the value set on the @var{i}-th control.
  2911. If @option{controls} is set to @code{help}, all available controls and
  2912. their valid ranges are printed.
  2913. @item sample_rate, s
  2914. Specify the sample rate, default to 44100. Only used if plugin have
  2915. zero inputs.
  2916. @item nb_samples, n
  2917. Set the number of samples per channel per each output frame, default
  2918. is 1024. Only used if plugin have zero inputs.
  2919. @item duration, d
  2920. Set the minimum duration of the sourced audio. See
  2921. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  2922. for the accepted syntax.
  2923. Note that the resulting duration may be greater than the specified duration,
  2924. as the generated audio is always cut at the end of a complete frame.
  2925. If not specified, or the expressed duration is negative, the audio is
  2926. supposed to be generated forever.
  2927. Only used if plugin have zero inputs.
  2928. @end table
  2929. @subsection Examples
  2930. @itemize
  2931. @item
  2932. List all available plugins within amp (LADSPA example plugin) library:
  2933. @example
  2934. ladspa=file=amp
  2935. @end example
  2936. @item
  2937. List all available controls and their valid ranges for @code{vcf_notch}
  2938. plugin from @code{VCF} library:
  2939. @example
  2940. ladspa=f=vcf:p=vcf_notch:c=help
  2941. @end example
  2942. @item
  2943. Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
  2944. plugin library:
  2945. @example
  2946. ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
  2947. @end example
  2948. @item
  2949. Add reverberation to the audio using TAP-plugins
  2950. (Tom's Audio Processing plugins):
  2951. @example
  2952. ladspa=file=tap_reverb:tap_reverb
  2953. @end example
  2954. @item
  2955. Generate white noise, with 0.2 amplitude:
  2956. @example
  2957. ladspa=file=cmt:noise_source_white:c=c0=.2
  2958. @end example
  2959. @item
  2960. Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
  2961. @code{C* Audio Plugin Suite} (CAPS) library:
  2962. @example
  2963. ladspa=file=caps:Click:c=c1=20'
  2964. @end example
  2965. @item
  2966. Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
  2967. @example
  2968. ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
  2969. @end example
  2970. @item
  2971. Increase volume by 20dB using fast lookahead limiter from Steve Harris
  2972. @code{SWH Plugins} collection:
  2973. @example
  2974. ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
  2975. @end example
  2976. @item
  2977. Attenuate low frequencies using Multiband EQ from Steve Harris
  2978. @code{SWH Plugins} collection:
  2979. @example
  2980. ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
  2981. @end example
  2982. @item
  2983. Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
  2984. (CAPS) library:
  2985. @example
  2986. ladspa=caps:Narrower
  2987. @end example
  2988. @item
  2989. Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
  2990. @example
  2991. ladspa=caps:White:.2
  2992. @end example
  2993. @item
  2994. Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
  2995. @example
  2996. ladspa=caps:Fractal:c=c1=1
  2997. @end example
  2998. @item
  2999. Dynamic volume normalization using @code{VLevel} plugin:
  3000. @example
  3001. ladspa=vlevel-ladspa:vlevel_mono
  3002. @end example
  3003. @end itemize
  3004. @subsection Commands
  3005. This filter supports the following commands:
  3006. @table @option
  3007. @item cN
  3008. Modify the @var{N}-th control value.
  3009. If the specified value is not valid, it is ignored and prior one is kept.
  3010. @end table
  3011. @section loudnorm
  3012. EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
  3013. Support for both single pass (livestreams, files) and double pass (files) modes.
  3014. This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
  3015. the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
  3016. Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
  3017. The filter accepts the following options:
  3018. @table @option
  3019. @item I, i
  3020. Set integrated loudness target.
  3021. Range is -70.0 - -5.0. Default value is -24.0.
  3022. @item LRA, lra
  3023. Set loudness range target.
  3024. Range is 1.0 - 20.0. Default value is 7.0.
  3025. @item TP, tp
  3026. Set maximum true peak.
  3027. Range is -9.0 - +0.0. Default value is -2.0.
  3028. @item measured_I, measured_i
  3029. Measured IL of input file.
  3030. Range is -99.0 - +0.0.
  3031. @item measured_LRA, measured_lra
  3032. Measured LRA of input file.
  3033. Range is 0.0 - 99.0.
  3034. @item measured_TP, measured_tp
  3035. Measured true peak of input file.
  3036. Range is -99.0 - +99.0.
  3037. @item measured_thresh
  3038. Measured threshold of input file.
  3039. Range is -99.0 - +0.0.
  3040. @item offset
  3041. Set offset gain. Gain is applied before the true-peak limiter.
  3042. Range is -99.0 - +99.0. Default is +0.0.
  3043. @item linear
  3044. Normalize linearly if possible.
  3045. measured_I, measured_LRA, measured_TP, and measured_thresh must also
  3046. to be specified in order to use this mode.
  3047. Options are true or false. Default is true.
  3048. @item dual_mono
  3049. Treat mono input files as "dual-mono". If a mono file is intended for playback
  3050. on a stereo system, its EBU R128 measurement will be perceptually incorrect.
  3051. If set to @code{true}, this option will compensate for this effect.
  3052. Multi-channel input files are not affected by this option.
  3053. Options are true or false. Default is false.
  3054. @item print_format
  3055. Set print format for stats. Options are summary, json, or none.
  3056. Default value is none.
  3057. @end table
  3058. @section lowpass
  3059. Apply a low-pass filter with 3dB point frequency.
  3060. The filter can be either single-pole or double-pole (the default).
  3061. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  3062. The filter accepts the following options:
  3063. @table @option
  3064. @item frequency, f
  3065. Set frequency in Hz. Default is 500.
  3066. @item poles, p
  3067. Set number of poles. Default is 2.
  3068. @item width_type, t
  3069. Set method to specify band-width of filter.
  3070. @table @option
  3071. @item h
  3072. Hz
  3073. @item q
  3074. Q-Factor
  3075. @item o
  3076. octave
  3077. @item s
  3078. slope
  3079. @item k
  3080. kHz
  3081. @end table
  3082. @item width, w
  3083. Specify the band-width of a filter in width_type units.
  3084. Applies only to double-pole filter.
  3085. The default is 0.707q and gives a Butterworth response.
  3086. @item channels, c
  3087. Specify which channels to filter, by default all available are filtered.
  3088. @end table
  3089. @subsection Examples
  3090. @itemize
  3091. @item
  3092. Lowpass only LFE channel, it LFE is not present it does nothing:
  3093. @example
  3094. lowpass=c=LFE
  3095. @end example
  3096. @end itemize
  3097. @subsection Commands
  3098. This filter supports the following commands:
  3099. @table @option
  3100. @item frequency, f
  3101. Change lowpass frequency.
  3102. Syntax for the command is : "@var{frequency}"
  3103. @item width_type, t
  3104. Change lowpass width_type.
  3105. Syntax for the command is : "@var{width_type}"
  3106. @item width, w
  3107. Change lowpass width.
  3108. Syntax for the command is : "@var{width}"
  3109. @end table
  3110. @section lv2
  3111. Load a LV2 (LADSPA Version 2) plugin.
  3112. To enable compilation of this filter you need to configure FFmpeg with
  3113. @code{--enable-lv2}.
  3114. @table @option
  3115. @item plugin, p
  3116. Specifies the plugin URI. You may need to escape ':'.
  3117. @item controls, c
  3118. Set the '|' separated list of controls which are zero or more floating point
  3119. values that determine the behavior of the loaded plugin (for example delay,
  3120. threshold or gain).
  3121. If @option{controls} is set to @code{help}, all available controls and
  3122. their valid ranges are printed.
  3123. @item sample_rate, s
  3124. Specify the sample rate, default to 44100. Only used if plugin have
  3125. zero inputs.
  3126. @item nb_samples, n
  3127. Set the number of samples per channel per each output frame, default
  3128. is 1024. Only used if plugin have zero inputs.
  3129. @item duration, d
  3130. Set the minimum duration of the sourced audio. See
  3131. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  3132. for the accepted syntax.
  3133. Note that the resulting duration may be greater than the specified duration,
  3134. as the generated audio is always cut at the end of a complete frame.
  3135. If not specified, or the expressed duration is negative, the audio is
  3136. supposed to be generated forever.
  3137. Only used if plugin have zero inputs.
  3138. @end table
  3139. @subsection Examples
  3140. @itemize
  3141. @item
  3142. Apply bass enhancer plugin from Calf:
  3143. @example
  3144. lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
  3145. @end example
  3146. @item
  3147. Apply vinyl plugin from Calf:
  3148. @example
  3149. lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
  3150. @end example
  3151. @item
  3152. Apply bit crusher plugin from ArtyFX:
  3153. @example
  3154. lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
  3155. @end example
  3156. @end itemize
  3157. @section mcompand
  3158. Multiband Compress or expand the audio's dynamic range.
  3159. The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
  3160. This is akin to the crossover of a loudspeaker, and results in flat frequency
  3161. response when absent compander action.
  3162. It accepts the following parameters:
  3163. @table @option
  3164. @item args
  3165. This option syntax is:
  3166. attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
  3167. For explanation of each item refer to compand filter documentation.
  3168. @end table
  3169. @anchor{pan}
  3170. @section pan
  3171. Mix channels with specific gain levels. The filter accepts the output
  3172. channel layout followed by a set of channels definitions.
  3173. This filter is also designed to efficiently remap the channels of an audio
  3174. stream.
  3175. The filter accepts parameters of the form:
  3176. "@var{l}|@var{outdef}|@var{outdef}|..."
  3177. @table @option
  3178. @item l
  3179. output channel layout or number of channels
  3180. @item outdef
  3181. output channel specification, of the form:
  3182. "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
  3183. @item out_name
  3184. output channel to define, either a channel name (FL, FR, etc.) or a channel
  3185. number (c0, c1, etc.)
  3186. @item gain
  3187. multiplicative coefficient for the channel, 1 leaving the volume unchanged
  3188. @item in_name
  3189. input channel to use, see out_name for details; it is not possible to mix
  3190. named and numbered input channels
  3191. @end table
  3192. If the `=' in a channel specification is replaced by `<', then the gains for
  3193. that specification will be renormalized so that the total is 1, thus
  3194. avoiding clipping noise.
  3195. @subsection Mixing examples
  3196. For example, if you want to down-mix from stereo to mono, but with a bigger
  3197. factor for the left channel:
  3198. @example
  3199. pan=1c|c0=0.9*c0+0.1*c1
  3200. @end example
  3201. A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
  3202. 7-channels surround:
  3203. @example
  3204. pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
  3205. @end example
  3206. Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
  3207. that should be preferred (see "-ac" option) unless you have very specific
  3208. needs.
  3209. @subsection Remapping examples
  3210. The channel remapping will be effective if, and only if:
  3211. @itemize
  3212. @item gain coefficients are zeroes or ones,
  3213. @item only one input per channel output,
  3214. @end itemize
  3215. If all these conditions are satisfied, the filter will notify the user ("Pure
  3216. channel mapping detected"), and use an optimized and lossless method to do the
  3217. remapping.
  3218. For example, if you have a 5.1 source and want a stereo audio stream by
  3219. dropping the extra channels:
  3220. @example
  3221. pan="stereo| c0=FL | c1=FR"
  3222. @end example
  3223. Given the same source, you can also switch front left and front right channels
  3224. and keep the input channel layout:
  3225. @example
  3226. pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
  3227. @end example
  3228. If the input is a stereo audio stream, you can mute the front left channel (and
  3229. still keep the stereo channel layout) with:
  3230. @example
  3231. pan="stereo|c1=c1"
  3232. @end example
  3233. Still with a stereo audio stream input, you can copy the right channel in both
  3234. front left and right:
  3235. @example
  3236. pan="stereo| c0=FR | c1=FR"
  3237. @end example
  3238. @section replaygain
  3239. ReplayGain scanner filter. This filter takes an audio stream as an input and
  3240. outputs it unchanged.
  3241. At end of filtering it displays @code{track_gain} and @code{track_peak}.
  3242. @section resample
  3243. Convert the audio sample format, sample rate and channel layout. It is
  3244. not meant to be used directly.
  3245. @section rubberband
  3246. Apply time-stretching and pitch-shifting with librubberband.
  3247. To enable compilation of this filter, you need to configure FFmpeg with
  3248. @code{--enable-librubberband}.
  3249. The filter accepts the following options:
  3250. @table @option
  3251. @item tempo
  3252. Set tempo scale factor.
  3253. @item pitch
  3254. Set pitch scale factor.
  3255. @item transients
  3256. Set transients detector.
  3257. Possible values are:
  3258. @table @var
  3259. @item crisp
  3260. @item mixed
  3261. @item smooth
  3262. @end table
  3263. @item detector
  3264. Set detector.
  3265. Possible values are:
  3266. @table @var
  3267. @item compound
  3268. @item percussive
  3269. @item soft
  3270. @end table
  3271. @item phase
  3272. Set phase.
  3273. Possible values are:
  3274. @table @var
  3275. @item laminar
  3276. @item independent
  3277. @end table
  3278. @item window
  3279. Set processing window size.
  3280. Possible values are:
  3281. @table @var
  3282. @item standard
  3283. @item short
  3284. @item long
  3285. @end table
  3286. @item smoothing
  3287. Set smoothing.
  3288. Possible values are:
  3289. @table @var
  3290. @item off
  3291. @item on
  3292. @end table
  3293. @item formant
  3294. Enable formant preservation when shift pitching.
  3295. Possible values are:
  3296. @table @var
  3297. @item shifted
  3298. @item preserved
  3299. @end table
  3300. @item pitchq
  3301. Set pitch quality.
  3302. Possible values are:
  3303. @table @var
  3304. @item quality
  3305. @item speed
  3306. @item consistency
  3307. @end table
  3308. @item channels
  3309. Set channels.
  3310. Possible values are:
  3311. @table @var
  3312. @item apart
  3313. @item together
  3314. @end table
  3315. @end table
  3316. @section sidechaincompress
  3317. This filter acts like normal compressor but has the ability to compress
  3318. detected signal using second input signal.
  3319. It needs two input streams and returns one output stream.
  3320. First input stream will be processed depending on second stream signal.
  3321. The filtered signal then can be filtered with other filters in later stages of
  3322. processing. See @ref{pan} and @ref{amerge} filter.
  3323. The filter accepts the following options:
  3324. @table @option
  3325. @item level_in
  3326. Set input gain. Default is 1. Range is between 0.015625 and 64.
  3327. @item mode
  3328. Set mode of compressor operation. Can be @code{upward} or @code{downward}.
  3329. Default is @code{downward}.
  3330. @item threshold
  3331. If a signal of second stream raises above this level it will affect the gain
  3332. reduction of first stream.
  3333. By default is 0.125. Range is between 0.00097563 and 1.
  3334. @item ratio
  3335. Set a ratio about which the signal is reduced. 1:2 means that if the level
  3336. raised 4dB above the threshold, it will be only 2dB above after the reduction.
  3337. Default is 2. Range is between 1 and 20.
  3338. @item attack
  3339. Amount of milliseconds the signal has to rise above the threshold before gain
  3340. reduction starts. Default is 20. Range is between 0.01 and 2000.
  3341. @item release
  3342. Amount of milliseconds the signal has to fall below the threshold before
  3343. reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
  3344. @item makeup
  3345. Set the amount by how much signal will be amplified after processing.
  3346. Default is 1. Range is from 1 to 64.
  3347. @item knee
  3348. Curve the sharp knee around the threshold to enter gain reduction more softly.
  3349. Default is 2.82843. Range is between 1 and 8.
  3350. @item link
  3351. Choose if the @code{average} level between all channels of side-chain stream
  3352. or the louder(@code{maximum}) channel of side-chain stream affects the
  3353. reduction. Default is @code{average}.
  3354. @item detection
  3355. Should the exact signal be taken in case of @code{peak} or an RMS one in case
  3356. of @code{rms}. Default is @code{rms} which is mainly smoother.
  3357. @item level_sc
  3358. Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
  3359. @item mix
  3360. How much to use compressed signal in output. Default is 1.
  3361. Range is between 0 and 1.
  3362. @end table
  3363. @subsection Examples
  3364. @itemize
  3365. @item
  3366. Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
  3367. depending on the signal of 2nd input and later compressed signal to be
  3368. merged with 2nd input:
  3369. @example
  3370. ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
  3371. @end example
  3372. @end itemize
  3373. @section sidechaingate
  3374. A sidechain gate acts like a normal (wideband) gate but has the ability to
  3375. filter the detected signal before sending it to the gain reduction stage.
  3376. Normally a gate uses the full range signal to detect a level above the
  3377. threshold.
  3378. For example: If you cut all lower frequencies from your sidechain signal
  3379. the gate will decrease the volume of your track only if not enough highs
  3380. appear. With this technique you are able to reduce the resonation of a
  3381. natural drum or remove "rumbling" of muted strokes from a heavily distorted
  3382. guitar.
  3383. It needs two input streams and returns one output stream.
  3384. First input stream will be processed depending on second stream signal.
  3385. The filter accepts the following options:
  3386. @table @option
  3387. @item level_in
  3388. Set input level before filtering.
  3389. Default is 1. Allowed range is from 0.015625 to 64.
  3390. @item mode
  3391. Set the mode of operation. Can be @code{upward} or @code{downward}.
  3392. Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
  3393. will be amplified, expanding dynamic range in upward direction.
  3394. Otherwise, in case of @code{downward} lower parts of signal will be reduced.
  3395. @item range
  3396. Set the level of gain reduction when the signal is below the threshold.
  3397. Default is 0.06125. Allowed range is from 0 to 1.
  3398. Setting this to 0 disables reduction and then filter behaves like expander.
  3399. @item threshold
  3400. If a signal rises above this level the gain reduction is released.
  3401. Default is 0.125. Allowed range is from 0 to 1.
  3402. @item ratio
  3403. Set a ratio about which the signal is reduced.
  3404. Default is 2. Allowed range is from 1 to 9000.
  3405. @item attack
  3406. Amount of milliseconds the signal has to rise above the threshold before gain
  3407. reduction stops.
  3408. Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
  3409. @item release
  3410. Amount of milliseconds the signal has to fall below the threshold before the
  3411. reduction is increased again. Default is 250 milliseconds.
  3412. Allowed range is from 0.01 to 9000.
  3413. @item makeup
  3414. Set amount of amplification of signal after processing.
  3415. Default is 1. Allowed range is from 1 to 64.
  3416. @item knee
  3417. Curve the sharp knee around the threshold to enter gain reduction more softly.
  3418. Default is 2.828427125. Allowed range is from 1 to 8.
  3419. @item detection
  3420. Choose if exact signal should be taken for detection or an RMS like one.
  3421. Default is rms. Can be peak or rms.
  3422. @item link
  3423. Choose if the average level between all channels or the louder channel affects
  3424. the reduction.
  3425. Default is average. Can be average or maximum.
  3426. @item level_sc
  3427. Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
  3428. @end table
  3429. @section silencedetect
  3430. Detect silence in an audio stream.
  3431. This filter logs a message when it detects that the input audio volume is less
  3432. or equal to a noise tolerance value for a duration greater or equal to the
  3433. minimum detected noise duration.
  3434. The printed times and duration are expressed in seconds.
  3435. The filter accepts the following options:
  3436. @table @option
  3437. @item noise, n
  3438. Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
  3439. specified value) or amplitude ratio. Default is -60dB, or 0.001.
  3440. @item duration, d
  3441. Set silence duration until notification (default is 2 seconds).
  3442. @item mono, m
  3443. Process each channel separately, instead of combined. By default is disabled.
  3444. @end table
  3445. @subsection Examples
  3446. @itemize
  3447. @item
  3448. Detect 5 seconds of silence with -50dB noise tolerance:
  3449. @example
  3450. silencedetect=n=-50dB:d=5
  3451. @end example
  3452. @item
  3453. Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
  3454. tolerance in @file{silence.mp3}:
  3455. @example
  3456. ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
  3457. @end example
  3458. @end itemize
  3459. @section silenceremove
  3460. Remove silence from the beginning, middle or end of the audio.
  3461. The filter accepts the following options:
  3462. @table @option
  3463. @item start_periods
  3464. This value is used to indicate if audio should be trimmed at beginning of
  3465. the audio. A value of zero indicates no silence should be trimmed from the
  3466. beginning. When specifying a non-zero value, it trims audio up until it
  3467. finds non-silence. Normally, when trimming silence from beginning of audio
  3468. the @var{start_periods} will be @code{1} but it can be increased to higher
  3469. values to trim all audio up to specific count of non-silence periods.
  3470. Default value is @code{0}.
  3471. @item start_duration
  3472. Specify the amount of time that non-silence must be detected before it stops
  3473. trimming audio. By increasing the duration, bursts of noises can be treated
  3474. as silence and trimmed off. Default value is @code{0}.
  3475. @item start_threshold
  3476. This indicates what sample value should be treated as silence. For digital
  3477. audio, a value of @code{0} may be fine but for audio recorded from analog,
  3478. you may wish to increase the value to account for background noise.
  3479. Can be specified in dB (in case "dB" is appended to the specified value)
  3480. or amplitude ratio. Default value is @code{0}.
  3481. @item start_silence
  3482. Specify max duration of silence at beginning that will be kept after
  3483. trimming. Default is 0, which is equal to trimming all samples detected
  3484. as silence.
  3485. @item start_mode
  3486. Specify mode of detection of silence end in start of multi-channel audio.
  3487. Can be @var{any} or @var{all}. Default is @var{any}.
  3488. With @var{any}, any sample that is detected as non-silence will cause
  3489. stopped trimming of silence.
  3490. With @var{all}, only if all channels are detected as non-silence will cause
  3491. stopped trimming of silence.
  3492. @item stop_periods
  3493. Set the count for trimming silence from the end of audio.
  3494. To remove silence from the middle of a file, specify a @var{stop_periods}
  3495. that is negative. This value is then treated as a positive value and is
  3496. used to indicate the effect should restart processing as specified by
  3497. @var{start_periods}, making it suitable for removing periods of silence
  3498. in the middle of the audio.
  3499. Default value is @code{0}.
  3500. @item stop_duration
  3501. Specify a duration of silence that must exist before audio is not copied any
  3502. more. By specifying a higher duration, silence that is wanted can be left in
  3503. the audio.
  3504. Default value is @code{0}.
  3505. @item stop_threshold
  3506. This is the same as @option{start_threshold} but for trimming silence from
  3507. the end of audio.
  3508. Can be specified in dB (in case "dB" is appended to the specified value)
  3509. or amplitude ratio. Default value is @code{0}.
  3510. @item stop_silence
  3511. Specify max duration of silence at end that will be kept after
  3512. trimming. Default is 0, which is equal to trimming all samples detected
  3513. as silence.
  3514. @item stop_mode
  3515. Specify mode of detection of silence start in end of multi-channel audio.
  3516. Can be @var{any} or @var{all}. Default is @var{any}.
  3517. With @var{any}, any sample that is detected as non-silence will cause
  3518. stopped trimming of silence.
  3519. With @var{all}, only if all channels are detected as non-silence will cause
  3520. stopped trimming of silence.
  3521. @item detection
  3522. Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
  3523. and works better with digital silence which is exactly 0.
  3524. Default value is @code{rms}.
  3525. @item window
  3526. Set duration in number of seconds used to calculate size of window in number
  3527. of samples for detecting silence.
  3528. Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
  3529. @end table
  3530. @subsection Examples
  3531. @itemize
  3532. @item
  3533. The following example shows how this filter can be used to start a recording
  3534. that does not contain the delay at the start which usually occurs between
  3535. pressing the record button and the start of the performance:
  3536. @example
  3537. silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
  3538. @end example
  3539. @item
  3540. Trim all silence encountered from beginning to end where there is more than 1
  3541. second of silence in audio:
  3542. @example
  3543. silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
  3544. @end example
  3545. @end itemize
  3546. @section sofalizer
  3547. SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
  3548. loudspeakers around the user for binaural listening via headphones (audio
  3549. formats up to 9 channels supported).
  3550. The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
  3551. SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
  3552. Austrian Academy of Sciences.
  3553. To enable compilation of this filter you need to configure FFmpeg with
  3554. @code{--enable-libmysofa}.
  3555. The filter accepts the following options:
  3556. @table @option
  3557. @item sofa
  3558. Set the SOFA file used for rendering.
  3559. @item gain
  3560. Set gain applied to audio. Value is in dB. Default is 0.
  3561. @item rotation
  3562. Set rotation of virtual loudspeakers in deg. Default is 0.
  3563. @item elevation
  3564. Set elevation of virtual speakers in deg. Default is 0.
  3565. @item radius
  3566. Set distance in meters between loudspeakers and the listener with near-field
  3567. HRTFs. Default is 1.
  3568. @item type
  3569. Set processing type. Can be @var{time} or @var{freq}. @var{time} is
  3570. processing audio in time domain which is slow.
  3571. @var{freq} is processing audio in frequency domain which is fast.
  3572. Default is @var{freq}.
  3573. @item speakers
  3574. Set custom positions of virtual loudspeakers. Syntax for this option is:
  3575. <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
  3576. Each virtual loudspeaker is described with short channel name following with
  3577. azimuth and elevation in degrees.
  3578. Each virtual loudspeaker description is separated by '|'.
  3579. For example to override front left and front right channel positions use:
  3580. 'speakers=FL 45 15|FR 345 15'.
  3581. Descriptions with unrecognised channel names are ignored.
  3582. @item lfegain
  3583. Set custom gain for LFE channels. Value is in dB. Default is 0.
  3584. @item framesize
  3585. Set custom frame size in number of samples. Default is 1024.
  3586. Allowed range is from 1024 to 96000. Only used if option @samp{type}
  3587. is set to @var{freq}.
  3588. @item normalize
  3589. Should all IRs be normalized upon importing SOFA file.
  3590. By default is enabled.
  3591. @item interpolate
  3592. Should nearest IRs be interpolated with neighbor IRs if exact position
  3593. does not match. By default is disabled.
  3594. @item minphase
  3595. Minphase all IRs upon loading of SOFA file. By default is disabled.
  3596. @item anglestep
  3597. Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
  3598. @item radstep
  3599. Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
  3600. @end table
  3601. @subsection Examples
  3602. @itemize
  3603. @item
  3604. Using ClubFritz6 sofa file:
  3605. @example
  3606. sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
  3607. @end example
  3608. @item
  3609. Using ClubFritz12 sofa file and bigger radius with small rotation:
  3610. @example
  3611. sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
  3612. @end example
  3613. @item
  3614. Similar as above but with custom speaker positions for front left, front right, back left and back right
  3615. and also with custom gain:
  3616. @example
  3617. "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
  3618. @end example
  3619. @end itemize
  3620. @section stereotools
  3621. This filter has some handy utilities to manage stereo signals, for converting
  3622. M/S stereo recordings to L/R signal while having control over the parameters
  3623. or spreading the stereo image of master track.
  3624. The filter accepts the following options:
  3625. @table @option
  3626. @item level_in
  3627. Set input level before filtering for both channels. Defaults is 1.
  3628. Allowed range is from 0.015625 to 64.
  3629. @item level_out
  3630. Set output level after filtering for both channels. Defaults is 1.
  3631. Allowed range is from 0.015625 to 64.
  3632. @item balance_in
  3633. Set input balance between both channels. Default is 0.
  3634. Allowed range is from -1 to 1.
  3635. @item balance_out
  3636. Set output balance between both channels. Default is 0.
  3637. Allowed range is from -1 to 1.
  3638. @item softclip
  3639. Enable softclipping. Results in analog distortion instead of harsh digital 0dB
  3640. clipping. Disabled by default.
  3641. @item mutel
  3642. Mute the left channel. Disabled by default.
  3643. @item muter
  3644. Mute the right channel. Disabled by default.
  3645. @item phasel
  3646. Change the phase of the left channel. Disabled by default.
  3647. @item phaser
  3648. Change the phase of the right channel. Disabled by default.
  3649. @item mode
  3650. Set stereo mode. Available values are:
  3651. @table @samp
  3652. @item lr>lr
  3653. Left/Right to Left/Right, this is default.
  3654. @item lr>ms
  3655. Left/Right to Mid/Side.
  3656. @item ms>lr
  3657. Mid/Side to Left/Right.
  3658. @item lr>ll
  3659. Left/Right to Left/Left.
  3660. @item lr>rr
  3661. Left/Right to Right/Right.
  3662. @item lr>l+r
  3663. Left/Right to Left + Right.
  3664. @item lr>rl
  3665. Left/Right to Right/Left.
  3666. @item ms>ll
  3667. Mid/Side to Left/Left.
  3668. @item ms>rr
  3669. Mid/Side to Right/Right.
  3670. @end table
  3671. @item slev
  3672. Set level of side signal. Default is 1.
  3673. Allowed range is from 0.015625 to 64.
  3674. @item sbal
  3675. Set balance of side signal. Default is 0.
  3676. Allowed range is from -1 to 1.
  3677. @item mlev
  3678. Set level of the middle signal. Default is 1.
  3679. Allowed range is from 0.015625 to 64.
  3680. @item mpan
  3681. Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
  3682. @item base
  3683. Set stereo base between mono and inversed channels. Default is 0.
  3684. Allowed range is from -1 to 1.
  3685. @item delay
  3686. Set delay in milliseconds how much to delay left from right channel and
  3687. vice versa. Default is 0. Allowed range is from -20 to 20.
  3688. @item sclevel
  3689. Set S/C level. Default is 1. Allowed range is from 1 to 100.
  3690. @item phase
  3691. Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
  3692. @item bmode_in, bmode_out
  3693. Set balance mode for balance_in/balance_out option.
  3694. Can be one of the following:
  3695. @table @samp
  3696. @item balance
  3697. Classic balance mode. Attenuate one channel at time.
  3698. Gain is raised up to 1.
  3699. @item amplitude
  3700. Similar as classic mode above but gain is raised up to 2.
  3701. @item power
  3702. Equal power distribution, from -6dB to +6dB range.
  3703. @end table
  3704. @end table
  3705. @subsection Examples
  3706. @itemize
  3707. @item
  3708. Apply karaoke like effect:
  3709. @example
  3710. stereotools=mlev=0.015625
  3711. @end example
  3712. @item
  3713. Convert M/S signal to L/R:
  3714. @example
  3715. "stereotools=mode=ms>lr"
  3716. @end example
  3717. @end itemize
  3718. @section stereowiden
  3719. This filter enhance the stereo effect by suppressing signal common to both
  3720. channels and by delaying the signal of left into right and vice versa,
  3721. thereby widening the stereo effect.
  3722. The filter accepts the following options:
  3723. @table @option
  3724. @item delay
  3725. Time in milliseconds of the delay of left signal into right and vice versa.
  3726. Default is 20 milliseconds.
  3727. @item feedback
  3728. Amount of gain in delayed signal into right and vice versa. Gives a delay
  3729. effect of left signal in right output and vice versa which gives widening
  3730. effect. Default is 0.3.
  3731. @item crossfeed
  3732. Cross feed of left into right with inverted phase. This helps in suppressing
  3733. the mono. If the value is 1 it will cancel all the signal common to both
  3734. channels. Default is 0.3.
  3735. @item drymix
  3736. Set level of input signal of original channel. Default is 0.8.
  3737. @end table
  3738. @section superequalizer
  3739. Apply 18 band equalizer.
  3740. The filter accepts the following options:
  3741. @table @option
  3742. @item 1b
  3743. Set 65Hz band gain.
  3744. @item 2b
  3745. Set 92Hz band gain.
  3746. @item 3b
  3747. Set 131Hz band gain.
  3748. @item 4b
  3749. Set 185Hz band gain.
  3750. @item 5b
  3751. Set 262Hz band gain.
  3752. @item 6b
  3753. Set 370Hz band gain.
  3754. @item 7b
  3755. Set 523Hz band gain.
  3756. @item 8b
  3757. Set 740Hz band gain.
  3758. @item 9b
  3759. Set 1047Hz band gain.
  3760. @item 10b
  3761. Set 1480Hz band gain.
  3762. @item 11b
  3763. Set 2093Hz band gain.
  3764. @item 12b
  3765. Set 2960Hz band gain.
  3766. @item 13b
  3767. Set 4186Hz band gain.
  3768. @item 14b
  3769. Set 5920Hz band gain.
  3770. @item 15b
  3771. Set 8372Hz band gain.
  3772. @item 16b
  3773. Set 11840Hz band gain.
  3774. @item 17b
  3775. Set 16744Hz band gain.
  3776. @item 18b
  3777. Set 20000Hz band gain.
  3778. @end table
  3779. @section surround
  3780. Apply audio surround upmix filter.
  3781. This filter allows to produce multichannel output from audio stream.
  3782. The filter accepts the following options:
  3783. @table @option
  3784. @item chl_out
  3785. Set output channel layout. By default, this is @var{5.1}.
  3786. See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  3787. for the required syntax.
  3788. @item chl_in
  3789. Set input channel layout. By default, this is @var{stereo}.
  3790. See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  3791. for the required syntax.
  3792. @item level_in
  3793. Set input volume level. By default, this is @var{1}.
  3794. @item level_out
  3795. Set output volume level. By default, this is @var{1}.
  3796. @item lfe
  3797. Enable LFE channel output if output channel layout has it. By default, this is enabled.
  3798. @item lfe_low
  3799. Set LFE low cut off frequency. By default, this is @var{128} Hz.
  3800. @item lfe_high
  3801. Set LFE high cut off frequency. By default, this is @var{256} Hz.
  3802. @item lfe_mode
  3803. Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
  3804. In @var{add} mode, LFE channel is created from input audio and added to output.
  3805. In @var{sub} mode, LFE channel is created from input audio and added to output but
  3806. also all non-LFE output channels are subtracted with output LFE channel.
  3807. @item angle
  3808. Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
  3809. Default is @var{90}.
  3810. @item fc_in
  3811. Set front center input volume. By default, this is @var{1}.
  3812. @item fc_out
  3813. Set front center output volume. By default, this is @var{1}.
  3814. @item fl_in
  3815. Set front left input volume. By default, this is @var{1}.
  3816. @item fl_out
  3817. Set front left output volume. By default, this is @var{1}.
  3818. @item fr_in
  3819. Set front right input volume. By default, this is @var{1}.
  3820. @item fr_out
  3821. Set front right output volume. By default, this is @var{1}.
  3822. @item sl_in
  3823. Set side left input volume. By default, this is @var{1}.
  3824. @item sl_out
  3825. Set side left output volume. By default, this is @var{1}.
  3826. @item sr_in
  3827. Set side right input volume. By default, this is @var{1}.
  3828. @item sr_out
  3829. Set side right output volume. By default, this is @var{1}.
  3830. @item bl_in
  3831. Set back left input volume. By default, this is @var{1}.
  3832. @item bl_out
  3833. Set back left output volume. By default, this is @var{1}.
  3834. @item br_in
  3835. Set back right input volume. By default, this is @var{1}.
  3836. @item br_out
  3837. Set back right output volume. By default, this is @var{1}.
  3838. @item bc_in
  3839. Set back center input volume. By default, this is @var{1}.
  3840. @item bc_out
  3841. Set back center output volume. By default, this is @var{1}.
  3842. @item lfe_in
  3843. Set LFE input volume. By default, this is @var{1}.
  3844. @item lfe_out
  3845. Set LFE output volume. By default, this is @var{1}.
  3846. @item allx
  3847. Set spread usage of stereo image across X axis for all channels.
  3848. @item ally
  3849. Set spread usage of stereo image across Y axis for all channels.
  3850. @item fcx, flx, frx, blx, brx, slx, srx, bcx
  3851. Set spread usage of stereo image across X axis for each channel.
  3852. @item fcy, fly, fry, bly, bry, sly, sry, bcy
  3853. Set spread usage of stereo image across Y axis for each channel.
  3854. @item win_size
  3855. Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
  3856. @item win_func
  3857. Set window function.
  3858. It accepts the following values:
  3859. @table @samp
  3860. @item rect
  3861. @item bartlett
  3862. @item hann, hanning
  3863. @item hamming
  3864. @item blackman
  3865. @item welch
  3866. @item flattop
  3867. @item bharris
  3868. @item bnuttall
  3869. @item bhann
  3870. @item sine
  3871. @item nuttall
  3872. @item lanczos
  3873. @item gauss
  3874. @item tukey
  3875. @item dolph
  3876. @item cauchy
  3877. @item parzen
  3878. @item poisson
  3879. @item bohman
  3880. @end table
  3881. Default is @code{hann}.
  3882. @item overlap
  3883. Set window overlap. If set to 1, the recommended overlap for selected
  3884. window function will be picked. Default is @code{0.5}.
  3885. @end table
  3886. @section treble, highshelf
  3887. Boost or cut treble (upper) frequencies of the audio using a two-pole
  3888. shelving filter with a response similar to that of a standard
  3889. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  3890. The filter accepts the following options:
  3891. @table @option
  3892. @item gain, g
  3893. Give the gain at whichever is the lower of ~22 kHz and the
  3894. Nyquist frequency. Its useful range is about -20 (for a large cut)
  3895. to +20 (for a large boost). Beware of clipping when using a positive gain.
  3896. @item frequency, f
  3897. Set the filter's central frequency and so can be used
  3898. to extend or reduce the frequency range to be boosted or cut.
  3899. The default value is @code{3000} Hz.
  3900. @item width_type, t
  3901. Set method to specify band-width of filter.
  3902. @table @option
  3903. @item h
  3904. Hz
  3905. @item q
  3906. Q-Factor
  3907. @item o
  3908. octave
  3909. @item s
  3910. slope
  3911. @item k
  3912. kHz
  3913. @end table
  3914. @item width, w
  3915. Determine how steep is the filter's shelf transition.
  3916. @item channels, c
  3917. Specify which channels to filter, by default all available are filtered.
  3918. @end table
  3919. @subsection Commands
  3920. This filter supports the following commands:
  3921. @table @option
  3922. @item frequency, f
  3923. Change treble frequency.
  3924. Syntax for the command is : "@var{frequency}"
  3925. @item width_type, t
  3926. Change treble width_type.
  3927. Syntax for the command is : "@var{width_type}"
  3928. @item width, w
  3929. Change treble width.
  3930. Syntax for the command is : "@var{width}"
  3931. @item gain, g
  3932. Change treble gain.
  3933. Syntax for the command is : "@var{gain}"
  3934. @end table
  3935. @section tremolo
  3936. Sinusoidal amplitude modulation.
  3937. The filter accepts the following options:
  3938. @table @option
  3939. @item f
  3940. Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
  3941. (20 Hz or lower) will result in a tremolo effect.
  3942. This filter may also be used as a ring modulator by specifying
  3943. a modulation frequency higher than 20 Hz.
  3944. Range is 0.1 - 20000.0. Default value is 5.0 Hz.
  3945. @item d
  3946. Depth of modulation as a percentage. Range is 0.0 - 1.0.
  3947. Default value is 0.5.
  3948. @end table
  3949. @section vibrato
  3950. Sinusoidal phase modulation.
  3951. The filter accepts the following options:
  3952. @table @option
  3953. @item f
  3954. Modulation frequency in Hertz.
  3955. Range is 0.1 - 20000.0. Default value is 5.0 Hz.
  3956. @item d
  3957. Depth of modulation as a percentage. Range is 0.0 - 1.0.
  3958. Default value is 0.5.
  3959. @end table
  3960. @section volume
  3961. Adjust the input audio volume.
  3962. It accepts the following parameters:
  3963. @table @option
  3964. @item volume
  3965. Set audio volume expression.
  3966. Output values are clipped to the maximum value.
  3967. The output audio volume is given by the relation:
  3968. @example
  3969. @var{output_volume} = @var{volume} * @var{input_volume}
  3970. @end example
  3971. The default value for @var{volume} is "1.0".
  3972. @item precision
  3973. This parameter represents the mathematical precision.
  3974. It determines which input sample formats will be allowed, which affects the
  3975. precision of the volume scaling.
  3976. @table @option
  3977. @item fixed
  3978. 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
  3979. @item float
  3980. 32-bit floating-point; this limits input sample format to FLT. (default)
  3981. @item double
  3982. 64-bit floating-point; this limits input sample format to DBL.
  3983. @end table
  3984. @item replaygain
  3985. Choose the behaviour on encountering ReplayGain side data in input frames.
  3986. @table @option
  3987. @item drop
  3988. Remove ReplayGain side data, ignoring its contents (the default).
  3989. @item ignore
  3990. Ignore ReplayGain side data, but leave it in the frame.
  3991. @item track
  3992. Prefer the track gain, if present.
  3993. @item album
  3994. Prefer the album gain, if present.
  3995. @end table
  3996. @item replaygain_preamp
  3997. Pre-amplification gain in dB to apply to the selected replaygain gain.
  3998. Default value for @var{replaygain_preamp} is 0.0.
  3999. @item eval
  4000. Set when the volume expression is evaluated.
  4001. It accepts the following values:
  4002. @table @samp
  4003. @item once
  4004. only evaluate expression once during the filter initialization, or
  4005. when the @samp{volume} command is sent
  4006. @item frame
  4007. evaluate expression for each incoming frame
  4008. @end table
  4009. Default value is @samp{once}.
  4010. @end table
  4011. The volume expression can contain the following parameters.
  4012. @table @option
  4013. @item n
  4014. frame number (starting at zero)
  4015. @item nb_channels
  4016. number of channels
  4017. @item nb_consumed_samples
  4018. number of samples consumed by the filter
  4019. @item nb_samples
  4020. number of samples in the current frame
  4021. @item pos
  4022. original frame position in the file
  4023. @item pts
  4024. frame PTS
  4025. @item sample_rate
  4026. sample rate
  4027. @item startpts
  4028. PTS at start of stream
  4029. @item startt
  4030. time at start of stream
  4031. @item t
  4032. frame time
  4033. @item tb
  4034. timestamp timebase
  4035. @item volume
  4036. last set volume value
  4037. @end table
  4038. Note that when @option{eval} is set to @samp{once} only the
  4039. @var{sample_rate} and @var{tb} variables are available, all other
  4040. variables will evaluate to NAN.
  4041. @subsection Commands
  4042. This filter supports the following commands:
  4043. @table @option
  4044. @item volume
  4045. Modify the volume expression.
  4046. The command accepts the same syntax of the corresponding option.
  4047. If the specified expression is not valid, it is kept at its current
  4048. value.
  4049. @item replaygain_noclip
  4050. Prevent clipping by limiting the gain applied.
  4051. Default value for @var{replaygain_noclip} is 1.
  4052. @end table
  4053. @subsection Examples
  4054. @itemize
  4055. @item
  4056. Halve the input audio volume:
  4057. @example
  4058. volume=volume=0.5
  4059. volume=volume=1/2
  4060. volume=volume=-6.0206dB
  4061. @end example
  4062. In all the above example the named key for @option{volume} can be
  4063. omitted, for example like in:
  4064. @example
  4065. volume=0.5
  4066. @end example
  4067. @item
  4068. Increase input audio power by 6 decibels using fixed-point precision:
  4069. @example
  4070. volume=volume=6dB:precision=fixed
  4071. @end example
  4072. @item
  4073. Fade volume after time 10 with an annihilation period of 5 seconds:
  4074. @example
  4075. volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
  4076. @end example
  4077. @end itemize
  4078. @section volumedetect
  4079. Detect the volume of the input video.
  4080. The filter has no parameters. The input is not modified. Statistics about
  4081. the volume will be printed in the log when the input stream end is reached.
  4082. In particular it will show the mean volume (root mean square), maximum
  4083. volume (on a per-sample basis), and the beginning of a histogram of the
  4084. registered volume values (from the maximum value to a cumulated 1/1000 of
  4085. the samples).
  4086. All volumes are in decibels relative to the maximum PCM value.
  4087. @subsection Examples
  4088. Here is an excerpt of the output:
  4089. @example
  4090. [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
  4091. [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
  4092. [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
  4093. [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
  4094. [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
  4095. [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
  4096. [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
  4097. [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
  4098. [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
  4099. @end example
  4100. It means that:
  4101. @itemize
  4102. @item
  4103. The mean square energy is approximately -27 dB, or 10^-2.7.
  4104. @item
  4105. The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
  4106. @item
  4107. There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
  4108. @end itemize
  4109. In other words, raising the volume by +4 dB does not cause any clipping,
  4110. raising it by +5 dB causes clipping for 6 samples, etc.
  4111. @c man end AUDIO FILTERS
  4112. @chapter Audio Sources
  4113. @c man begin AUDIO SOURCES
  4114. Below is a description of the currently available audio sources.
  4115. @section abuffer
  4116. Buffer audio frames, and make them available to the filter chain.
  4117. This source is mainly intended for a programmatic use, in particular
  4118. through the interface defined in @file{libavfilter/asrc_abuffer.h}.
  4119. It accepts the following parameters:
  4120. @table @option
  4121. @item time_base
  4122. The timebase which will be used for timestamps of submitted frames. It must be
  4123. either a floating-point number or in @var{numerator}/@var{denominator} form.
  4124. @item sample_rate
  4125. The sample rate of the incoming audio buffers.
  4126. @item sample_fmt
  4127. The sample format of the incoming audio buffers.
  4128. Either a sample format name or its corresponding integer representation from
  4129. the enum AVSampleFormat in @file{libavutil/samplefmt.h}
  4130. @item channel_layout
  4131. The channel layout of the incoming audio buffers.
  4132. Either a channel layout name from channel_layout_map in
  4133. @file{libavutil/channel_layout.c} or its corresponding integer representation
  4134. from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
  4135. @item channels
  4136. The number of channels of the incoming audio buffers.
  4137. If both @var{channels} and @var{channel_layout} are specified, then they
  4138. must be consistent.
  4139. @end table
  4140. @subsection Examples
  4141. @example
  4142. abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
  4143. @end example
  4144. will instruct the source to accept planar 16bit signed stereo at 44100Hz.
  4145. Since the sample format with name "s16p" corresponds to the number
  4146. 6 and the "stereo" channel layout corresponds to the value 0x3, this is
  4147. equivalent to:
  4148. @example
  4149. abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
  4150. @end example
  4151. @section aevalsrc
  4152. Generate an audio signal specified by an expression.
  4153. This source accepts in input one or more expressions (one for each
  4154. channel), which are evaluated and used to generate a corresponding
  4155. audio signal.
  4156. This source accepts the following options:
  4157. @table @option
  4158. @item exprs
  4159. Set the '|'-separated expressions list for each separate channel. In case the
  4160. @option{channel_layout} option is not specified, the selected channel layout
  4161. depends on the number of provided expressions. Otherwise the last
  4162. specified expression is applied to the remaining output channels.
  4163. @item channel_layout, c
  4164. Set the channel layout. The number of channels in the specified layout
  4165. must be equal to the number of specified expressions.
  4166. @item duration, d
  4167. Set the minimum duration of the sourced audio. See
  4168. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  4169. for the accepted syntax.
  4170. Note that the resulting duration may be greater than the specified
  4171. duration, as the generated audio is always cut at the end of a
  4172. complete frame.
  4173. If not specified, or the expressed duration is negative, the audio is
  4174. supposed to be generated forever.
  4175. @item nb_samples, n
  4176. Set the number of samples per channel per each output frame,
  4177. default to 1024.
  4178. @item sample_rate, s
  4179. Specify the sample rate, default to 44100.
  4180. @end table
  4181. Each expression in @var{exprs} can contain the following constants:
  4182. @table @option
  4183. @item n
  4184. number of the evaluated sample, starting from 0
  4185. @item t
  4186. time of the evaluated sample expressed in seconds, starting from 0
  4187. @item s
  4188. sample rate
  4189. @end table
  4190. @subsection Examples
  4191. @itemize
  4192. @item
  4193. Generate silence:
  4194. @example
  4195. aevalsrc=0
  4196. @end example
  4197. @item
  4198. Generate a sin signal with frequency of 440 Hz, set sample rate to
  4199. 8000 Hz:
  4200. @example
  4201. aevalsrc="sin(440*2*PI*t):s=8000"
  4202. @end example
  4203. @item
  4204. Generate a two channels signal, specify the channel layout (Front
  4205. Center + Back Center) explicitly:
  4206. @example
  4207. aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
  4208. @end example
  4209. @item
  4210. Generate white noise:
  4211. @example
  4212. aevalsrc="-2+random(0)"
  4213. @end example
  4214. @item
  4215. Generate an amplitude modulated signal:
  4216. @example
  4217. aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
  4218. @end example
  4219. @item
  4220. Generate 2.5 Hz binaural beats on a 360 Hz carrier:
  4221. @example
  4222. aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
  4223. @end example
  4224. @end itemize
  4225. @section anullsrc
  4226. The null audio source, return unprocessed audio frames. It is mainly useful
  4227. as a template and to be employed in analysis / debugging tools, or as
  4228. the source for filters which ignore the input data (for example the sox
  4229. synth filter).
  4230. This source accepts the following options:
  4231. @table @option
  4232. @item channel_layout, cl
  4233. Specifies the channel layout, and can be either an integer or a string
  4234. representing a channel layout. The default value of @var{channel_layout}
  4235. is "stereo".
  4236. Check the channel_layout_map definition in
  4237. @file{libavutil/channel_layout.c} for the mapping between strings and
  4238. channel layout values.
  4239. @item sample_rate, r
  4240. Specifies the sample rate, and defaults to 44100.
  4241. @item nb_samples, n
  4242. Set the number of samples per requested frames.
  4243. @end table
  4244. @subsection Examples
  4245. @itemize
  4246. @item
  4247. Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
  4248. @example
  4249. anullsrc=r=48000:cl=4
  4250. @end example
  4251. @item
  4252. Do the same operation with a more obvious syntax:
  4253. @example
  4254. anullsrc=r=48000:cl=mono
  4255. @end example
  4256. @end itemize
  4257. All the parameters need to be explicitly defined.
  4258. @section flite
  4259. Synthesize a voice utterance using the libflite library.
  4260. To enable compilation of this filter you need to configure FFmpeg with
  4261. @code{--enable-libflite}.
  4262. Note that versions of the flite library prior to 2.0 are not thread-safe.
  4263. The filter accepts the following options:
  4264. @table @option
  4265. @item list_voices
  4266. If set to 1, list the names of the available voices and exit
  4267. immediately. Default value is 0.
  4268. @item nb_samples, n
  4269. Set the maximum number of samples per frame. Default value is 512.
  4270. @item textfile
  4271. Set the filename containing the text to speak.
  4272. @item text
  4273. Set the text to speak.
  4274. @item voice, v
  4275. Set the voice to use for the speech synthesis. Default value is
  4276. @code{kal}. See also the @var{list_voices} option.
  4277. @end table
  4278. @subsection Examples
  4279. @itemize
  4280. @item
  4281. Read from file @file{speech.txt}, and synthesize the text using the
  4282. standard flite voice:
  4283. @example
  4284. flite=textfile=speech.txt
  4285. @end example
  4286. @item
  4287. Read the specified text selecting the @code{slt} voice:
  4288. @example
  4289. flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  4290. @end example
  4291. @item
  4292. Input text to ffmpeg:
  4293. @example
  4294. ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  4295. @end example
  4296. @item
  4297. Make @file{ffplay} speak the specified text, using @code{flite} and
  4298. the @code{lavfi} device:
  4299. @example
  4300. ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
  4301. @end example
  4302. @end itemize
  4303. For more information about libflite, check:
  4304. @url{http://www.festvox.org/flite/}
  4305. @section anoisesrc
  4306. Generate a noise audio signal.
  4307. The filter accepts the following options:
  4308. @table @option
  4309. @item sample_rate, r
  4310. Specify the sample rate. Default value is 48000 Hz.
  4311. @item amplitude, a
  4312. Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
  4313. is 1.0.
  4314. @item duration, d
  4315. Specify the duration of the generated audio stream. Not specifying this option
  4316. results in noise with an infinite length.
  4317. @item color, colour, c
  4318. Specify the color of noise. Available noise colors are white, pink, brown,
  4319. blue and violet. Default color is white.
  4320. @item seed, s
  4321. Specify a value used to seed the PRNG.
  4322. @item nb_samples, n
  4323. Set the number of samples per each output frame, default is 1024.
  4324. @end table
  4325. @subsection Examples
  4326. @itemize
  4327. @item
  4328. Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
  4329. @example
  4330. anoisesrc=d=60:c=pink:r=44100:a=0.5
  4331. @end example
  4332. @end itemize
  4333. @section hilbert
  4334. Generate odd-tap Hilbert transform FIR coefficients.
  4335. The resulting stream can be used with @ref{afir} filter for phase-shifting
  4336. the signal by 90 degrees.
  4337. This is used in many matrix coding schemes and for analytic signal generation.
  4338. The process is often written as a multiplication by i (or j), the imaginary unit.
  4339. The filter accepts the following options:
  4340. @table @option
  4341. @item sample_rate, s
  4342. Set sample rate, default is 44100.
  4343. @item taps, t
  4344. Set length of FIR filter, default is 22051.
  4345. @item nb_samples, n
  4346. Set number of samples per each frame.
  4347. @item win_func, w
  4348. Set window function to be used when generating FIR coefficients.
  4349. @end table
  4350. @section sinc
  4351. Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
  4352. The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
  4353. The filter accepts the following options:
  4354. @table @option
  4355. @item sample_rate, r
  4356. Set sample rate, default is 44100.
  4357. @item nb_samples, n
  4358. Set number of samples per each frame. Default is 1024.
  4359. @item hp
  4360. Set high-pass frequency. Default is 0.
  4361. @item lp
  4362. Set low-pass frequency. Default is 0.
  4363. If high-pass frequency is lower than low-pass frequency and low-pass frequency
  4364. is higher than 0 then filter will create band-pass filter coefficients,
  4365. otherwise band-reject filter coefficients.
  4366. @item phase
  4367. Set filter phase response. Default is 50. Allowed range is from 0 to 100.
  4368. @item beta
  4369. Set Kaiser window beta.
  4370. @item att
  4371. Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
  4372. @item round
  4373. Enable rounding, by default is disabled.
  4374. @item hptaps
  4375. Set number of taps for high-pass filter.
  4376. @item lptaps
  4377. Set number of taps for low-pass filter.
  4378. @end table
  4379. @section sine
  4380. Generate an audio signal made of a sine wave with amplitude 1/8.
  4381. The audio signal is bit-exact.
  4382. The filter accepts the following options:
  4383. @table @option
  4384. @item frequency, f
  4385. Set the carrier frequency. Default is 440 Hz.
  4386. @item beep_factor, b
  4387. Enable a periodic beep every second with frequency @var{beep_factor} times
  4388. the carrier frequency. Default is 0, meaning the beep is disabled.
  4389. @item sample_rate, r
  4390. Specify the sample rate, default is 44100.
  4391. @item duration, d
  4392. Specify the duration of the generated audio stream.
  4393. @item samples_per_frame
  4394. Set the number of samples per output frame.
  4395. The expression can contain the following constants:
  4396. @table @option
  4397. @item n
  4398. The (sequential) number of the output audio frame, starting from 0.
  4399. @item pts
  4400. The PTS (Presentation TimeStamp) of the output audio frame,
  4401. expressed in @var{TB} units.
  4402. @item t
  4403. The PTS of the output audio frame, expressed in seconds.
  4404. @item TB
  4405. The timebase of the output audio frames.
  4406. @end table
  4407. Default is @code{1024}.
  4408. @end table
  4409. @subsection Examples
  4410. @itemize
  4411. @item
  4412. Generate a simple 440 Hz sine wave:
  4413. @example
  4414. sine
  4415. @end example
  4416. @item
  4417. Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
  4418. @example
  4419. sine=220:4:d=5
  4420. sine=f=220:b=4:d=5
  4421. sine=frequency=220:beep_factor=4:duration=5
  4422. @end example
  4423. @item
  4424. Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
  4425. pattern:
  4426. @example
  4427. sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
  4428. @end example
  4429. @end itemize
  4430. @c man end AUDIO SOURCES
  4431. @chapter Audio Sinks
  4432. @c man begin AUDIO SINKS
  4433. Below is a description of the currently available audio sinks.
  4434. @section abuffersink
  4435. Buffer audio frames, and make them available to the end of filter chain.
  4436. This sink is mainly intended for programmatic use, in particular
  4437. through the interface defined in @file{libavfilter/buffersink.h}
  4438. or the options system.
  4439. It accepts a pointer to an AVABufferSinkContext structure, which
  4440. defines the incoming buffers' formats, to be passed as the opaque
  4441. parameter to @code{avfilter_init_filter} for initialization.
  4442. @section anullsink
  4443. Null audio sink; do absolutely nothing with the input audio. It is
  4444. mainly useful as a template and for use in analysis / debugging
  4445. tools.
  4446. @c man end AUDIO SINKS
  4447. @chapter Video Filters
  4448. @c man begin VIDEO FILTERS
  4449. When you configure your FFmpeg build, you can disable any of the
  4450. existing filters using @code{--disable-filters}.
  4451. The configure output will show the video filters included in your
  4452. build.
  4453. Below is a description of the currently available video filters.
  4454. @section alphaextract
  4455. Extract the alpha component from the input as a grayscale video. This
  4456. is especially useful with the @var{alphamerge} filter.
  4457. @section alphamerge
  4458. Add or replace the alpha component of the primary input with the
  4459. grayscale value of a second input. This is intended for use with
  4460. @var{alphaextract} to allow the transmission or storage of frame
  4461. sequences that have alpha in a format that doesn't support an alpha
  4462. channel.
  4463. For example, to reconstruct full frames from a normal YUV-encoded video
  4464. and a separate video created with @var{alphaextract}, you might use:
  4465. @example
  4466. movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
  4467. @end example
  4468. Since this filter is designed for reconstruction, it operates on frame
  4469. sequences without considering timestamps, and terminates when either
  4470. input reaches end of stream. This will cause problems if your encoding
  4471. pipeline drops frames. If you're trying to apply an image as an
  4472. overlay to a video stream, consider the @var{overlay} filter instead.
  4473. @section amplify
  4474. Amplify differences between current pixel and pixels of adjacent frames in
  4475. same pixel location.
  4476. This filter accepts the following options:
  4477. @table @option
  4478. @item radius
  4479. Set frame radius. Default is 2. Allowed range is from 1 to 63.
  4480. For example radius of 3 will instruct filter to calculate average of 7 frames.
  4481. @item factor
  4482. Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
  4483. @item threshold
  4484. Set threshold for difference amplification. Any difference greater or equal to
  4485. this value will not alter source pixel. Default is 10.
  4486. Allowed range is from 0 to 65535.
  4487. @item tolerance
  4488. Set tolerance for difference amplification. Any difference lower to
  4489. this value will not alter source pixel. Default is 0.
  4490. Allowed range is from 0 to 65535.
  4491. @item low
  4492. Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
  4493. This option controls maximum possible value that will decrease source pixel value.
  4494. @item high
  4495. Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
  4496. This option controls maximum possible value that will increase source pixel value.
  4497. @item planes
  4498. Set which planes to filter. Default is all. Allowed range is from 0 to 15.
  4499. @end table
  4500. @section ass
  4501. Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
  4502. and libavformat to work. On the other hand, it is limited to ASS (Advanced
  4503. Substation Alpha) subtitles files.
  4504. This filter accepts the following option in addition to the common options from
  4505. the @ref{subtitles} filter:
  4506. @table @option
  4507. @item shaping
  4508. Set the shaping engine
  4509. Available values are:
  4510. @table @samp
  4511. @item auto
  4512. The default libass shaping engine, which is the best available.
  4513. @item simple
  4514. Fast, font-agnostic shaper that can do only substitutions
  4515. @item complex
  4516. Slower shaper using OpenType for substitutions and positioning
  4517. @end table
  4518. The default is @code{auto}.
  4519. @end table
  4520. @section atadenoise
  4521. Apply an Adaptive Temporal Averaging Denoiser to the video input.
  4522. The filter accepts the following options:
  4523. @table @option
  4524. @item 0a
  4525. Set threshold A for 1st plane. Default is 0.02.
  4526. Valid range is 0 to 0.3.
  4527. @item 0b
  4528. Set threshold B for 1st plane. Default is 0.04.
  4529. Valid range is 0 to 5.
  4530. @item 1a
  4531. Set threshold A for 2nd plane. Default is 0.02.
  4532. Valid range is 0 to 0.3.
  4533. @item 1b
  4534. Set threshold B for 2nd plane. Default is 0.04.
  4535. Valid range is 0 to 5.
  4536. @item 2a
  4537. Set threshold A for 3rd plane. Default is 0.02.
  4538. Valid range is 0 to 0.3.
  4539. @item 2b
  4540. Set threshold B for 3rd plane. Default is 0.04.
  4541. Valid range is 0 to 5.
  4542. Threshold A is designed to react on abrupt changes in the input signal and
  4543. threshold B is designed to react on continuous changes in the input signal.
  4544. @item s
  4545. Set number of frames filter will use for averaging. Default is 9. Must be odd
  4546. number in range [5, 129].
  4547. @item p
  4548. Set what planes of frame filter will use for averaging. Default is all.
  4549. @end table
  4550. @section avgblur
  4551. Apply average blur filter.
  4552. The filter accepts the following options:
  4553. @table @option
  4554. @item sizeX
  4555. Set horizontal radius size.
  4556. @item planes
  4557. Set which planes to filter. By default all planes are filtered.
  4558. @item sizeY
  4559. Set vertical radius size, if zero it will be same as @code{sizeX}.
  4560. Default is @code{0}.
  4561. @end table
  4562. @section bbox
  4563. Compute the bounding box for the non-black pixels in the input frame
  4564. luminance plane.
  4565. This filter computes the bounding box containing all the pixels with a
  4566. luminance value greater than the minimum allowed value.
  4567. The parameters describing the bounding box are printed on the filter
  4568. log.
  4569. The filter accepts the following option:
  4570. @table @option
  4571. @item min_val
  4572. Set the minimal luminance value. Default is @code{16}.
  4573. @end table
  4574. @section bitplanenoise
  4575. Show and measure bit plane noise.
  4576. The filter accepts the following options:
  4577. @table @option
  4578. @item bitplane
  4579. Set which plane to analyze. Default is @code{1}.
  4580. @item filter
  4581. Filter out noisy pixels from @code{bitplane} set above.
  4582. Default is disabled.
  4583. @end table
  4584. @section blackdetect
  4585. Detect video intervals that are (almost) completely black. Can be
  4586. useful to detect chapter transitions, commercials, or invalid
  4587. recordings. Output lines contains the time for the start, end and
  4588. duration of the detected black interval expressed in seconds.
  4589. In order to display the output lines, you need to set the loglevel at
  4590. least to the AV_LOG_INFO value.
  4591. The filter accepts the following options:
  4592. @table @option
  4593. @item black_min_duration, d
  4594. Set the minimum detected black duration expressed in seconds. It must
  4595. be a non-negative floating point number.
  4596. Default value is 2.0.
  4597. @item picture_black_ratio_th, pic_th
  4598. Set the threshold for considering a picture "black".
  4599. Express the minimum value for the ratio:
  4600. @example
  4601. @var{nb_black_pixels} / @var{nb_pixels}
  4602. @end example
  4603. for which a picture is considered black.
  4604. Default value is 0.98.
  4605. @item pixel_black_th, pix_th
  4606. Set the threshold for considering a pixel "black".
  4607. The threshold expresses the maximum pixel luminance value for which a
  4608. pixel is considered "black". The provided value is scaled according to
  4609. the following equation:
  4610. @example
  4611. @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
  4612. @end example
  4613. @var{luminance_range_size} and @var{luminance_minimum_value} depend on
  4614. the input video format, the range is [0-255] for YUV full-range
  4615. formats and [16-235] for YUV non full-range formats.
  4616. Default value is 0.10.
  4617. @end table
  4618. The following example sets the maximum pixel threshold to the minimum
  4619. value, and detects only black intervals of 2 or more seconds:
  4620. @example
  4621. blackdetect=d=2:pix_th=0.00
  4622. @end example
  4623. @section blackframe
  4624. Detect frames that are (almost) completely black. Can be useful to
  4625. detect chapter transitions or commercials. Output lines consist of
  4626. the frame number of the detected frame, the percentage of blackness,
  4627. the position in the file if known or -1 and the timestamp in seconds.
  4628. In order to display the output lines, you need to set the loglevel at
  4629. least to the AV_LOG_INFO value.
  4630. This filter exports frame metadata @code{lavfi.blackframe.pblack}.
  4631. The value represents the percentage of pixels in the picture that
  4632. are below the threshold value.
  4633. It accepts the following parameters:
  4634. @table @option
  4635. @item amount
  4636. The percentage of the pixels that have to be below the threshold; it defaults to
  4637. @code{98}.
  4638. @item threshold, thresh
  4639. The threshold below which a pixel value is considered black; it defaults to
  4640. @code{32}.
  4641. @end table
  4642. @section blend, tblend
  4643. Blend two video frames into each other.
  4644. The @code{blend} filter takes two input streams and outputs one
  4645. stream, the first input is the "top" layer and second input is
  4646. "bottom" layer. By default, the output terminates when the longest input terminates.
  4647. The @code{tblend} (time blend) filter takes two consecutive frames
  4648. from one single stream, and outputs the result obtained by blending
  4649. the new frame on top of the old frame.
  4650. A description of the accepted options follows.
  4651. @table @option
  4652. @item c0_mode
  4653. @item c1_mode
  4654. @item c2_mode
  4655. @item c3_mode
  4656. @item all_mode
  4657. Set blend mode for specific pixel component or all pixel components in case
  4658. of @var{all_mode}. Default value is @code{normal}.
  4659. Available values for component modes are:
  4660. @table @samp
  4661. @item addition
  4662. @item grainmerge
  4663. @item and
  4664. @item average
  4665. @item burn
  4666. @item darken
  4667. @item difference
  4668. @item grainextract
  4669. @item divide
  4670. @item dodge
  4671. @item freeze
  4672. @item exclusion
  4673. @item extremity
  4674. @item glow
  4675. @item hardlight
  4676. @item hardmix
  4677. @item heat
  4678. @item lighten
  4679. @item linearlight
  4680. @item multiply
  4681. @item multiply128
  4682. @item negation
  4683. @item normal
  4684. @item or
  4685. @item overlay
  4686. @item phoenix
  4687. @item pinlight
  4688. @item reflect
  4689. @item screen
  4690. @item softlight
  4691. @item subtract
  4692. @item vividlight
  4693. @item xor
  4694. @end table
  4695. @item c0_opacity
  4696. @item c1_opacity
  4697. @item c2_opacity
  4698. @item c3_opacity
  4699. @item all_opacity
  4700. Set blend opacity for specific pixel component or all pixel components in case
  4701. of @var{all_opacity}. Only used in combination with pixel component blend modes.
  4702. @item c0_expr
  4703. @item c1_expr
  4704. @item c2_expr
  4705. @item c3_expr
  4706. @item all_expr
  4707. Set blend expression for specific pixel component or all pixel components in case
  4708. of @var{all_expr}. Note that related mode options will be ignored if those are set.
  4709. The expressions can use the following variables:
  4710. @table @option
  4711. @item N
  4712. The sequential number of the filtered frame, starting from @code{0}.
  4713. @item X
  4714. @item Y
  4715. the coordinates of the current sample
  4716. @item W
  4717. @item H
  4718. the width and height of currently filtered plane
  4719. @item SW
  4720. @item SH
  4721. Width and height scale for the plane being filtered. It is the
  4722. ratio between the dimensions of the current plane to the luma plane,
  4723. e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
  4724. the luma plane and @code{0.5,0.5} for the chroma planes.
  4725. @item T
  4726. Time of the current frame, expressed in seconds.
  4727. @item TOP, A
  4728. Value of pixel component at current location for first video frame (top layer).
  4729. @item BOTTOM, B
  4730. Value of pixel component at current location for second video frame (bottom layer).
  4731. @end table
  4732. @end table
  4733. The @code{blend} filter also supports the @ref{framesync} options.
  4734. @subsection Examples
  4735. @itemize
  4736. @item
  4737. Apply transition from bottom layer to top layer in first 10 seconds:
  4738. @example
  4739. blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
  4740. @end example
  4741. @item
  4742. Apply linear horizontal transition from top layer to bottom layer:
  4743. @example
  4744. blend=all_expr='A*(X/W)+B*(1-X/W)'
  4745. @end example
  4746. @item
  4747. Apply 1x1 checkerboard effect:
  4748. @example
  4749. blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
  4750. @end example
  4751. @item
  4752. Apply uncover left effect:
  4753. @example
  4754. blend=all_expr='if(gte(N*SW+X,W),A,B)'
  4755. @end example
  4756. @item
  4757. Apply uncover down effect:
  4758. @example
  4759. blend=all_expr='if(gte(Y-N*SH,0),A,B)'
  4760. @end example
  4761. @item
  4762. Apply uncover up-left effect:
  4763. @example
  4764. blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
  4765. @end example
  4766. @item
  4767. Split diagonally video and shows top and bottom layer on each side:
  4768. @example
  4769. blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
  4770. @end example
  4771. @item
  4772. Display differences between the current and the previous frame:
  4773. @example
  4774. tblend=all_mode=grainextract
  4775. @end example
  4776. @end itemize
  4777. @section bm3d
  4778. Denoise frames using Block-Matching 3D algorithm.
  4779. The filter accepts the following options.
  4780. @table @option
  4781. @item sigma
  4782. Set denoising strength. Default value is 1.
  4783. Allowed range is from 0 to 999.9.
  4784. The denoising algorithm is very sensitive to sigma, so adjust it
  4785. according to the source.
  4786. @item block
  4787. Set local patch size. This sets dimensions in 2D.
  4788. @item bstep
  4789. Set sliding step for processing blocks. Default value is 4.
  4790. Allowed range is from 1 to 64.
  4791. Smaller values allows processing more reference blocks and is slower.
  4792. @item group
  4793. Set maximal number of similar blocks for 3rd dimension. Default value is 1.
  4794. When set to 1, no block matching is done. Larger values allows more blocks
  4795. in single group.
  4796. Allowed range is from 1 to 256.
  4797. @item range
  4798. Set radius for search block matching. Default is 9.
  4799. Allowed range is from 1 to INT32_MAX.
  4800. @item mstep
  4801. Set step between two search locations for block matching. Default is 1.
  4802. Allowed range is from 1 to 64. Smaller is slower.
  4803. @item thmse
  4804. Set threshold of mean square error for block matching. Valid range is 0 to
  4805. INT32_MAX.
  4806. @item hdthr
  4807. Set thresholding parameter for hard thresholding in 3D transformed domain.
  4808. Larger values results in stronger hard-thresholding filtering in frequency
  4809. domain.
  4810. @item estim
  4811. Set filtering estimation mode. Can be @code{basic} or @code{final}.
  4812. Default is @code{basic}.
  4813. @item ref
  4814. If enabled, filter will use 2nd stream for block matching.
  4815. Default is disabled for @code{basic} value of @var{estim} option,
  4816. and always enabled if value of @var{estim} is @code{final}.
  4817. @item planes
  4818. Set planes to filter. Default is all available except alpha.
  4819. @end table
  4820. @subsection Examples
  4821. @itemize
  4822. @item
  4823. Basic filtering with bm3d:
  4824. @example
  4825. bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
  4826. @end example
  4827. @item
  4828. Same as above, but filtering only luma:
  4829. @example
  4830. bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
  4831. @end example
  4832. @item
  4833. Same as above, but with both estimation modes:
  4834. @example
  4835. split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
  4836. @end example
  4837. @item
  4838. Same as above, but prefilter with @ref{nlmeans} filter instead:
  4839. @example
  4840. split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1
  4841. @end example
  4842. @end itemize
  4843. @section boxblur
  4844. Apply a boxblur algorithm to the input video.
  4845. It accepts the following parameters:
  4846. @table @option
  4847. @item luma_radius, lr
  4848. @item luma_power, lp
  4849. @item chroma_radius, cr
  4850. @item chroma_power, cp
  4851. @item alpha_radius, ar
  4852. @item alpha_power, ap
  4853. @end table
  4854. A description of the accepted options follows.
  4855. @table @option
  4856. @item luma_radius, lr
  4857. @item chroma_radius, cr
  4858. @item alpha_radius, ar
  4859. Set an expression for the box radius in pixels used for blurring the
  4860. corresponding input plane.
  4861. The radius value must be a non-negative number, and must not be
  4862. greater than the value of the expression @code{min(w,h)/2} for the
  4863. luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
  4864. planes.
  4865. Default value for @option{luma_radius} is "2". If not specified,
  4866. @option{chroma_radius} and @option{alpha_radius} default to the
  4867. corresponding value set for @option{luma_radius}.
  4868. The expressions can contain the following constants:
  4869. @table @option
  4870. @item w
  4871. @item h
  4872. The input width and height in pixels.
  4873. @item cw
  4874. @item ch
  4875. The input chroma image width and height in pixels.
  4876. @item hsub
  4877. @item vsub
  4878. The horizontal and vertical chroma subsample values. For example, for the
  4879. pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
  4880. @end table
  4881. @item luma_power, lp
  4882. @item chroma_power, cp
  4883. @item alpha_power, ap
  4884. Specify how many times the boxblur filter is applied to the
  4885. corresponding plane.
  4886. Default value for @option{luma_power} is 2. If not specified,
  4887. @option{chroma_power} and @option{alpha_power} default to the
  4888. corresponding value set for @option{luma_power}.
  4889. A value of 0 will disable the effect.
  4890. @end table
  4891. @subsection Examples
  4892. @itemize
  4893. @item
  4894. Apply a boxblur filter with the luma, chroma, and alpha radii
  4895. set to 2:
  4896. @example
  4897. boxblur=luma_radius=2:luma_power=1
  4898. boxblur=2:1
  4899. @end example
  4900. @item
  4901. Set the luma radius to 2, and alpha and chroma radius to 0:
  4902. @example
  4903. boxblur=2:1:cr=0:ar=0
  4904. @end example
  4905. @item
  4906. Set the luma and chroma radii to a fraction of the video dimension:
  4907. @example
  4908. boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
  4909. @end example
  4910. @end itemize
  4911. @section bwdif
  4912. Deinterlace the input video ("bwdif" stands for "Bob Weaver
  4913. Deinterlacing Filter").
  4914. Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
  4915. interpolation algorithms.
  4916. It accepts the following parameters:
  4917. @table @option
  4918. @item mode
  4919. The interlacing mode to adopt. It accepts one of the following values:
  4920. @table @option
  4921. @item 0, send_frame
  4922. Output one frame for each frame.
  4923. @item 1, send_field
  4924. Output one frame for each field.
  4925. @end table
  4926. The default value is @code{send_field}.
  4927. @item parity
  4928. The picture field parity assumed for the input interlaced video. It accepts one
  4929. of the following values:
  4930. @table @option
  4931. @item 0, tff
  4932. Assume the top field is first.
  4933. @item 1, bff
  4934. Assume the bottom field is first.
  4935. @item -1, auto
  4936. Enable automatic detection of field parity.
  4937. @end table
  4938. The default value is @code{auto}.
  4939. If the interlacing is unknown or the decoder does not export this information,
  4940. top field first will be assumed.
  4941. @item deint
  4942. Specify which frames to deinterlace. Accept one of the following
  4943. values:
  4944. @table @option
  4945. @item 0, all
  4946. Deinterlace all frames.
  4947. @item 1, interlaced
  4948. Only deinterlace frames marked as interlaced.
  4949. @end table
  4950. The default value is @code{all}.
  4951. @end table
  4952. @section chromahold
  4953. Remove all color information for all colors except for certain one.
  4954. The filter accepts the following options:
  4955. @table @option
  4956. @item color
  4957. The color which will not be replaced with neutral chroma.
  4958. @item similarity
  4959. Similarity percentage with the above color.
  4960. 0.01 matches only the exact key color, while 1.0 matches everything.
  4961. @item yuv
  4962. Signals that the color passed is already in YUV instead of RGB.
  4963. Literal colors like "green" or "red" don't make sense with this enabled anymore.
  4964. This can be used to pass exact YUV values as hexadecimal numbers.
  4965. @end table
  4966. @section chromakey
  4967. YUV colorspace color/chroma keying.
  4968. The filter accepts the following options:
  4969. @table @option
  4970. @item color
  4971. The color which will be replaced with transparency.
  4972. @item similarity
  4973. Similarity percentage with the key color.
  4974. 0.01 matches only the exact key color, while 1.0 matches everything.
  4975. @item blend
  4976. Blend percentage.
  4977. 0.0 makes pixels either fully transparent, or not transparent at all.
  4978. Higher values result in semi-transparent pixels, with a higher transparency
  4979. the more similar the pixels color is to the key color.
  4980. @item yuv
  4981. Signals that the color passed is already in YUV instead of RGB.
  4982. Literal colors like "green" or "red" don't make sense with this enabled anymore.
  4983. This can be used to pass exact YUV values as hexadecimal numbers.
  4984. @end table
  4985. @subsection Examples
  4986. @itemize
  4987. @item
  4988. Make every green pixel in the input image transparent:
  4989. @example
  4990. ffmpeg -i input.png -vf chromakey=green out.png
  4991. @end example
  4992. @item
  4993. Overlay a greenscreen-video on top of a static black background.
  4994. @example
  4995. 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
  4996. @end example
  4997. @end itemize
  4998. @section chromashift
  4999. Shift chroma pixels horizontally and/or vertically.
  5000. The filter accepts the following options:
  5001. @table @option
  5002. @item cbh
  5003. Set amount to shift chroma-blue horizontally.
  5004. @item cbv
  5005. Set amount to shift chroma-blue vertically.
  5006. @item crh
  5007. Set amount to shift chroma-red horizontally.
  5008. @item crv
  5009. Set amount to shift chroma-red vertically.
  5010. @item edge
  5011. Set edge mode, can be @var{smear}, default, or @var{warp}.
  5012. @end table
  5013. @section ciescope
  5014. Display CIE color diagram with pixels overlaid onto it.
  5015. The filter accepts the following options:
  5016. @table @option
  5017. @item system
  5018. Set color system.
  5019. @table @samp
  5020. @item ntsc, 470m
  5021. @item ebu, 470bg
  5022. @item smpte
  5023. @item 240m
  5024. @item apple
  5025. @item widergb
  5026. @item cie1931
  5027. @item rec709, hdtv
  5028. @item uhdtv, rec2020
  5029. @end table
  5030. @item cie
  5031. Set CIE system.
  5032. @table @samp
  5033. @item xyy
  5034. @item ucs
  5035. @item luv
  5036. @end table
  5037. @item gamuts
  5038. Set what gamuts to draw.
  5039. See @code{system} option for available values.
  5040. @item size, s
  5041. Set ciescope size, by default set to 512.
  5042. @item intensity, i
  5043. Set intensity used to map input pixel values to CIE diagram.
  5044. @item contrast
  5045. Set contrast used to draw tongue colors that are out of active color system gamut.
  5046. @item corrgamma
  5047. Correct gamma displayed on scope, by default enabled.
  5048. @item showwhite
  5049. Show white point on CIE diagram, by default disabled.
  5050. @item gamma
  5051. Set input gamma. Used only with XYZ input color space.
  5052. @end table
  5053. @section codecview
  5054. Visualize information exported by some codecs.
  5055. Some codecs can export information through frames using side-data or other
  5056. means. For example, some MPEG based codecs export motion vectors through the
  5057. @var{export_mvs} flag in the codec @option{flags2} option.
  5058. The filter accepts the following option:
  5059. @table @option
  5060. @item mv
  5061. Set motion vectors to visualize.
  5062. Available flags for @var{mv} are:
  5063. @table @samp
  5064. @item pf
  5065. forward predicted MVs of P-frames
  5066. @item bf
  5067. forward predicted MVs of B-frames
  5068. @item bb
  5069. backward predicted MVs of B-frames
  5070. @end table
  5071. @item qp
  5072. Display quantization parameters using the chroma planes.
  5073. @item mv_type, mvt
  5074. Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
  5075. Available flags for @var{mv_type} are:
  5076. @table @samp
  5077. @item fp
  5078. forward predicted MVs
  5079. @item bp
  5080. backward predicted MVs
  5081. @end table
  5082. @item frame_type, ft
  5083. Set frame type to visualize motion vectors of.
  5084. Available flags for @var{frame_type} are:
  5085. @table @samp
  5086. @item if
  5087. intra-coded frames (I-frames)
  5088. @item pf
  5089. predicted frames (P-frames)
  5090. @item bf
  5091. bi-directionally predicted frames (B-frames)
  5092. @end table
  5093. @end table
  5094. @subsection Examples
  5095. @itemize
  5096. @item
  5097. Visualize forward predicted MVs of all frames using @command{ffplay}:
  5098. @example
  5099. ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
  5100. @end example
  5101. @item
  5102. Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
  5103. @example
  5104. ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
  5105. @end example
  5106. @end itemize
  5107. @section colorbalance
  5108. Modify intensity of primary colors (red, green and blue) of input frames.
  5109. The filter allows an input frame to be adjusted in the shadows, midtones or highlights
  5110. regions for the red-cyan, green-magenta or blue-yellow balance.
  5111. A positive adjustment value shifts the balance towards the primary color, a negative
  5112. value towards the complementary color.
  5113. The filter accepts the following options:
  5114. @table @option
  5115. @item rs
  5116. @item gs
  5117. @item bs
  5118. Adjust red, green and blue shadows (darkest pixels).
  5119. @item rm
  5120. @item gm
  5121. @item bm
  5122. Adjust red, green and blue midtones (medium pixels).
  5123. @item rh
  5124. @item gh
  5125. @item bh
  5126. Adjust red, green and blue highlights (brightest pixels).
  5127. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  5128. @end table
  5129. @subsection Examples
  5130. @itemize
  5131. @item
  5132. Add red color cast to shadows:
  5133. @example
  5134. colorbalance=rs=.3
  5135. @end example
  5136. @end itemize
  5137. @section colorkey
  5138. RGB colorspace color keying.
  5139. The filter accepts the following options:
  5140. @table @option
  5141. @item color
  5142. The color which will be replaced with transparency.
  5143. @item similarity
  5144. Similarity percentage with the key color.
  5145. 0.01 matches only the exact key color, while 1.0 matches everything.
  5146. @item blend
  5147. Blend percentage.
  5148. 0.0 makes pixels either fully transparent, or not transparent at all.
  5149. Higher values result in semi-transparent pixels, with a higher transparency
  5150. the more similar the pixels color is to the key color.
  5151. @end table
  5152. @subsection Examples
  5153. @itemize
  5154. @item
  5155. Make every green pixel in the input image transparent:
  5156. @example
  5157. ffmpeg -i input.png -vf colorkey=green out.png
  5158. @end example
  5159. @item
  5160. Overlay a greenscreen-video on top of a static background image.
  5161. @example
  5162. 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
  5163. @end example
  5164. @end itemize
  5165. @section colorlevels
  5166. Adjust video input frames using levels.
  5167. The filter accepts the following options:
  5168. @table @option
  5169. @item rimin
  5170. @item gimin
  5171. @item bimin
  5172. @item aimin
  5173. Adjust red, green, blue and alpha input black point.
  5174. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  5175. @item rimax
  5176. @item gimax
  5177. @item bimax
  5178. @item aimax
  5179. Adjust red, green, blue and alpha input white point.
  5180. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
  5181. Input levels are used to lighten highlights (bright tones), darken shadows
  5182. (dark tones), change the balance of bright and dark tones.
  5183. @item romin
  5184. @item gomin
  5185. @item bomin
  5186. @item aomin
  5187. Adjust red, green, blue and alpha output black point.
  5188. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
  5189. @item romax
  5190. @item gomax
  5191. @item bomax
  5192. @item aomax
  5193. Adjust red, green, blue and alpha output white point.
  5194. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
  5195. Output levels allows manual selection of a constrained output level range.
  5196. @end table
  5197. @subsection Examples
  5198. @itemize
  5199. @item
  5200. Make video output darker:
  5201. @example
  5202. colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
  5203. @end example
  5204. @item
  5205. Increase contrast:
  5206. @example
  5207. colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
  5208. @end example
  5209. @item
  5210. Make video output lighter:
  5211. @example
  5212. colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
  5213. @end example
  5214. @item
  5215. Increase brightness:
  5216. @example
  5217. colorlevels=romin=0.5:gomin=0.5:bomin=0.5
  5218. @end example
  5219. @end itemize
  5220. @section colorchannelmixer
  5221. Adjust video input frames by re-mixing color channels.
  5222. This filter modifies a color channel by adding the values associated to
  5223. the other channels of the same pixels. For example if the value to
  5224. modify is red, the output value will be:
  5225. @example
  5226. @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
  5227. @end example
  5228. The filter accepts the following options:
  5229. @table @option
  5230. @item rr
  5231. @item rg
  5232. @item rb
  5233. @item ra
  5234. Adjust contribution of input red, green, blue and alpha channels for output red channel.
  5235. Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
  5236. @item gr
  5237. @item gg
  5238. @item gb
  5239. @item ga
  5240. Adjust contribution of input red, green, blue and alpha channels for output green channel.
  5241. Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
  5242. @item br
  5243. @item bg
  5244. @item bb
  5245. @item ba
  5246. Adjust contribution of input red, green, blue and alpha channels for output blue channel.
  5247. Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
  5248. @item ar
  5249. @item ag
  5250. @item ab
  5251. @item aa
  5252. Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
  5253. Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
  5254. Allowed ranges for options are @code{[-2.0, 2.0]}.
  5255. @end table
  5256. @subsection Examples
  5257. @itemize
  5258. @item
  5259. Convert source to grayscale:
  5260. @example
  5261. colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
  5262. @end example
  5263. @item
  5264. Simulate sepia tones:
  5265. @example
  5266. colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
  5267. @end example
  5268. @end itemize
  5269. @section colormatrix
  5270. Convert color matrix.
  5271. The filter accepts the following options:
  5272. @table @option
  5273. @item src
  5274. @item dst
  5275. Specify the source and destination color matrix. Both values must be
  5276. specified.
  5277. The accepted values are:
  5278. @table @samp
  5279. @item bt709
  5280. BT.709
  5281. @item fcc
  5282. FCC
  5283. @item bt601
  5284. BT.601
  5285. @item bt470
  5286. BT.470
  5287. @item bt470bg
  5288. BT.470BG
  5289. @item smpte170m
  5290. SMPTE-170M
  5291. @item smpte240m
  5292. SMPTE-240M
  5293. @item bt2020
  5294. BT.2020
  5295. @end table
  5296. @end table
  5297. For example to convert from BT.601 to SMPTE-240M, use the command:
  5298. @example
  5299. colormatrix=bt601:smpte240m
  5300. @end example
  5301. @section colorspace
  5302. Convert colorspace, transfer characteristics or color primaries.
  5303. Input video needs to have an even size.
  5304. The filter accepts the following options:
  5305. @table @option
  5306. @anchor{all}
  5307. @item all
  5308. Specify all color properties at once.
  5309. The accepted values are:
  5310. @table @samp
  5311. @item bt470m
  5312. BT.470M
  5313. @item bt470bg
  5314. BT.470BG
  5315. @item bt601-6-525
  5316. BT.601-6 525
  5317. @item bt601-6-625
  5318. BT.601-6 625
  5319. @item bt709
  5320. BT.709
  5321. @item smpte170m
  5322. SMPTE-170M
  5323. @item smpte240m
  5324. SMPTE-240M
  5325. @item bt2020
  5326. BT.2020
  5327. @end table
  5328. @anchor{space}
  5329. @item space
  5330. Specify output colorspace.
  5331. The accepted values are:
  5332. @table @samp
  5333. @item bt709
  5334. BT.709
  5335. @item fcc
  5336. FCC
  5337. @item bt470bg
  5338. BT.470BG or BT.601-6 625
  5339. @item smpte170m
  5340. SMPTE-170M or BT.601-6 525
  5341. @item smpte240m
  5342. SMPTE-240M
  5343. @item ycgco
  5344. YCgCo
  5345. @item bt2020ncl
  5346. BT.2020 with non-constant luminance
  5347. @end table
  5348. @anchor{trc}
  5349. @item trc
  5350. Specify output transfer characteristics.
  5351. The accepted values are:
  5352. @table @samp
  5353. @item bt709
  5354. BT.709
  5355. @item bt470m
  5356. BT.470M
  5357. @item bt470bg
  5358. BT.470BG
  5359. @item gamma22
  5360. Constant gamma of 2.2
  5361. @item gamma28
  5362. Constant gamma of 2.8
  5363. @item smpte170m
  5364. SMPTE-170M, BT.601-6 625 or BT.601-6 525
  5365. @item smpte240m
  5366. SMPTE-240M
  5367. @item srgb
  5368. SRGB
  5369. @item iec61966-2-1
  5370. iec61966-2-1
  5371. @item iec61966-2-4
  5372. iec61966-2-4
  5373. @item xvycc
  5374. xvycc
  5375. @item bt2020-10
  5376. BT.2020 for 10-bits content
  5377. @item bt2020-12
  5378. BT.2020 for 12-bits content
  5379. @end table
  5380. @anchor{primaries}
  5381. @item primaries
  5382. Specify output color primaries.
  5383. The accepted values are:
  5384. @table @samp
  5385. @item bt709
  5386. BT.709
  5387. @item bt470m
  5388. BT.470M
  5389. @item bt470bg
  5390. BT.470BG or BT.601-6 625
  5391. @item smpte170m
  5392. SMPTE-170M or BT.601-6 525
  5393. @item smpte240m
  5394. SMPTE-240M
  5395. @item film
  5396. film
  5397. @item smpte431
  5398. SMPTE-431
  5399. @item smpte432
  5400. SMPTE-432
  5401. @item bt2020
  5402. BT.2020
  5403. @item jedec-p22
  5404. JEDEC P22 phosphors
  5405. @end table
  5406. @anchor{range}
  5407. @item range
  5408. Specify output color range.
  5409. The accepted values are:
  5410. @table @samp
  5411. @item tv
  5412. TV (restricted) range
  5413. @item mpeg
  5414. MPEG (restricted) range
  5415. @item pc
  5416. PC (full) range
  5417. @item jpeg
  5418. JPEG (full) range
  5419. @end table
  5420. @item format
  5421. Specify output color format.
  5422. The accepted values are:
  5423. @table @samp
  5424. @item yuv420p
  5425. YUV 4:2:0 planar 8-bits
  5426. @item yuv420p10
  5427. YUV 4:2:0 planar 10-bits
  5428. @item yuv420p12
  5429. YUV 4:2:0 planar 12-bits
  5430. @item yuv422p
  5431. YUV 4:2:2 planar 8-bits
  5432. @item yuv422p10
  5433. YUV 4:2:2 planar 10-bits
  5434. @item yuv422p12
  5435. YUV 4:2:2 planar 12-bits
  5436. @item yuv444p
  5437. YUV 4:4:4 planar 8-bits
  5438. @item yuv444p10
  5439. YUV 4:4:4 planar 10-bits
  5440. @item yuv444p12
  5441. YUV 4:4:4 planar 12-bits
  5442. @end table
  5443. @item fast
  5444. Do a fast conversion, which skips gamma/primary correction. This will take
  5445. significantly less CPU, but will be mathematically incorrect. To get output
  5446. compatible with that produced by the colormatrix filter, use fast=1.
  5447. @item dither
  5448. Specify dithering mode.
  5449. The accepted values are:
  5450. @table @samp
  5451. @item none
  5452. No dithering
  5453. @item fsb
  5454. Floyd-Steinberg dithering
  5455. @end table
  5456. @item wpadapt
  5457. Whitepoint adaptation mode.
  5458. The accepted values are:
  5459. @table @samp
  5460. @item bradford
  5461. Bradford whitepoint adaptation
  5462. @item vonkries
  5463. von Kries whitepoint adaptation
  5464. @item identity
  5465. identity whitepoint adaptation (i.e. no whitepoint adaptation)
  5466. @end table
  5467. @item iall
  5468. Override all input properties at once. Same accepted values as @ref{all}.
  5469. @item ispace
  5470. Override input colorspace. Same accepted values as @ref{space}.
  5471. @item iprimaries
  5472. Override input color primaries. Same accepted values as @ref{primaries}.
  5473. @item itrc
  5474. Override input transfer characteristics. Same accepted values as @ref{trc}.
  5475. @item irange
  5476. Override input color range. Same accepted values as @ref{range}.
  5477. @end table
  5478. The filter converts the transfer characteristics, color space and color
  5479. primaries to the specified user values. The output value, if not specified,
  5480. is set to a default value based on the "all" property. If that property is
  5481. also not specified, the filter will log an error. The output color range and
  5482. format default to the same value as the input color range and format. The
  5483. input transfer characteristics, color space, color primaries and color range
  5484. should be set on the input data. If any of these are missing, the filter will
  5485. log an error and no conversion will take place.
  5486. For example to convert the input to SMPTE-240M, use the command:
  5487. @example
  5488. colorspace=smpte240m
  5489. @end example
  5490. @section convolution
  5491. Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
  5492. The filter accepts the following options:
  5493. @table @option
  5494. @item 0m
  5495. @item 1m
  5496. @item 2m
  5497. @item 3m
  5498. Set matrix for each plane.
  5499. Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
  5500. and from 1 to 49 odd number of signed integers in @var{row} mode.
  5501. @item 0rdiv
  5502. @item 1rdiv
  5503. @item 2rdiv
  5504. @item 3rdiv
  5505. Set multiplier for calculated value for each plane.
  5506. If unset or 0, it will be sum of all matrix elements.
  5507. @item 0bias
  5508. @item 1bias
  5509. @item 2bias
  5510. @item 3bias
  5511. Set bias for each plane. This value is added to the result of the multiplication.
  5512. Useful for making the overall image brighter or darker. Default is 0.0.
  5513. @item 0mode
  5514. @item 1mode
  5515. @item 2mode
  5516. @item 3mode
  5517. Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
  5518. Default is @var{square}.
  5519. @end table
  5520. @subsection Examples
  5521. @itemize
  5522. @item
  5523. Apply sharpen:
  5524. @example
  5525. 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"
  5526. @end example
  5527. @item
  5528. Apply blur:
  5529. @example
  5530. 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"
  5531. @end example
  5532. @item
  5533. Apply edge enhance:
  5534. @example
  5535. 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"
  5536. @end example
  5537. @item
  5538. Apply edge detect:
  5539. @example
  5540. 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"
  5541. @end example
  5542. @item
  5543. Apply laplacian edge detector which includes diagonals:
  5544. @example
  5545. convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"
  5546. @end example
  5547. @item
  5548. Apply emboss:
  5549. @example
  5550. 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"
  5551. @end example
  5552. @end itemize
  5553. @section convolve
  5554. Apply 2D convolution of video stream in frequency domain using second stream
  5555. as impulse.
  5556. The filter accepts the following options:
  5557. @table @option
  5558. @item planes
  5559. Set which planes to process.
  5560. @item impulse
  5561. Set which impulse video frames will be processed, can be @var{first}
  5562. or @var{all}. Default is @var{all}.
  5563. @end table
  5564. The @code{convolve} filter also supports the @ref{framesync} options.
  5565. @section copy
  5566. Copy the input video source unchanged to the output. This is mainly useful for
  5567. testing purposes.
  5568. @anchor{coreimage}
  5569. @section coreimage
  5570. Video filtering on GPU using Apple's CoreImage API on OSX.
  5571. Hardware acceleration is based on an OpenGL context. Usually, this means it is
  5572. processed by video hardware. However, software-based OpenGL implementations
  5573. exist which means there is no guarantee for hardware processing. It depends on
  5574. the respective OSX.
  5575. There are many filters and image generators provided by Apple that come with a
  5576. large variety of options. The filter has to be referenced by its name along
  5577. with its options.
  5578. The coreimage filter accepts the following options:
  5579. @table @option
  5580. @item list_filters
  5581. List all available filters and generators along with all their respective
  5582. options as well as possible minimum and maximum values along with the default
  5583. values.
  5584. @example
  5585. list_filters=true
  5586. @end example
  5587. @item filter
  5588. Specify all filters by their respective name and options.
  5589. Use @var{list_filters} to determine all valid filter names and options.
  5590. Numerical options are specified by a float value and are automatically clamped
  5591. to their respective value range. Vector and color options have to be specified
  5592. by a list of space separated float values. Character escaping has to be done.
  5593. A special option name @code{default} is available to use default options for a
  5594. filter.
  5595. It is required to specify either @code{default} or at least one of the filter options.
  5596. All omitted options are used with their default values.
  5597. The syntax of the filter string is as follows:
  5598. @example
  5599. filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
  5600. @end example
  5601. @item output_rect
  5602. Specify a rectangle where the output of the filter chain is copied into the
  5603. input image. It is given by a list of space separated float values:
  5604. @example
  5605. output_rect=x\ y\ width\ height
  5606. @end example
  5607. If not given, the output rectangle equals the dimensions of the input image.
  5608. The output rectangle is automatically cropped at the borders of the input
  5609. image. Negative values are valid for each component.
  5610. @example
  5611. output_rect=25\ 25\ 100\ 100
  5612. @end example
  5613. @end table
  5614. Several filters can be chained for successive processing without GPU-HOST
  5615. transfers allowing for fast processing of complex filter chains.
  5616. Currently, only filters with zero (generators) or exactly one (filters) input
  5617. image and one output image are supported. Also, transition filters are not yet
  5618. usable as intended.
  5619. Some filters generate output images with additional padding depending on the
  5620. respective filter kernel. The padding is automatically removed to ensure the
  5621. filter output has the same size as the input image.
  5622. For image generators, the size of the output image is determined by the
  5623. previous output image of the filter chain or the input image of the whole
  5624. filterchain, respectively. The generators do not use the pixel information of
  5625. this image to generate their output. However, the generated output is
  5626. blended onto this image, resulting in partial or complete coverage of the
  5627. output image.
  5628. The @ref{coreimagesrc} video source can be used for generating input images
  5629. which are directly fed into the filter chain. By using it, providing input
  5630. images by another video source or an input video is not required.
  5631. @subsection Examples
  5632. @itemize
  5633. @item
  5634. List all filters available:
  5635. @example
  5636. coreimage=list_filters=true
  5637. @end example
  5638. @item
  5639. Use the CIBoxBlur filter with default options to blur an image:
  5640. @example
  5641. coreimage=filter=CIBoxBlur@@default
  5642. @end example
  5643. @item
  5644. Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
  5645. its center at 100x100 and a radius of 50 pixels:
  5646. @example
  5647. coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
  5648. @end example
  5649. @item
  5650. Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
  5651. given as complete and escaped command-line for Apple's standard bash shell:
  5652. @example
  5653. ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
  5654. @end example
  5655. @end itemize
  5656. @section crop
  5657. Crop the input video to given dimensions.
  5658. It accepts the following parameters:
  5659. @table @option
  5660. @item w, out_w
  5661. The width of the output video. It defaults to @code{iw}.
  5662. This expression is evaluated only once during the filter
  5663. configuration, or when the @samp{w} or @samp{out_w} command is sent.
  5664. @item h, out_h
  5665. The height of the output video. It defaults to @code{ih}.
  5666. This expression is evaluated only once during the filter
  5667. configuration, or when the @samp{h} or @samp{out_h} command is sent.
  5668. @item x
  5669. The horizontal position, in the input video, of the left edge of the output
  5670. video. It defaults to @code{(in_w-out_w)/2}.
  5671. This expression is evaluated per-frame.
  5672. @item y
  5673. The vertical position, in the input video, of the top edge of the output video.
  5674. It defaults to @code{(in_h-out_h)/2}.
  5675. This expression is evaluated per-frame.
  5676. @item keep_aspect
  5677. If set to 1 will force the output display aspect ratio
  5678. to be the same of the input, by changing the output sample aspect
  5679. ratio. It defaults to 0.
  5680. @item exact
  5681. Enable exact cropping. If enabled, subsampled videos will be cropped at exact
  5682. width/height/x/y as specified and will not be rounded to nearest smaller value.
  5683. It defaults to 0.
  5684. @end table
  5685. The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
  5686. expressions containing the following constants:
  5687. @table @option
  5688. @item x
  5689. @item y
  5690. The computed values for @var{x} and @var{y}. They are evaluated for
  5691. each new frame.
  5692. @item in_w
  5693. @item in_h
  5694. The input width and height.
  5695. @item iw
  5696. @item ih
  5697. These are the same as @var{in_w} and @var{in_h}.
  5698. @item out_w
  5699. @item out_h
  5700. The output (cropped) width and height.
  5701. @item ow
  5702. @item oh
  5703. These are the same as @var{out_w} and @var{out_h}.
  5704. @item a
  5705. same as @var{iw} / @var{ih}
  5706. @item sar
  5707. input sample aspect ratio
  5708. @item dar
  5709. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  5710. @item hsub
  5711. @item vsub
  5712. horizontal and vertical chroma subsample values. For example for the
  5713. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5714. @item n
  5715. The number of the input frame, starting from 0.
  5716. @item pos
  5717. the position in the file of the input frame, NAN if unknown
  5718. @item t
  5719. The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
  5720. @end table
  5721. The expression for @var{out_w} may depend on the value of @var{out_h},
  5722. and the expression for @var{out_h} may depend on @var{out_w}, but they
  5723. cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
  5724. evaluated after @var{out_w} and @var{out_h}.
  5725. The @var{x} and @var{y} parameters specify the expressions for the
  5726. position of the top-left corner of the output (non-cropped) area. They
  5727. are evaluated for each frame. If the evaluated value is not valid, it
  5728. is approximated to the nearest valid value.
  5729. The expression for @var{x} may depend on @var{y}, and the expression
  5730. for @var{y} may depend on @var{x}.
  5731. @subsection Examples
  5732. @itemize
  5733. @item
  5734. Crop area with size 100x100 at position (12,34).
  5735. @example
  5736. crop=100:100:12:34
  5737. @end example
  5738. Using named options, the example above becomes:
  5739. @example
  5740. crop=w=100:h=100:x=12:y=34
  5741. @end example
  5742. @item
  5743. Crop the central input area with size 100x100:
  5744. @example
  5745. crop=100:100
  5746. @end example
  5747. @item
  5748. Crop the central input area with size 2/3 of the input video:
  5749. @example
  5750. crop=2/3*in_w:2/3*in_h
  5751. @end example
  5752. @item
  5753. Crop the input video central square:
  5754. @example
  5755. crop=out_w=in_h
  5756. crop=in_h
  5757. @end example
  5758. @item
  5759. Delimit the rectangle with the top-left corner placed at position
  5760. 100:100 and the right-bottom corner corresponding to the right-bottom
  5761. corner of the input image.
  5762. @example
  5763. crop=in_w-100:in_h-100:100:100
  5764. @end example
  5765. @item
  5766. Crop 10 pixels from the left and right borders, and 20 pixels from
  5767. the top and bottom borders
  5768. @example
  5769. crop=in_w-2*10:in_h-2*20
  5770. @end example
  5771. @item
  5772. Keep only the bottom right quarter of the input image:
  5773. @example
  5774. crop=in_w/2:in_h/2:in_w/2:in_h/2
  5775. @end example
  5776. @item
  5777. Crop height for getting Greek harmony:
  5778. @example
  5779. crop=in_w:1/PHI*in_w
  5780. @end example
  5781. @item
  5782. Apply trembling effect:
  5783. @example
  5784. 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)
  5785. @end example
  5786. @item
  5787. Apply erratic camera effect depending on timestamp:
  5788. @example
  5789. 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)"
  5790. @end example
  5791. @item
  5792. Set x depending on the value of y:
  5793. @example
  5794. crop=in_w/2:in_h/2:y:10+10*sin(n/10)
  5795. @end example
  5796. @end itemize
  5797. @subsection Commands
  5798. This filter supports the following commands:
  5799. @table @option
  5800. @item w, out_w
  5801. @item h, out_h
  5802. @item x
  5803. @item y
  5804. Set width/height of the output video and the horizontal/vertical position
  5805. in the input video.
  5806. The command accepts the same syntax of the corresponding option.
  5807. If the specified expression is not valid, it is kept at its current
  5808. value.
  5809. @end table
  5810. @section cropdetect
  5811. Auto-detect the crop size.
  5812. It calculates the necessary cropping parameters and prints the
  5813. recommended parameters via the logging system. The detected dimensions
  5814. correspond to the non-black area of the input video.
  5815. It accepts the following parameters:
  5816. @table @option
  5817. @item limit
  5818. Set higher black value threshold, which can be optionally specified
  5819. from nothing (0) to everything (255 for 8-bit based formats). An intensity
  5820. value greater to the set value is considered non-black. It defaults to 24.
  5821. You can also specify a value between 0.0 and 1.0 which will be scaled depending
  5822. on the bitdepth of the pixel format.
  5823. @item round
  5824. The value which the width/height should be divisible by. It defaults to
  5825. 16. The offset is automatically adjusted to center the video. Use 2 to
  5826. get only even dimensions (needed for 4:2:2 video). 16 is best when
  5827. encoding to most video codecs.
  5828. @item reset_count, reset
  5829. Set the counter that determines after how many frames cropdetect will
  5830. reset the previously detected largest video area and start over to
  5831. detect the current optimal crop area. Default value is 0.
  5832. This can be useful when channel logos distort the video area. 0
  5833. indicates 'never reset', and returns the largest area encountered during
  5834. playback.
  5835. @end table
  5836. @anchor{cue}
  5837. @section cue
  5838. Delay video filtering until a given wallclock timestamp. The filter first
  5839. passes on @option{preroll} amount of frames, then it buffers at most
  5840. @option{buffer} amount of frames and waits for the cue. After reaching the cue
  5841. it forwards the buffered frames and also any subsequent frames coming in its
  5842. input.
  5843. The filter can be used synchronize the output of multiple ffmpeg processes for
  5844. realtime output devices like decklink. By putting the delay in the filtering
  5845. chain and pre-buffering frames the process can pass on data to output almost
  5846. immediately after the target wallclock timestamp is reached.
  5847. Perfect frame accuracy cannot be guaranteed, but the result is good enough for
  5848. some use cases.
  5849. @table @option
  5850. @item cue
  5851. The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
  5852. @item preroll
  5853. The duration of content to pass on as preroll expressed in seconds. Default is 0.
  5854. @item buffer
  5855. The maximum duration of content to buffer before waiting for the cue expressed
  5856. in seconds. Default is 0.
  5857. @end table
  5858. @anchor{curves}
  5859. @section curves
  5860. Apply color adjustments using curves.
  5861. This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
  5862. component (red, green and blue) has its values defined by @var{N} key points
  5863. tied from each other using a smooth curve. The x-axis represents the pixel
  5864. values from the input frame, and the y-axis the new pixel values to be set for
  5865. the output frame.
  5866. By default, a component curve is defined by the two points @var{(0;0)} and
  5867. @var{(1;1)}. This creates a straight line where each original pixel value is
  5868. "adjusted" to its own value, which means no change to the image.
  5869. The filter allows you to redefine these two points and add some more. A new
  5870. curve (using a natural cubic spline interpolation) will be define to pass
  5871. smoothly through all these new coordinates. The new defined points needs to be
  5872. strictly increasing over the x-axis, and their @var{x} and @var{y} values must
  5873. be in the @var{[0;1]} interval. If the computed curves happened to go outside
  5874. the vector spaces, the values will be clipped accordingly.
  5875. The filter accepts the following options:
  5876. @table @option
  5877. @item preset
  5878. Select one of the available color presets. This option can be used in addition
  5879. to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
  5880. options takes priority on the preset values.
  5881. Available presets are:
  5882. @table @samp
  5883. @item none
  5884. @item color_negative
  5885. @item cross_process
  5886. @item darker
  5887. @item increase_contrast
  5888. @item lighter
  5889. @item linear_contrast
  5890. @item medium_contrast
  5891. @item negative
  5892. @item strong_contrast
  5893. @item vintage
  5894. @end table
  5895. Default is @code{none}.
  5896. @item master, m
  5897. Set the master key points. These points will define a second pass mapping. It
  5898. is sometimes called a "luminance" or "value" mapping. It can be used with
  5899. @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
  5900. post-processing LUT.
  5901. @item red, r
  5902. Set the key points for the red component.
  5903. @item green, g
  5904. Set the key points for the green component.
  5905. @item blue, b
  5906. Set the key points for the blue component.
  5907. @item all
  5908. Set the key points for all components (not including master).
  5909. Can be used in addition to the other key points component
  5910. options. In this case, the unset component(s) will fallback on this
  5911. @option{all} setting.
  5912. @item psfile
  5913. Specify a Photoshop curves file (@code{.acv}) to import the settings from.
  5914. @item plot
  5915. Save Gnuplot script of the curves in specified file.
  5916. @end table
  5917. To avoid some filtergraph syntax conflicts, each key points list need to be
  5918. defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
  5919. @subsection Examples
  5920. @itemize
  5921. @item
  5922. Increase slightly the middle level of blue:
  5923. @example
  5924. curves=blue='0/0 0.5/0.58 1/1'
  5925. @end example
  5926. @item
  5927. Vintage effect:
  5928. @example
  5929. 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'
  5930. @end example
  5931. Here we obtain the following coordinates for each components:
  5932. @table @var
  5933. @item red
  5934. @code{(0;0.11) (0.42;0.51) (1;0.95)}
  5935. @item green
  5936. @code{(0;0) (0.50;0.48) (1;1)}
  5937. @item blue
  5938. @code{(0;0.22) (0.49;0.44) (1;0.80)}
  5939. @end table
  5940. @item
  5941. The previous example can also be achieved with the associated built-in preset:
  5942. @example
  5943. curves=preset=vintage
  5944. @end example
  5945. @item
  5946. Or simply:
  5947. @example
  5948. curves=vintage
  5949. @end example
  5950. @item
  5951. Use a Photoshop preset and redefine the points of the green component:
  5952. @example
  5953. curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
  5954. @end example
  5955. @item
  5956. Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
  5957. and @command{gnuplot}:
  5958. @example
  5959. ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
  5960. gnuplot -p /tmp/curves.plt
  5961. @end example
  5962. @end itemize
  5963. @section datascope
  5964. Video data analysis filter.
  5965. This filter shows hexadecimal pixel values of part of video.
  5966. The filter accepts the following options:
  5967. @table @option
  5968. @item size, s
  5969. Set output video size.
  5970. @item x
  5971. Set x offset from where to pick pixels.
  5972. @item y
  5973. Set y offset from where to pick pixels.
  5974. @item mode
  5975. Set scope mode, can be one of the following:
  5976. @table @samp
  5977. @item mono
  5978. Draw hexadecimal pixel values with white color on black background.
  5979. @item color
  5980. Draw hexadecimal pixel values with input video pixel color on black
  5981. background.
  5982. @item color2
  5983. Draw hexadecimal pixel values on color background picked from input video,
  5984. the text color is picked in such way so its always visible.
  5985. @end table
  5986. @item axis
  5987. Draw rows and columns numbers on left and top of video.
  5988. @item opacity
  5989. Set background opacity.
  5990. @end table
  5991. @section dctdnoiz
  5992. Denoise frames using 2D DCT (frequency domain filtering).
  5993. This filter is not designed for real time.
  5994. The filter accepts the following options:
  5995. @table @option
  5996. @item sigma, s
  5997. Set the noise sigma constant.
  5998. This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
  5999. coefficient (absolute value) below this threshold with be dropped.
  6000. If you need a more advanced filtering, see @option{expr}.
  6001. Default is @code{0}.
  6002. @item overlap
  6003. Set number overlapping pixels for each block. Since the filter can be slow, you
  6004. may want to reduce this value, at the cost of a less effective filter and the
  6005. risk of various artefacts.
  6006. If the overlapping value doesn't permit processing the whole input width or
  6007. height, a warning will be displayed and according borders won't be denoised.
  6008. Default value is @var{blocksize}-1, which is the best possible setting.
  6009. @item expr, e
  6010. Set the coefficient factor expression.
  6011. For each coefficient of a DCT block, this expression will be evaluated as a
  6012. multiplier value for the coefficient.
  6013. If this is option is set, the @option{sigma} option will be ignored.
  6014. The absolute value of the coefficient can be accessed through the @var{c}
  6015. variable.
  6016. @item n
  6017. Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
  6018. @var{blocksize}, which is the width and height of the processed blocks.
  6019. The default value is @var{3} (8x8) and can be raised to @var{4} for a
  6020. @var{blocksize} of 16x16. Note that changing this setting has huge consequences
  6021. on the speed processing. Also, a larger block size does not necessarily means a
  6022. better de-noising.
  6023. @end table
  6024. @subsection Examples
  6025. Apply a denoise with a @option{sigma} of @code{4.5}:
  6026. @example
  6027. dctdnoiz=4.5
  6028. @end example
  6029. The same operation can be achieved using the expression system:
  6030. @example
  6031. dctdnoiz=e='gte(c, 4.5*3)'
  6032. @end example
  6033. Violent denoise using a block size of @code{16x16}:
  6034. @example
  6035. dctdnoiz=15:n=4
  6036. @end example
  6037. @section deband
  6038. Remove banding artifacts from input video.
  6039. It works by replacing banded pixels with average value of referenced pixels.
  6040. The filter accepts the following options:
  6041. @table @option
  6042. @item 1thr
  6043. @item 2thr
  6044. @item 3thr
  6045. @item 4thr
  6046. Set banding detection threshold for each plane. Default is 0.02.
  6047. Valid range is 0.00003 to 0.5.
  6048. If difference between current pixel and reference pixel is less than threshold,
  6049. it will be considered as banded.
  6050. @item range, r
  6051. Banding detection range in pixels. Default is 16. If positive, random number
  6052. in range 0 to set value will be used. If negative, exact absolute value
  6053. will be used.
  6054. The range defines square of four pixels around current pixel.
  6055. @item direction, d
  6056. Set direction in radians from which four pixel will be compared. If positive,
  6057. random direction from 0 to set direction will be picked. If negative, exact of
  6058. absolute value will be picked. For example direction 0, -PI or -2*PI radians
  6059. will pick only pixels on same row and -PI/2 will pick only pixels on same
  6060. column.
  6061. @item blur, b
  6062. If enabled, current pixel is compared with average value of all four
  6063. surrounding pixels. The default is enabled. If disabled current pixel is
  6064. compared with all four surrounding pixels. The pixel is considered banded
  6065. if only all four differences with surrounding pixels are less than threshold.
  6066. @item coupling, c
  6067. If enabled, current pixel is changed if and only if all pixel components are banded,
  6068. e.g. banding detection threshold is triggered for all color components.
  6069. The default is disabled.
  6070. @end table
  6071. @section deblock
  6072. Remove blocking artifacts from input video.
  6073. The filter accepts the following options:
  6074. @table @option
  6075. @item filter
  6076. Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
  6077. This controls what kind of deblocking is applied.
  6078. @item block
  6079. Set size of block, allowed range is from 4 to 512. Default is @var{8}.
  6080. @item alpha
  6081. @item beta
  6082. @item gamma
  6083. @item delta
  6084. Set blocking detection thresholds. Allowed range is 0 to 1.
  6085. Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
  6086. Using higher threshold gives more deblocking strength.
  6087. Setting @var{alpha} controls threshold detection at exact edge of block.
  6088. Remaining options controls threshold detection near the edge. Each one for
  6089. below/above or left/right. Setting any of those to @var{0} disables
  6090. deblocking.
  6091. @item planes
  6092. Set planes to filter. Default is to filter all available planes.
  6093. @end table
  6094. @subsection Examples
  6095. @itemize
  6096. @item
  6097. Deblock using weak filter and block size of 4 pixels.
  6098. @example
  6099. deblock=filter=weak:block=4
  6100. @end example
  6101. @item
  6102. Deblock using strong filter, block size of 4 pixels and custom thresholds for
  6103. deblocking more edges.
  6104. @example
  6105. deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
  6106. @end example
  6107. @item
  6108. Similar as above, but filter only first plane.
  6109. @example
  6110. deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
  6111. @end example
  6112. @item
  6113. Similar as above, but filter only second and third plane.
  6114. @example
  6115. deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
  6116. @end example
  6117. @end itemize
  6118. @anchor{decimate}
  6119. @section decimate
  6120. Drop duplicated frames at regular intervals.
  6121. The filter accepts the following options:
  6122. @table @option
  6123. @item cycle
  6124. Set the number of frames from which one will be dropped. Setting this to
  6125. @var{N} means one frame in every batch of @var{N} frames will be dropped.
  6126. Default is @code{5}.
  6127. @item dupthresh
  6128. Set the threshold for duplicate detection. If the difference metric for a frame
  6129. is less than or equal to this value, then it is declared as duplicate. Default
  6130. is @code{1.1}
  6131. @item scthresh
  6132. Set scene change threshold. Default is @code{15}.
  6133. @item blockx
  6134. @item blocky
  6135. Set the size of the x and y-axis blocks used during metric calculations.
  6136. Larger blocks give better noise suppression, but also give worse detection of
  6137. small movements. Must be a power of two. Default is @code{32}.
  6138. @item ppsrc
  6139. Mark main input as a pre-processed input and activate clean source input
  6140. stream. This allows the input to be pre-processed with various filters to help
  6141. the metrics calculation while keeping the frame selection lossless. When set to
  6142. @code{1}, the first stream is for the pre-processed input, and the second
  6143. stream is the clean source from where the kept frames are chosen. Default is
  6144. @code{0}.
  6145. @item chroma
  6146. Set whether or not chroma is considered in the metric calculations. Default is
  6147. @code{1}.
  6148. @end table
  6149. @section deconvolve
  6150. Apply 2D deconvolution of video stream in frequency domain using second stream
  6151. as impulse.
  6152. The filter accepts the following options:
  6153. @table @option
  6154. @item planes
  6155. Set which planes to process.
  6156. @item impulse
  6157. Set which impulse video frames will be processed, can be @var{first}
  6158. or @var{all}. Default is @var{all}.
  6159. @item noise
  6160. Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
  6161. and height are not same and not power of 2 or if stream prior to convolving
  6162. had noise.
  6163. @end table
  6164. The @code{deconvolve} filter also supports the @ref{framesync} options.
  6165. @section dedot
  6166. Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
  6167. It accepts the following options:
  6168. @table @option
  6169. @item m
  6170. Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
  6171. @var{rainbows} for cross-color reduction.
  6172. @item lt
  6173. Set spatial luma threshold. Lower values increases reduction of cross-luminance.
  6174. @item tl
  6175. Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
  6176. @item tc
  6177. Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
  6178. @item ct
  6179. Set temporal chroma threshold. Lower values increases reduction of cross-color.
  6180. @end table
  6181. @section deflate
  6182. Apply deflate effect to the video.
  6183. This filter replaces the pixel by the local(3x3) average by taking into account
  6184. only values lower than the pixel.
  6185. It accepts the following options:
  6186. @table @option
  6187. @item threshold0
  6188. @item threshold1
  6189. @item threshold2
  6190. @item threshold3
  6191. Limit the maximum change for each plane, default is 65535.
  6192. If 0, plane will remain unchanged.
  6193. @end table
  6194. @section deflicker
  6195. Remove temporal frame luminance variations.
  6196. It accepts the following options:
  6197. @table @option
  6198. @item size, s
  6199. Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
  6200. @item mode, m
  6201. Set averaging mode to smooth temporal luminance variations.
  6202. Available values are:
  6203. @table @samp
  6204. @item am
  6205. Arithmetic mean
  6206. @item gm
  6207. Geometric mean
  6208. @item hm
  6209. Harmonic mean
  6210. @item qm
  6211. Quadratic mean
  6212. @item cm
  6213. Cubic mean
  6214. @item pm
  6215. Power mean
  6216. @item median
  6217. Median
  6218. @end table
  6219. @item bypass
  6220. Do not actually modify frame. Useful when one only wants metadata.
  6221. @end table
  6222. @section dejudder
  6223. Remove judder produced by partially interlaced telecined content.
  6224. Judder can be introduced, for instance, by @ref{pullup} filter. If the original
  6225. source was partially telecined content then the output of @code{pullup,dejudder}
  6226. will have a variable frame rate. May change the recorded frame rate of the
  6227. container. Aside from that change, this filter will not affect constant frame
  6228. rate video.
  6229. The option available in this filter is:
  6230. @table @option
  6231. @item cycle
  6232. Specify the length of the window over which the judder repeats.
  6233. Accepts any integer greater than 1. Useful values are:
  6234. @table @samp
  6235. @item 4
  6236. If the original was telecined from 24 to 30 fps (Film to NTSC).
  6237. @item 5
  6238. If the original was telecined from 25 to 30 fps (PAL to NTSC).
  6239. @item 20
  6240. If a mixture of the two.
  6241. @end table
  6242. The default is @samp{4}.
  6243. @end table
  6244. @section delogo
  6245. Suppress a TV station logo by a simple interpolation of the surrounding
  6246. pixels. Just set a rectangle covering the logo and watch it disappear
  6247. (and sometimes something even uglier appear - your mileage may vary).
  6248. It accepts the following parameters:
  6249. @table @option
  6250. @item x
  6251. @item y
  6252. Specify the top left corner coordinates of the logo. They must be
  6253. specified.
  6254. @item w
  6255. @item h
  6256. Specify the width and height of the logo to clear. They must be
  6257. specified.
  6258. @item band, t
  6259. Specify the thickness of the fuzzy edge of the rectangle (added to
  6260. @var{w} and @var{h}). The default value is 1. This option is
  6261. deprecated, setting higher values should no longer be necessary and
  6262. is not recommended.
  6263. @item show
  6264. When set to 1, a green rectangle is drawn on the screen to simplify
  6265. finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
  6266. The default value is 0.
  6267. The rectangle is drawn on the outermost pixels which will be (partly)
  6268. replaced with interpolated values. The values of the next pixels
  6269. immediately outside this rectangle in each direction will be used to
  6270. compute the interpolated pixel values inside the rectangle.
  6271. @end table
  6272. @subsection Examples
  6273. @itemize
  6274. @item
  6275. Set a rectangle covering the area with top left corner coordinates 0,0
  6276. and size 100x77, and a band of size 10:
  6277. @example
  6278. delogo=x=0:y=0:w=100:h=77:band=10
  6279. @end example
  6280. @end itemize
  6281. @section deshake
  6282. Attempt to fix small changes in horizontal and/or vertical shift. This
  6283. filter helps remove camera shake from hand-holding a camera, bumping a
  6284. tripod, moving on a vehicle, etc.
  6285. The filter accepts the following options:
  6286. @table @option
  6287. @item x
  6288. @item y
  6289. @item w
  6290. @item h
  6291. Specify a rectangular area where to limit the search for motion
  6292. vectors.
  6293. If desired the search for motion vectors can be limited to a
  6294. rectangular area of the frame defined by its top left corner, width
  6295. and height. These parameters have the same meaning as the drawbox
  6296. filter which can be used to visualise the position of the bounding
  6297. box.
  6298. This is useful when simultaneous movement of subjects within the frame
  6299. might be confused for camera motion by the motion vector search.
  6300. If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
  6301. then the full frame is used. This allows later options to be set
  6302. without specifying the bounding box for the motion vector search.
  6303. Default - search the whole frame.
  6304. @item rx
  6305. @item ry
  6306. Specify the maximum extent of movement in x and y directions in the
  6307. range 0-64 pixels. Default 16.
  6308. @item edge
  6309. Specify how to generate pixels to fill blanks at the edge of the
  6310. frame. Available values are:
  6311. @table @samp
  6312. @item blank, 0
  6313. Fill zeroes at blank locations
  6314. @item original, 1
  6315. Original image at blank locations
  6316. @item clamp, 2
  6317. Extruded edge value at blank locations
  6318. @item mirror, 3
  6319. Mirrored edge at blank locations
  6320. @end table
  6321. Default value is @samp{mirror}.
  6322. @item blocksize
  6323. Specify the blocksize to use for motion search. Range 4-128 pixels,
  6324. default 8.
  6325. @item contrast
  6326. Specify the contrast threshold for blocks. Only blocks with more than
  6327. the specified contrast (difference between darkest and lightest
  6328. pixels) will be considered. Range 1-255, default 125.
  6329. @item search
  6330. Specify the search strategy. Available values are:
  6331. @table @samp
  6332. @item exhaustive, 0
  6333. Set exhaustive search
  6334. @item less, 1
  6335. Set less exhaustive search.
  6336. @end table
  6337. Default value is @samp{exhaustive}.
  6338. @item filename
  6339. If set then a detailed log of the motion search is written to the
  6340. specified file.
  6341. @end table
  6342. @section despill
  6343. Remove unwanted contamination of foreground colors, caused by reflected color of
  6344. greenscreen or bluescreen.
  6345. This filter accepts the following options:
  6346. @table @option
  6347. @item type
  6348. Set what type of despill to use.
  6349. @item mix
  6350. Set how spillmap will be generated.
  6351. @item expand
  6352. Set how much to get rid of still remaining spill.
  6353. @item red
  6354. Controls amount of red in spill area.
  6355. @item green
  6356. Controls amount of green in spill area.
  6357. Should be -1 for greenscreen.
  6358. @item blue
  6359. Controls amount of blue in spill area.
  6360. Should be -1 for bluescreen.
  6361. @item brightness
  6362. Controls brightness of spill area, preserving colors.
  6363. @item alpha
  6364. Modify alpha from generated spillmap.
  6365. @end table
  6366. @section detelecine
  6367. Apply an exact inverse of the telecine operation. It requires a predefined
  6368. pattern specified using the pattern option which must be the same as that passed
  6369. to the telecine filter.
  6370. This filter accepts the following options:
  6371. @table @option
  6372. @item first_field
  6373. @table @samp
  6374. @item top, t
  6375. top field first
  6376. @item bottom, b
  6377. bottom field first
  6378. The default value is @code{top}.
  6379. @end table
  6380. @item pattern
  6381. A string of numbers representing the pulldown pattern you wish to apply.
  6382. The default value is @code{23}.
  6383. @item start_frame
  6384. A number representing position of the first frame with respect to the telecine
  6385. pattern. This is to be used if the stream is cut. The default value is @code{0}.
  6386. @end table
  6387. @section dilation
  6388. Apply dilation effect to the video.
  6389. This filter replaces the pixel by the local(3x3) maximum.
  6390. It accepts the following options:
  6391. @table @option
  6392. @item threshold0
  6393. @item threshold1
  6394. @item threshold2
  6395. @item threshold3
  6396. Limit the maximum change for each plane, default is 65535.
  6397. If 0, plane will remain unchanged.
  6398. @item coordinates
  6399. Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
  6400. pixels are used.
  6401. Flags to local 3x3 coordinates maps like this:
  6402. 1 2 3
  6403. 4 5
  6404. 6 7 8
  6405. @end table
  6406. @section displace
  6407. Displace pixels as indicated by second and third input stream.
  6408. It takes three input streams and outputs one stream, the first input is the
  6409. source, and second and third input are displacement maps.
  6410. The second input specifies how much to displace pixels along the
  6411. x-axis, while the third input specifies how much to displace pixels
  6412. along the y-axis.
  6413. If one of displacement map streams terminates, last frame from that
  6414. displacement map will be used.
  6415. Note that once generated, displacements maps can be reused over and over again.
  6416. A description of the accepted options follows.
  6417. @table @option
  6418. @item edge
  6419. Set displace behavior for pixels that are out of range.
  6420. Available values are:
  6421. @table @samp
  6422. @item blank
  6423. Missing pixels are replaced by black pixels.
  6424. @item smear
  6425. Adjacent pixels will spread out to replace missing pixels.
  6426. @item wrap
  6427. Out of range pixels are wrapped so they point to pixels of other side.
  6428. @item mirror
  6429. Out of range pixels will be replaced with mirrored pixels.
  6430. @end table
  6431. Default is @samp{smear}.
  6432. @end table
  6433. @subsection Examples
  6434. @itemize
  6435. @item
  6436. Add ripple effect to rgb input of video size hd720:
  6437. @example
  6438. 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
  6439. @end example
  6440. @item
  6441. Add wave effect to rgb input of video size hd720:
  6442. @example
  6443. 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
  6444. @end example
  6445. @end itemize
  6446. @section drawbox
  6447. Draw a colored box on the input image.
  6448. It accepts the following parameters:
  6449. @table @option
  6450. @item x
  6451. @item y
  6452. The expressions which specify the top left corner coordinates of the box. It defaults to 0.
  6453. @item width, w
  6454. @item height, h
  6455. The expressions which specify the width and height of the box; if 0 they are interpreted as
  6456. the input width and height. It defaults to 0.
  6457. @item color, c
  6458. Specify the color of the box to write. For the general syntax of this option,
  6459. check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
  6460. value @code{invert} is used, the box edge color is the same as the
  6461. video with inverted luma.
  6462. @item thickness, t
  6463. The expression which sets the thickness of the box edge.
  6464. A value of @code{fill} will create a filled box. Default value is @code{3}.
  6465. See below for the list of accepted constants.
  6466. @item replace
  6467. Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
  6468. will overwrite the video's color and alpha pixels.
  6469. Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
  6470. @end table
  6471. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  6472. following constants:
  6473. @table @option
  6474. @item dar
  6475. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  6476. @item hsub
  6477. @item vsub
  6478. horizontal and vertical chroma subsample values. For example for the
  6479. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6480. @item in_h, ih
  6481. @item in_w, iw
  6482. The input width and height.
  6483. @item sar
  6484. The input sample aspect ratio.
  6485. @item x
  6486. @item y
  6487. The x and y offset coordinates where the box is drawn.
  6488. @item w
  6489. @item h
  6490. The width and height of the drawn box.
  6491. @item t
  6492. The thickness of the drawn box.
  6493. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  6494. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  6495. @end table
  6496. @subsection Examples
  6497. @itemize
  6498. @item
  6499. Draw a black box around the edge of the input image:
  6500. @example
  6501. drawbox
  6502. @end example
  6503. @item
  6504. Draw a box with color red and an opacity of 50%:
  6505. @example
  6506. drawbox=10:20:200:60:red@@0.5
  6507. @end example
  6508. The previous example can be specified as:
  6509. @example
  6510. drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
  6511. @end example
  6512. @item
  6513. Fill the box with pink color:
  6514. @example
  6515. drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
  6516. @end example
  6517. @item
  6518. Draw a 2-pixel red 2.40:1 mask:
  6519. @example
  6520. 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
  6521. @end example
  6522. @end itemize
  6523. @section drawgrid
  6524. Draw a grid on the input image.
  6525. It accepts the following parameters:
  6526. @table @option
  6527. @item x
  6528. @item y
  6529. The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
  6530. @item width, w
  6531. @item height, h
  6532. The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
  6533. input width and height, respectively, minus @code{thickness}, so image gets
  6534. framed. Default to 0.
  6535. @item color, c
  6536. Specify the color of the grid. For the general syntax of this option,
  6537. check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
  6538. value @code{invert} is used, the grid color is the same as the
  6539. video with inverted luma.
  6540. @item thickness, t
  6541. The expression which sets the thickness of the grid line. Default value is @code{1}.
  6542. See below for the list of accepted constants.
  6543. @item replace
  6544. Applicable if the input has alpha. With @code{1} the pixels of the painted grid
  6545. will overwrite the video's color and alpha pixels.
  6546. Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
  6547. @end table
  6548. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  6549. following constants:
  6550. @table @option
  6551. @item dar
  6552. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  6553. @item hsub
  6554. @item vsub
  6555. horizontal and vertical chroma subsample values. For example for the
  6556. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6557. @item in_h, ih
  6558. @item in_w, iw
  6559. The input grid cell width and height.
  6560. @item sar
  6561. The input sample aspect ratio.
  6562. @item x
  6563. @item y
  6564. The x and y coordinates of some point of grid intersection (meant to configure offset).
  6565. @item w
  6566. @item h
  6567. The width and height of the drawn cell.
  6568. @item t
  6569. The thickness of the drawn cell.
  6570. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  6571. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  6572. @end table
  6573. @subsection Examples
  6574. @itemize
  6575. @item
  6576. Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
  6577. @example
  6578. drawgrid=width=100:height=100:thickness=2:color=red@@0.5
  6579. @end example
  6580. @item
  6581. Draw a white 3x3 grid with an opacity of 50%:
  6582. @example
  6583. drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
  6584. @end example
  6585. @end itemize
  6586. @anchor{drawtext}
  6587. @section drawtext
  6588. Draw a text string or text from a specified file on top of a video, using the
  6589. libfreetype library.
  6590. To enable compilation of this filter, you need to configure FFmpeg with
  6591. @code{--enable-libfreetype}.
  6592. To enable default font fallback and the @var{font} option you need to
  6593. configure FFmpeg with @code{--enable-libfontconfig}.
  6594. To enable the @var{text_shaping} option, you need to configure FFmpeg with
  6595. @code{--enable-libfribidi}.
  6596. @subsection Syntax
  6597. It accepts the following parameters:
  6598. @table @option
  6599. @item box
  6600. Used to draw a box around text using the background color.
  6601. The value must be either 1 (enable) or 0 (disable).
  6602. The default value of @var{box} is 0.
  6603. @item boxborderw
  6604. Set the width of the border to be drawn around the box using @var{boxcolor}.
  6605. The default value of @var{boxborderw} is 0.
  6606. @item boxcolor
  6607. The color to be used for drawing box around text. For the syntax of this
  6608. option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  6609. The default value of @var{boxcolor} is "white".
  6610. @item line_spacing
  6611. Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
  6612. The default value of @var{line_spacing} is 0.
  6613. @item borderw
  6614. Set the width of the border to be drawn around the text using @var{bordercolor}.
  6615. The default value of @var{borderw} is 0.
  6616. @item bordercolor
  6617. Set the color to be used for drawing border around text. For the syntax of this
  6618. option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  6619. The default value of @var{bordercolor} is "black".
  6620. @item expansion
  6621. Select how the @var{text} is expanded. Can be either @code{none},
  6622. @code{strftime} (deprecated) or
  6623. @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
  6624. below for details.
  6625. @item basetime
  6626. Set a start time for the count. Value is in microseconds. Only applied
  6627. in the deprecated strftime expansion mode. To emulate in normal expansion
  6628. mode use the @code{pts} function, supplying the start time (in seconds)
  6629. as the second argument.
  6630. @item fix_bounds
  6631. If true, check and fix text coords to avoid clipping.
  6632. @item fontcolor
  6633. The color to be used for drawing fonts. For the syntax of this option, check
  6634. the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  6635. The default value of @var{fontcolor} is "black".
  6636. @item fontcolor_expr
  6637. String which is expanded the same way as @var{text} to obtain dynamic
  6638. @var{fontcolor} value. By default this option has empty value and is not
  6639. processed. When this option is set, it overrides @var{fontcolor} option.
  6640. @item font
  6641. The font family to be used for drawing text. By default Sans.
  6642. @item fontfile
  6643. The font file to be used for drawing text. The path must be included.
  6644. This parameter is mandatory if the fontconfig support is disabled.
  6645. @item alpha
  6646. Draw the text applying alpha blending. The value can
  6647. be a number between 0.0 and 1.0.
  6648. The expression accepts the same variables @var{x, y} as well.
  6649. The default value is 1.
  6650. Please see @var{fontcolor_expr}.
  6651. @item fontsize
  6652. The font size to be used for drawing text.
  6653. The default value of @var{fontsize} is 16.
  6654. @item text_shaping
  6655. If set to 1, attempt to shape the text (for example, reverse the order of
  6656. right-to-left text and join Arabic characters) before drawing it.
  6657. Otherwise, just draw the text exactly as given.
  6658. By default 1 (if supported).
  6659. @item ft_load_flags
  6660. The flags to be used for loading the fonts.
  6661. The flags map the corresponding flags supported by libfreetype, and are
  6662. a combination of the following values:
  6663. @table @var
  6664. @item default
  6665. @item no_scale
  6666. @item no_hinting
  6667. @item render
  6668. @item no_bitmap
  6669. @item vertical_layout
  6670. @item force_autohint
  6671. @item crop_bitmap
  6672. @item pedantic
  6673. @item ignore_global_advance_width
  6674. @item no_recurse
  6675. @item ignore_transform
  6676. @item monochrome
  6677. @item linear_design
  6678. @item no_autohint
  6679. @end table
  6680. Default value is "default".
  6681. For more information consult the documentation for the FT_LOAD_*
  6682. libfreetype flags.
  6683. @item shadowcolor
  6684. The color to be used for drawing a shadow behind the drawn text. For the
  6685. syntax of this option, check the @ref{color syntax,,"Color" section in the
  6686. ffmpeg-utils manual,ffmpeg-utils}.
  6687. The default value of @var{shadowcolor} is "black".
  6688. @item shadowx
  6689. @item shadowy
  6690. The x and y offsets for the text shadow position with respect to the
  6691. position of the text. They can be either positive or negative
  6692. values. The default value for both is "0".
  6693. @item start_number
  6694. The starting frame number for the n/frame_num variable. The default value
  6695. is "0".
  6696. @item tabsize
  6697. The size in number of spaces to use for rendering the tab.
  6698. Default value is 4.
  6699. @item timecode
  6700. Set the initial timecode representation in "hh:mm:ss[:;.]ff"
  6701. format. It can be used with or without text parameter. @var{timecode_rate}
  6702. option must be specified.
  6703. @item timecode_rate, rate, r
  6704. Set the timecode frame rate (timecode only). Value will be rounded to nearest
  6705. integer. Minimum value is "1".
  6706. Drop-frame timecode is supported for frame rates 30 & 60.
  6707. @item tc24hmax
  6708. If set to 1, the output of the timecode option will wrap around at 24 hours.
  6709. Default is 0 (disabled).
  6710. @item text
  6711. The text string to be drawn. The text must be a sequence of UTF-8
  6712. encoded characters.
  6713. This parameter is mandatory if no file is specified with the parameter
  6714. @var{textfile}.
  6715. @item textfile
  6716. A text file containing text to be drawn. The text must be a sequence
  6717. of UTF-8 encoded characters.
  6718. This parameter is mandatory if no text string is specified with the
  6719. parameter @var{text}.
  6720. If both @var{text} and @var{textfile} are specified, an error is thrown.
  6721. @item reload
  6722. If set to 1, the @var{textfile} will be reloaded before each frame.
  6723. Be sure to update it atomically, or it may be read partially, or even fail.
  6724. @item x
  6725. @item y
  6726. The expressions which specify the offsets where text will be drawn
  6727. within the video frame. They are relative to the top/left border of the
  6728. output image.
  6729. The default value of @var{x} and @var{y} is "0".
  6730. See below for the list of accepted constants and functions.
  6731. @end table
  6732. The parameters for @var{x} and @var{y} are expressions containing the
  6733. following constants and functions:
  6734. @table @option
  6735. @item dar
  6736. input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
  6737. @item hsub
  6738. @item vsub
  6739. horizontal and vertical chroma subsample values. For example for the
  6740. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6741. @item line_h, lh
  6742. the height of each text line
  6743. @item main_h, h, H
  6744. the input height
  6745. @item main_w, w, W
  6746. the input width
  6747. @item max_glyph_a, ascent
  6748. the maximum distance from the baseline to the highest/upper grid
  6749. coordinate used to place a glyph outline point, for all the rendered
  6750. glyphs.
  6751. It is a positive value, due to the grid's orientation with the Y axis
  6752. upwards.
  6753. @item max_glyph_d, descent
  6754. the maximum distance from the baseline to the lowest grid coordinate
  6755. used to place a glyph outline point, for all the rendered glyphs.
  6756. This is a negative value, due to the grid's orientation, with the Y axis
  6757. upwards.
  6758. @item max_glyph_h
  6759. maximum glyph height, that is the maximum height for all the glyphs
  6760. contained in the rendered text, it is equivalent to @var{ascent} -
  6761. @var{descent}.
  6762. @item max_glyph_w
  6763. maximum glyph width, that is the maximum width for all the glyphs
  6764. contained in the rendered text
  6765. @item n
  6766. the number of input frame, starting from 0
  6767. @item rand(min, max)
  6768. return a random number included between @var{min} and @var{max}
  6769. @item sar
  6770. The input sample aspect ratio.
  6771. @item t
  6772. timestamp expressed in seconds, NAN if the input timestamp is unknown
  6773. @item text_h, th
  6774. the height of the rendered text
  6775. @item text_w, tw
  6776. the width of the rendered text
  6777. @item x
  6778. @item y
  6779. the x and y offset coordinates where the text is drawn.
  6780. These parameters allow the @var{x} and @var{y} expressions to refer
  6781. each other, so you can for example specify @code{y=x/dar}.
  6782. @end table
  6783. @anchor{drawtext_expansion}
  6784. @subsection Text expansion
  6785. If @option{expansion} is set to @code{strftime},
  6786. the filter recognizes strftime() sequences in the provided text and
  6787. expands them accordingly. Check the documentation of strftime(). This
  6788. feature is deprecated.
  6789. If @option{expansion} is set to @code{none}, the text is printed verbatim.
  6790. If @option{expansion} is set to @code{normal} (which is the default),
  6791. the following expansion mechanism is used.
  6792. The backslash character @samp{\}, followed by any character, always expands to
  6793. the second character.
  6794. Sequences of the form @code{%@{...@}} are expanded. The text between the
  6795. braces is a function name, possibly followed by arguments separated by ':'.
  6796. If the arguments contain special characters or delimiters (':' or '@}'),
  6797. they should be escaped.
  6798. Note that they probably must also be escaped as the value for the
  6799. @option{text} option in the filter argument string and as the filter
  6800. argument in the filtergraph description, and possibly also for the shell,
  6801. that makes up to four levels of escaping; using a text file avoids these
  6802. problems.
  6803. The following functions are available:
  6804. @table @command
  6805. @item expr, e
  6806. The expression evaluation result.
  6807. It must take one argument specifying the expression to be evaluated,
  6808. which accepts the same constants and functions as the @var{x} and
  6809. @var{y} values. Note that not all constants should be used, for
  6810. example the text size is not known when evaluating the expression, so
  6811. the constants @var{text_w} and @var{text_h} will have an undefined
  6812. value.
  6813. @item expr_int_format, eif
  6814. Evaluate the expression's value and output as formatted integer.
  6815. The first argument is the expression to be evaluated, just as for the @var{expr} function.
  6816. The second argument specifies the output format. Allowed values are @samp{x},
  6817. @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
  6818. @code{printf} function.
  6819. The third parameter is optional and sets the number of positions taken by the output.
  6820. It can be used to add padding with zeros from the left.
  6821. @item gmtime
  6822. The time at which the filter is running, expressed in UTC.
  6823. It can accept an argument: a strftime() format string.
  6824. @item localtime
  6825. The time at which the filter is running, expressed in the local time zone.
  6826. It can accept an argument: a strftime() format string.
  6827. @item metadata
  6828. Frame metadata. Takes one or two arguments.
  6829. The first argument is mandatory and specifies the metadata key.
  6830. The second argument is optional and specifies a default value, used when the
  6831. metadata key is not found or empty.
  6832. @item n, frame_num
  6833. The frame number, starting from 0.
  6834. @item pict_type
  6835. A 1 character description of the current picture type.
  6836. @item pts
  6837. The timestamp of the current frame.
  6838. It can take up to three arguments.
  6839. The first argument is the format of the timestamp; it defaults to @code{flt}
  6840. for seconds as a decimal number with microsecond accuracy; @code{hms} stands
  6841. for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
  6842. @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
  6843. @code{localtime} stands for the timestamp of the frame formatted as
  6844. local time zone time.
  6845. The second argument is an offset added to the timestamp.
  6846. If the format is set to @code{hms}, a third argument @code{24HH} may be
  6847. supplied to present the hour part of the formatted timestamp in 24h format
  6848. (00-23).
  6849. If the format is set to @code{localtime} or @code{gmtime},
  6850. a third argument may be supplied: a strftime() format string.
  6851. By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
  6852. @end table
  6853. @subsection Examples
  6854. @itemize
  6855. @item
  6856. Draw "Test Text" with font FreeSerif, using the default values for the
  6857. optional parameters.
  6858. @example
  6859. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
  6860. @end example
  6861. @item
  6862. Draw 'Test Text' with font FreeSerif of size 24 at position x=100
  6863. and y=50 (counting from the top-left corner of the screen), text is
  6864. yellow with a red box around it. Both the text and the box have an
  6865. opacity of 20%.
  6866. @example
  6867. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
  6868. x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
  6869. @end example
  6870. Note that the double quotes are not necessary if spaces are not used
  6871. within the parameter list.
  6872. @item
  6873. Show the text at the center of the video frame:
  6874. @example
  6875. drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
  6876. @end example
  6877. @item
  6878. Show the text at a random position, switching to a new position every 30 seconds:
  6879. @example
  6880. 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)"
  6881. @end example
  6882. @item
  6883. Show a text line sliding from right to left in the last row of the video
  6884. frame. The file @file{LONG_LINE} is assumed to contain a single line
  6885. with no newlines.
  6886. @example
  6887. drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
  6888. @end example
  6889. @item
  6890. Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
  6891. @example
  6892. drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
  6893. @end example
  6894. @item
  6895. Draw a single green letter "g", at the center of the input video.
  6896. The glyph baseline is placed at half screen height.
  6897. @example
  6898. drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
  6899. @end example
  6900. @item
  6901. Show text for 1 second every 3 seconds:
  6902. @example
  6903. drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
  6904. @end example
  6905. @item
  6906. Use fontconfig to set the font. Note that the colons need to be escaped.
  6907. @example
  6908. drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
  6909. @end example
  6910. @item
  6911. Print the date of a real-time encoding (see strftime(3)):
  6912. @example
  6913. drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
  6914. @end example
  6915. @item
  6916. Show text fading in and out (appearing/disappearing):
  6917. @example
  6918. #!/bin/sh
  6919. DS=1.0 # display start
  6920. DE=10.0 # display end
  6921. FID=1.5 # fade in duration
  6922. FOD=5 # fade out duration
  6923. 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 @}"
  6924. @end example
  6925. @item
  6926. Horizontally align multiple separate texts. Note that @option{max_glyph_a}
  6927. and the @option{fontsize} value are included in the @option{y} offset.
  6928. @example
  6929. drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
  6930. drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
  6931. @end example
  6932. @end itemize
  6933. For more information about libfreetype, check:
  6934. @url{http://www.freetype.org/}.
  6935. For more information about fontconfig, check:
  6936. @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
  6937. For more information about libfribidi, check:
  6938. @url{http://fribidi.org/}.
  6939. @section edgedetect
  6940. Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
  6941. The filter accepts the following options:
  6942. @table @option
  6943. @item low
  6944. @item high
  6945. Set low and high threshold values used by the Canny thresholding
  6946. algorithm.
  6947. The high threshold selects the "strong" edge pixels, which are then
  6948. connected through 8-connectivity with the "weak" edge pixels selected
  6949. by the low threshold.
  6950. @var{low} and @var{high} threshold values must be chosen in the range
  6951. [0,1], and @var{low} should be lesser or equal to @var{high}.
  6952. Default value for @var{low} is @code{20/255}, and default value for @var{high}
  6953. is @code{50/255}.
  6954. @item mode
  6955. Define the drawing mode.
  6956. @table @samp
  6957. @item wires
  6958. Draw white/gray wires on black background.
  6959. @item colormix
  6960. Mix the colors to create a paint/cartoon effect.
  6961. @item canny
  6962. Apply Canny edge detector on all selected planes.
  6963. @end table
  6964. Default value is @var{wires}.
  6965. @item planes
  6966. Select planes for filtering. By default all available planes are filtered.
  6967. @end table
  6968. @subsection Examples
  6969. @itemize
  6970. @item
  6971. Standard edge detection with custom values for the hysteresis thresholding:
  6972. @example
  6973. edgedetect=low=0.1:high=0.4
  6974. @end example
  6975. @item
  6976. Painting effect without thresholding:
  6977. @example
  6978. edgedetect=mode=colormix:high=0
  6979. @end example
  6980. @end itemize
  6981. @section eq
  6982. Set brightness, contrast, saturation and approximate gamma adjustment.
  6983. The filter accepts the following options:
  6984. @table @option
  6985. @item contrast
  6986. Set the contrast expression. The value must be a float value in range
  6987. @code{-2.0} to @code{2.0}. The default value is "1".
  6988. @item brightness
  6989. Set the brightness expression. The value must be a float value in
  6990. range @code{-1.0} to @code{1.0}. The default value is "0".
  6991. @item saturation
  6992. Set the saturation expression. The value must be a float in
  6993. range @code{0.0} to @code{3.0}. The default value is "1".
  6994. @item gamma
  6995. Set the gamma expression. The value must be a float in range
  6996. @code{0.1} to @code{10.0}. The default value is "1".
  6997. @item gamma_r
  6998. Set the gamma expression for red. The value must be a float in
  6999. range @code{0.1} to @code{10.0}. The default value is "1".
  7000. @item gamma_g
  7001. Set the gamma expression for green. The value must be a float in range
  7002. @code{0.1} to @code{10.0}. The default value is "1".
  7003. @item gamma_b
  7004. Set the gamma expression for blue. The value must be a float in range
  7005. @code{0.1} to @code{10.0}. The default value is "1".
  7006. @item gamma_weight
  7007. Set the gamma weight expression. It can be used to reduce the effect
  7008. of a high gamma value on bright image areas, e.g. keep them from
  7009. getting overamplified and just plain white. The value must be a float
  7010. in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
  7011. gamma correction all the way down while @code{1.0} leaves it at its
  7012. full strength. Default is "1".
  7013. @item eval
  7014. Set when the expressions for brightness, contrast, saturation and
  7015. gamma expressions are evaluated.
  7016. It accepts the following values:
  7017. @table @samp
  7018. @item init
  7019. only evaluate expressions once during the filter initialization or
  7020. when a command is processed
  7021. @item frame
  7022. evaluate expressions for each incoming frame
  7023. @end table
  7024. Default value is @samp{init}.
  7025. @end table
  7026. The expressions accept the following parameters:
  7027. @table @option
  7028. @item n
  7029. frame count of the input frame starting from 0
  7030. @item pos
  7031. byte position of the corresponding packet in the input file, NAN if
  7032. unspecified
  7033. @item r
  7034. frame rate of the input video, NAN if the input frame rate is unknown
  7035. @item t
  7036. timestamp expressed in seconds, NAN if the input timestamp is unknown
  7037. @end table
  7038. @subsection Commands
  7039. The filter supports the following commands:
  7040. @table @option
  7041. @item contrast
  7042. Set the contrast expression.
  7043. @item brightness
  7044. Set the brightness expression.
  7045. @item saturation
  7046. Set the saturation expression.
  7047. @item gamma
  7048. Set the gamma expression.
  7049. @item gamma_r
  7050. Set the gamma_r expression.
  7051. @item gamma_g
  7052. Set gamma_g expression.
  7053. @item gamma_b
  7054. Set gamma_b expression.
  7055. @item gamma_weight
  7056. Set gamma_weight expression.
  7057. The command accepts the same syntax of the corresponding option.
  7058. If the specified expression is not valid, it is kept at its current
  7059. value.
  7060. @end table
  7061. @section erosion
  7062. Apply erosion effect to the video.
  7063. This filter replaces the pixel by the local(3x3) minimum.
  7064. It accepts the following options:
  7065. @table @option
  7066. @item threshold0
  7067. @item threshold1
  7068. @item threshold2
  7069. @item threshold3
  7070. Limit the maximum change for each plane, default is 65535.
  7071. If 0, plane will remain unchanged.
  7072. @item coordinates
  7073. Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
  7074. pixels are used.
  7075. Flags to local 3x3 coordinates maps like this:
  7076. 1 2 3
  7077. 4 5
  7078. 6 7 8
  7079. @end table
  7080. @section extractplanes
  7081. Extract color channel components from input video stream into
  7082. separate grayscale video streams.
  7083. The filter accepts the following option:
  7084. @table @option
  7085. @item planes
  7086. Set plane(s) to extract.
  7087. Available values for planes are:
  7088. @table @samp
  7089. @item y
  7090. @item u
  7091. @item v
  7092. @item a
  7093. @item r
  7094. @item g
  7095. @item b
  7096. @end table
  7097. Choosing planes not available in the input will result in an error.
  7098. That means you cannot select @code{r}, @code{g}, @code{b} planes
  7099. with @code{y}, @code{u}, @code{v} planes at same time.
  7100. @end table
  7101. @subsection Examples
  7102. @itemize
  7103. @item
  7104. Extract luma, u and v color channel component from input video frame
  7105. into 3 grayscale outputs:
  7106. @example
  7107. 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
  7108. @end example
  7109. @end itemize
  7110. @section elbg
  7111. Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
  7112. For each input image, the filter will compute the optimal mapping from
  7113. the input to the output given the codebook length, that is the number
  7114. of distinct output colors.
  7115. This filter accepts the following options.
  7116. @table @option
  7117. @item codebook_length, l
  7118. Set codebook length. The value must be a positive integer, and
  7119. represents the number of distinct output colors. Default value is 256.
  7120. @item nb_steps, n
  7121. Set the maximum number of iterations to apply for computing the optimal
  7122. mapping. The higher the value the better the result and the higher the
  7123. computation time. Default value is 1.
  7124. @item seed, s
  7125. Set a random seed, must be an integer included between 0 and
  7126. UINT32_MAX. If not specified, or if explicitly set to -1, the filter
  7127. will try to use a good random seed on a best effort basis.
  7128. @item pal8
  7129. Set pal8 output pixel format. This option does not work with codebook
  7130. length greater than 256.
  7131. @end table
  7132. @section entropy
  7133. Measure graylevel entropy in histogram of color channels of video frames.
  7134. It accepts the following parameters:
  7135. @table @option
  7136. @item mode
  7137. Can be either @var{normal} or @var{diff}. Default is @var{normal}.
  7138. @var{diff} mode measures entropy of histogram delta values, absolute differences
  7139. between neighbour histogram values.
  7140. @end table
  7141. @section fade
  7142. Apply a fade-in/out effect to the input video.
  7143. It accepts the following parameters:
  7144. @table @option
  7145. @item type, t
  7146. The effect type can be either "in" for a fade-in, or "out" for a fade-out
  7147. effect.
  7148. Default is @code{in}.
  7149. @item start_frame, s
  7150. Specify the number of the frame to start applying the fade
  7151. effect at. Default is 0.
  7152. @item nb_frames, n
  7153. The number of frames that the fade effect lasts. At the end of the
  7154. fade-in effect, the output video will have the same intensity as the input video.
  7155. At the end of the fade-out transition, the output video will be filled with the
  7156. selected @option{color}.
  7157. Default is 25.
  7158. @item alpha
  7159. If set to 1, fade only alpha channel, if one exists on the input.
  7160. Default value is 0.
  7161. @item start_time, st
  7162. Specify the timestamp (in seconds) of the frame to start to apply the fade
  7163. effect. If both start_frame and start_time are specified, the fade will start at
  7164. whichever comes last. Default is 0.
  7165. @item duration, d
  7166. The number of seconds for which the fade effect has to last. At the end of the
  7167. fade-in effect the output video will have the same intensity as the input video,
  7168. at the end of the fade-out transition the output video will be filled with the
  7169. selected @option{color}.
  7170. If both duration and nb_frames are specified, duration is used. Default is 0
  7171. (nb_frames is used by default).
  7172. @item color, c
  7173. Specify the color of the fade. Default is "black".
  7174. @end table
  7175. @subsection Examples
  7176. @itemize
  7177. @item
  7178. Fade in the first 30 frames of video:
  7179. @example
  7180. fade=in:0:30
  7181. @end example
  7182. The command above is equivalent to:
  7183. @example
  7184. fade=t=in:s=0:n=30
  7185. @end example
  7186. @item
  7187. Fade out the last 45 frames of a 200-frame video:
  7188. @example
  7189. fade=out:155:45
  7190. fade=type=out:start_frame=155:nb_frames=45
  7191. @end example
  7192. @item
  7193. Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
  7194. @example
  7195. fade=in:0:25, fade=out:975:25
  7196. @end example
  7197. @item
  7198. Make the first 5 frames yellow, then fade in from frame 5-24:
  7199. @example
  7200. fade=in:5:20:color=yellow
  7201. @end example
  7202. @item
  7203. Fade in alpha over first 25 frames of video:
  7204. @example
  7205. fade=in:0:25:alpha=1
  7206. @end example
  7207. @item
  7208. Make the first 5.5 seconds black, then fade in for 0.5 seconds:
  7209. @example
  7210. fade=t=in:st=5.5:d=0.5
  7211. @end example
  7212. @end itemize
  7213. @section fftfilt
  7214. Apply arbitrary expressions to samples in frequency domain
  7215. @table @option
  7216. @item dc_Y
  7217. Adjust the dc value (gain) of the luma plane of the image. The filter
  7218. accepts an integer value in range @code{0} to @code{1000}. The default
  7219. value is set to @code{0}.
  7220. @item dc_U
  7221. Adjust the dc value (gain) of the 1st chroma plane of the image. The
  7222. filter accepts an integer value in range @code{0} to @code{1000}. The
  7223. default value is set to @code{0}.
  7224. @item dc_V
  7225. Adjust the dc value (gain) of the 2nd chroma plane of the image. The
  7226. filter accepts an integer value in range @code{0} to @code{1000}. The
  7227. default value is set to @code{0}.
  7228. @item weight_Y
  7229. Set the frequency domain weight expression for the luma plane.
  7230. @item weight_U
  7231. Set the frequency domain weight expression for the 1st chroma plane.
  7232. @item weight_V
  7233. Set the frequency domain weight expression for the 2nd chroma plane.
  7234. @item eval
  7235. Set when the expressions are evaluated.
  7236. It accepts the following values:
  7237. @table @samp
  7238. @item init
  7239. Only evaluate expressions once during the filter initialization.
  7240. @item frame
  7241. Evaluate expressions for each incoming frame.
  7242. @end table
  7243. Default value is @samp{init}.
  7244. The filter accepts the following variables:
  7245. @item X
  7246. @item Y
  7247. The coordinates of the current sample.
  7248. @item W
  7249. @item H
  7250. The width and height of the image.
  7251. @item N
  7252. The number of input frame, starting from 0.
  7253. @end table
  7254. @subsection Examples
  7255. @itemize
  7256. @item
  7257. High-pass:
  7258. @example
  7259. fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
  7260. @end example
  7261. @item
  7262. Low-pass:
  7263. @example
  7264. fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
  7265. @end example
  7266. @item
  7267. Sharpen:
  7268. @example
  7269. fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
  7270. @end example
  7271. @item
  7272. Blur:
  7273. @example
  7274. fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
  7275. @end example
  7276. @end itemize
  7277. @section fftdnoiz
  7278. Denoise frames using 3D FFT (frequency domain filtering).
  7279. The filter accepts the following options:
  7280. @table @option
  7281. @item sigma
  7282. Set the noise sigma constant. This sets denoising strength.
  7283. Default value is 1. Allowed range is from 0 to 30.
  7284. Using very high sigma with low overlap may give blocking artifacts.
  7285. @item amount
  7286. Set amount of denoising. By default all detected noise is reduced.
  7287. Default value is 1. Allowed range is from 0 to 1.
  7288. @item block
  7289. Set size of block, Default is 4, can be 3, 4, 5 or 6.
  7290. Actual size of block in pixels is 2 to power of @var{block}, so by default
  7291. block size in pixels is 2^4 which is 16.
  7292. @item overlap
  7293. Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
  7294. @item prev
  7295. Set number of previous frames to use for denoising. By default is set to 0.
  7296. @item next
  7297. Set number of next frames to to use for denoising. By default is set to 0.
  7298. @item planes
  7299. Set planes which will be filtered, by default are all available filtered
  7300. except alpha.
  7301. @end table
  7302. @section field
  7303. Extract a single field from an interlaced image using stride
  7304. arithmetic to avoid wasting CPU time. The output frames are marked as
  7305. non-interlaced.
  7306. The filter accepts the following options:
  7307. @table @option
  7308. @item type
  7309. Specify whether to extract the top (if the value is @code{0} or
  7310. @code{top}) or the bottom field (if the value is @code{1} or
  7311. @code{bottom}).
  7312. @end table
  7313. @section fieldhint
  7314. Create new frames by copying the top and bottom fields from surrounding frames
  7315. supplied as numbers by the hint file.
  7316. @table @option
  7317. @item hint
  7318. Set file containing hints: absolute/relative frame numbers.
  7319. There must be one line for each frame in a clip. Each line must contain two
  7320. numbers separated by the comma, optionally followed by @code{-} or @code{+}.
  7321. Numbers supplied on each line of file can not be out of [N-1,N+1] where N
  7322. is current frame number for @code{absolute} mode or out of [-1, 1] range
  7323. for @code{relative} mode. First number tells from which frame to pick up top
  7324. field and second number tells from which frame to pick up bottom field.
  7325. If optionally followed by @code{+} output frame will be marked as interlaced,
  7326. else if followed by @code{-} output frame will be marked as progressive, else
  7327. it will be marked same as input frame.
  7328. If line starts with @code{#} or @code{;} that line is skipped.
  7329. @item mode
  7330. Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
  7331. @end table
  7332. Example of first several lines of @code{hint} file for @code{relative} mode:
  7333. @example
  7334. 0,0 - # first frame
  7335. 1,0 - # second frame, use third's frame top field and second's frame bottom field
  7336. 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
  7337. 1,0 -
  7338. 0,0 -
  7339. 0,0 -
  7340. 1,0 -
  7341. 1,0 -
  7342. 1,0 -
  7343. 0,0 -
  7344. 0,0 -
  7345. 1,0 -
  7346. 1,0 -
  7347. 1,0 -
  7348. 0,0 -
  7349. @end example
  7350. @section fieldmatch
  7351. Field matching filter for inverse telecine. It is meant to reconstruct the
  7352. progressive frames from a telecined stream. The filter does not drop duplicated
  7353. frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
  7354. followed by a decimation filter such as @ref{decimate} in the filtergraph.
  7355. The separation of the field matching and the decimation is notably motivated by
  7356. the possibility of inserting a de-interlacing filter fallback between the two.
  7357. If the source has mixed telecined and real interlaced content,
  7358. @code{fieldmatch} will not be able to match fields for the interlaced parts.
  7359. But these remaining combed frames will be marked as interlaced, and thus can be
  7360. de-interlaced by a later filter such as @ref{yadif} before decimation.
  7361. In addition to the various configuration options, @code{fieldmatch} can take an
  7362. optional second stream, activated through the @option{ppsrc} option. If
  7363. enabled, the frames reconstruction will be based on the fields and frames from
  7364. this second stream. This allows the first input to be pre-processed in order to
  7365. help the various algorithms of the filter, while keeping the output lossless
  7366. (assuming the fields are matched properly). Typically, a field-aware denoiser,
  7367. or brightness/contrast adjustments can help.
  7368. Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
  7369. and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
  7370. which @code{fieldmatch} is based on. While the semantic and usage are very
  7371. close, some behaviour and options names can differ.
  7372. The @ref{decimate} filter currently only works for constant frame rate input.
  7373. If your input has mixed telecined (30fps) and progressive content with a lower
  7374. framerate like 24fps use the following filterchain to produce the necessary cfr
  7375. stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
  7376. The filter accepts the following options:
  7377. @table @option
  7378. @item order
  7379. Specify the assumed field order of the input stream. Available values are:
  7380. @table @samp
  7381. @item auto
  7382. Auto detect parity (use FFmpeg's internal parity value).
  7383. @item bff
  7384. Assume bottom field first.
  7385. @item tff
  7386. Assume top field first.
  7387. @end table
  7388. Note that it is sometimes recommended not to trust the parity announced by the
  7389. stream.
  7390. Default value is @var{auto}.
  7391. @item mode
  7392. Set the matching mode or strategy to use. @option{pc} mode is the safest in the
  7393. sense that it won't risk creating jerkiness due to duplicate frames when
  7394. possible, but if there are bad edits or blended fields it will end up
  7395. outputting combed frames when a good match might actually exist. On the other
  7396. hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
  7397. but will almost always find a good frame if there is one. The other values are
  7398. all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
  7399. jerkiness and creating duplicate frames versus finding good matches in sections
  7400. with bad edits, orphaned fields, blended fields, etc.
  7401. More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
  7402. Available values are:
  7403. @table @samp
  7404. @item pc
  7405. 2-way matching (p/c)
  7406. @item pc_n
  7407. 2-way matching, and trying 3rd match if still combed (p/c + n)
  7408. @item pc_u
  7409. 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
  7410. @item pc_n_ub
  7411. 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
  7412. still combed (p/c + n + u/b)
  7413. @item pcn
  7414. 3-way matching (p/c/n)
  7415. @item pcn_ub
  7416. 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
  7417. detected as combed (p/c/n + u/b)
  7418. @end table
  7419. The parenthesis at the end indicate the matches that would be used for that
  7420. mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
  7421. @var{top}).
  7422. In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
  7423. the slowest.
  7424. Default value is @var{pc_n}.
  7425. @item ppsrc
  7426. Mark the main input stream as a pre-processed input, and enable the secondary
  7427. input stream as the clean source to pick the fields from. See the filter
  7428. introduction for more details. It is similar to the @option{clip2} feature from
  7429. VFM/TFM.
  7430. Default value is @code{0} (disabled).
  7431. @item field
  7432. Set the field to match from. It is recommended to set this to the same value as
  7433. @option{order} unless you experience matching failures with that setting. In
  7434. certain circumstances changing the field that is used to match from can have a
  7435. large impact on matching performance. Available values are:
  7436. @table @samp
  7437. @item auto
  7438. Automatic (same value as @option{order}).
  7439. @item bottom
  7440. Match from the bottom field.
  7441. @item top
  7442. Match from the top field.
  7443. @end table
  7444. Default value is @var{auto}.
  7445. @item mchroma
  7446. Set whether or not chroma is included during the match comparisons. In most
  7447. cases it is recommended to leave this enabled. You should set this to @code{0}
  7448. only if your clip has bad chroma problems such as heavy rainbowing or other
  7449. artifacts. Setting this to @code{0} could also be used to speed things up at
  7450. the cost of some accuracy.
  7451. Default value is @code{1}.
  7452. @item y0
  7453. @item y1
  7454. These define an exclusion band which excludes the lines between @option{y0} and
  7455. @option{y1} from being included in the field matching decision. An exclusion
  7456. band can be used to ignore subtitles, a logo, or other things that may
  7457. interfere with the matching. @option{y0} sets the starting scan line and
  7458. @option{y1} sets the ending line; all lines in between @option{y0} and
  7459. @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
  7460. @option{y0} and @option{y1} to the same value will disable the feature.
  7461. @option{y0} and @option{y1} defaults to @code{0}.
  7462. @item scthresh
  7463. Set the scene change detection threshold as a percentage of maximum change on
  7464. the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
  7465. detection is only relevant in case @option{combmatch}=@var{sc}. The range for
  7466. @option{scthresh} is @code{[0.0, 100.0]}.
  7467. Default value is @code{12.0}.
  7468. @item combmatch
  7469. When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
  7470. account the combed scores of matches when deciding what match to use as the
  7471. final match. Available values are:
  7472. @table @samp
  7473. @item none
  7474. No final matching based on combed scores.
  7475. @item sc
  7476. Combed scores are only used when a scene change is detected.
  7477. @item full
  7478. Use combed scores all the time.
  7479. @end table
  7480. Default is @var{sc}.
  7481. @item combdbg
  7482. Force @code{fieldmatch} to calculate the combed metrics for certain matches and
  7483. print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
  7484. Available values are:
  7485. @table @samp
  7486. @item none
  7487. No forced calculation.
  7488. @item pcn
  7489. Force p/c/n calculations.
  7490. @item pcnub
  7491. Force p/c/n/u/b calculations.
  7492. @end table
  7493. Default value is @var{none}.
  7494. @item cthresh
  7495. This is the area combing threshold used for combed frame detection. This
  7496. essentially controls how "strong" or "visible" combing must be to be detected.
  7497. Larger values mean combing must be more visible and smaller values mean combing
  7498. can be less visible or strong and still be detected. Valid settings are from
  7499. @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
  7500. be detected as combed). This is basically a pixel difference value. A good
  7501. range is @code{[8, 12]}.
  7502. Default value is @code{9}.
  7503. @item chroma
  7504. Sets whether or not chroma is considered in the combed frame decision. Only
  7505. disable this if your source has chroma problems (rainbowing, etc.) that are
  7506. causing problems for the combed frame detection with chroma enabled. Actually,
  7507. using @option{chroma}=@var{0} is usually more reliable, except for the case
  7508. where there is chroma only combing in the source.
  7509. Default value is @code{0}.
  7510. @item blockx
  7511. @item blocky
  7512. Respectively set the x-axis and y-axis size of the window used during combed
  7513. frame detection. This has to do with the size of the area in which
  7514. @option{combpel} pixels are required to be detected as combed for a frame to be
  7515. declared combed. See the @option{combpel} parameter description for more info.
  7516. Possible values are any number that is a power of 2 starting at 4 and going up
  7517. to 512.
  7518. Default value is @code{16}.
  7519. @item combpel
  7520. The number of combed pixels inside any of the @option{blocky} by
  7521. @option{blockx} size blocks on the frame for the frame to be detected as
  7522. combed. While @option{cthresh} controls how "visible" the combing must be, this
  7523. setting controls "how much" combing there must be in any localized area (a
  7524. window defined by the @option{blockx} and @option{blocky} settings) on the
  7525. frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
  7526. which point no frames will ever be detected as combed). This setting is known
  7527. as @option{MI} in TFM/VFM vocabulary.
  7528. Default value is @code{80}.
  7529. @end table
  7530. @anchor{p/c/n/u/b meaning}
  7531. @subsection p/c/n/u/b meaning
  7532. @subsubsection p/c/n
  7533. We assume the following telecined stream:
  7534. @example
  7535. Top fields: 1 2 2 3 4
  7536. Bottom fields: 1 2 3 4 4
  7537. @end example
  7538. The numbers correspond to the progressive frame the fields relate to. Here, the
  7539. first two frames are progressive, the 3rd and 4th are combed, and so on.
  7540. When @code{fieldmatch} is configured to run a matching from bottom
  7541. (@option{field}=@var{bottom}) this is how this input stream get transformed:
  7542. @example
  7543. Input stream:
  7544. T 1 2 2 3 4
  7545. B 1 2 3 4 4 <-- matching reference
  7546. Matches: c c n n c
  7547. Output stream:
  7548. T 1 2 3 4 4
  7549. B 1 2 3 4 4
  7550. @end example
  7551. As a result of the field matching, we can see that some frames get duplicated.
  7552. To perform a complete inverse telecine, you need to rely on a decimation filter
  7553. after this operation. See for instance the @ref{decimate} filter.
  7554. The same operation now matching from top fields (@option{field}=@var{top})
  7555. looks like this:
  7556. @example
  7557. Input stream:
  7558. T 1 2 2 3 4 <-- matching reference
  7559. B 1 2 3 4 4
  7560. Matches: c c p p c
  7561. Output stream:
  7562. T 1 2 2 3 4
  7563. B 1 2 2 3 4
  7564. @end example
  7565. In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
  7566. basically, they refer to the frame and field of the opposite parity:
  7567. @itemize
  7568. @item @var{p} matches the field of the opposite parity in the previous frame
  7569. @item @var{c} matches the field of the opposite parity in the current frame
  7570. @item @var{n} matches the field of the opposite parity in the next frame
  7571. @end itemize
  7572. @subsubsection u/b
  7573. The @var{u} and @var{b} matching are a bit special in the sense that they match
  7574. from the opposite parity flag. In the following examples, we assume that we are
  7575. currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
  7576. 'x' is placed above and below each matched fields.
  7577. With bottom matching (@option{field}=@var{bottom}):
  7578. @example
  7579. Match: c p n b u
  7580. x x x x x
  7581. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  7582. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  7583. x x x x x
  7584. Output frames:
  7585. 2 1 2 2 2
  7586. 2 2 2 1 3
  7587. @end example
  7588. With top matching (@option{field}=@var{top}):
  7589. @example
  7590. Match: c p n b u
  7591. x x x x x
  7592. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  7593. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  7594. x x x x x
  7595. Output frames:
  7596. 2 2 2 1 2
  7597. 2 1 3 2 2
  7598. @end example
  7599. @subsection Examples
  7600. Simple IVTC of a top field first telecined stream:
  7601. @example
  7602. fieldmatch=order=tff:combmatch=none, decimate
  7603. @end example
  7604. Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
  7605. @example
  7606. fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
  7607. @end example
  7608. @section fieldorder
  7609. Transform the field order of the input video.
  7610. It accepts the following parameters:
  7611. @table @option
  7612. @item order
  7613. The output field order. Valid values are @var{tff} for top field first or @var{bff}
  7614. for bottom field first.
  7615. @end table
  7616. The default value is @samp{tff}.
  7617. The transformation is done by shifting the picture content up or down
  7618. by one line, and filling the remaining line with appropriate picture content.
  7619. This method is consistent with most broadcast field order converters.
  7620. If the input video is not flagged as being interlaced, or it is already
  7621. flagged as being of the required output field order, then this filter does
  7622. not alter the incoming video.
  7623. It is very useful when converting to or from PAL DV material,
  7624. which is bottom field first.
  7625. For example:
  7626. @example
  7627. ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
  7628. @end example
  7629. @section fifo, afifo
  7630. Buffer input images and send them when they are requested.
  7631. It is mainly useful when auto-inserted by the libavfilter
  7632. framework.
  7633. It does not take parameters.
  7634. @section fillborders
  7635. Fill borders of the input video, without changing video stream dimensions.
  7636. Sometimes video can have garbage at the four edges and you may not want to
  7637. crop video input to keep size multiple of some number.
  7638. This filter accepts the following options:
  7639. @table @option
  7640. @item left
  7641. Number of pixels to fill from left border.
  7642. @item right
  7643. Number of pixels to fill from right border.
  7644. @item top
  7645. Number of pixels to fill from top border.
  7646. @item bottom
  7647. Number of pixels to fill from bottom border.
  7648. @item mode
  7649. Set fill mode.
  7650. It accepts the following values:
  7651. @table @samp
  7652. @item smear
  7653. fill pixels using outermost pixels
  7654. @item mirror
  7655. fill pixels using mirroring
  7656. @item fixed
  7657. fill pixels with constant value
  7658. @end table
  7659. Default is @var{smear}.
  7660. @item color
  7661. Set color for pixels in fixed mode. Default is @var{black}.
  7662. @end table
  7663. @section find_rect
  7664. Find a rectangular object
  7665. It accepts the following options:
  7666. @table @option
  7667. @item object
  7668. Filepath of the object image, needs to be in gray8.
  7669. @item threshold
  7670. Detection threshold, default is 0.5.
  7671. @item mipmaps
  7672. Number of mipmaps, default is 3.
  7673. @item xmin, ymin, xmax, ymax
  7674. Specifies the rectangle in which to search.
  7675. @end table
  7676. @subsection Examples
  7677. @itemize
  7678. @item
  7679. Generate a representative palette of a given video using @command{ffmpeg}:
  7680. @example
  7681. ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
  7682. @end example
  7683. @end itemize
  7684. @section cover_rect
  7685. Cover a rectangular object
  7686. It accepts the following options:
  7687. @table @option
  7688. @item cover
  7689. Filepath of the optional cover image, needs to be in yuv420.
  7690. @item mode
  7691. Set covering mode.
  7692. It accepts the following values:
  7693. @table @samp
  7694. @item cover
  7695. cover it by the supplied image
  7696. @item blur
  7697. cover it by interpolating the surrounding pixels
  7698. @end table
  7699. Default value is @var{blur}.
  7700. @end table
  7701. @subsection Examples
  7702. @itemize
  7703. @item
  7704. Generate a representative palette of a given video using @command{ffmpeg}:
  7705. @example
  7706. ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
  7707. @end example
  7708. @end itemize
  7709. @section floodfill
  7710. Flood area with values of same pixel components with another values.
  7711. It accepts the following options:
  7712. @table @option
  7713. @item x
  7714. Set pixel x coordinate.
  7715. @item y
  7716. Set pixel y coordinate.
  7717. @item s0
  7718. Set source #0 component value.
  7719. @item s1
  7720. Set source #1 component value.
  7721. @item s2
  7722. Set source #2 component value.
  7723. @item s3
  7724. Set source #3 component value.
  7725. @item d0
  7726. Set destination #0 component value.
  7727. @item d1
  7728. Set destination #1 component value.
  7729. @item d2
  7730. Set destination #2 component value.
  7731. @item d3
  7732. Set destination #3 component value.
  7733. @end table
  7734. @anchor{format}
  7735. @section format
  7736. Convert the input video to one of the specified pixel formats.
  7737. Libavfilter will try to pick one that is suitable as input to
  7738. the next filter.
  7739. It accepts the following parameters:
  7740. @table @option
  7741. @item pix_fmts
  7742. A '|'-separated list of pixel format names, such as
  7743. "pix_fmts=yuv420p|monow|rgb24".
  7744. @end table
  7745. @subsection Examples
  7746. @itemize
  7747. @item
  7748. Convert the input video to the @var{yuv420p} format
  7749. @example
  7750. format=pix_fmts=yuv420p
  7751. @end example
  7752. Convert the input video to any of the formats in the list
  7753. @example
  7754. format=pix_fmts=yuv420p|yuv444p|yuv410p
  7755. @end example
  7756. @end itemize
  7757. @anchor{fps}
  7758. @section fps
  7759. Convert the video to specified constant frame rate by duplicating or dropping
  7760. frames as necessary.
  7761. It accepts the following parameters:
  7762. @table @option
  7763. @item fps
  7764. The desired output frame rate. The default is @code{25}.
  7765. @item start_time
  7766. Assume the first PTS should be the given value, in seconds. This allows for
  7767. padding/trimming at the start of stream. By default, no assumption is made
  7768. about the first frame's expected PTS, so no padding or trimming is done.
  7769. For example, this could be set to 0 to pad the beginning with duplicates of
  7770. the first frame if a video stream starts after the audio stream or to trim any
  7771. frames with a negative PTS.
  7772. @item round
  7773. Timestamp (PTS) rounding method.
  7774. Possible values are:
  7775. @table @option
  7776. @item zero
  7777. round towards 0
  7778. @item inf
  7779. round away from 0
  7780. @item down
  7781. round towards -infinity
  7782. @item up
  7783. round towards +infinity
  7784. @item near
  7785. round to nearest
  7786. @end table
  7787. The default is @code{near}.
  7788. @item eof_action
  7789. Action performed when reading the last frame.
  7790. Possible values are:
  7791. @table @option
  7792. @item round
  7793. Use same timestamp rounding method as used for other frames.
  7794. @item pass
  7795. Pass through last frame if input duration has not been reached yet.
  7796. @end table
  7797. The default is @code{round}.
  7798. @end table
  7799. Alternatively, the options can be specified as a flat string:
  7800. @var{fps}[:@var{start_time}[:@var{round}]].
  7801. See also the @ref{setpts} filter.
  7802. @subsection Examples
  7803. @itemize
  7804. @item
  7805. A typical usage in order to set the fps to 25:
  7806. @example
  7807. fps=fps=25
  7808. @end example
  7809. @item
  7810. Sets the fps to 24, using abbreviation and rounding method to round to nearest:
  7811. @example
  7812. fps=fps=film:round=near
  7813. @end example
  7814. @end itemize
  7815. @section framepack
  7816. Pack two different video streams into a stereoscopic video, setting proper
  7817. metadata on supported codecs. The two views should have the same size and
  7818. framerate and processing will stop when the shorter video ends. Please note
  7819. that you may conveniently adjust view properties with the @ref{scale} and
  7820. @ref{fps} filters.
  7821. It accepts the following parameters:
  7822. @table @option
  7823. @item format
  7824. The desired packing format. Supported values are:
  7825. @table @option
  7826. @item sbs
  7827. The views are next to each other (default).
  7828. @item tab
  7829. The views are on top of each other.
  7830. @item lines
  7831. The views are packed by line.
  7832. @item columns
  7833. The views are packed by column.
  7834. @item frameseq
  7835. The views are temporally interleaved.
  7836. @end table
  7837. @end table
  7838. Some examples:
  7839. @example
  7840. # Convert left and right views into a frame-sequential video
  7841. ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
  7842. # Convert views into a side-by-side video with the same output resolution as the input
  7843. 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
  7844. @end example
  7845. @section framerate
  7846. Change the frame rate by interpolating new video output frames from the source
  7847. frames.
  7848. This filter is not designed to function correctly with interlaced media. If
  7849. you wish to change the frame rate of interlaced media then you are required
  7850. to deinterlace before this filter and re-interlace after this filter.
  7851. A description of the accepted options follows.
  7852. @table @option
  7853. @item fps
  7854. Specify the output frames per second. This option can also be specified
  7855. as a value alone. The default is @code{50}.
  7856. @item interp_start
  7857. Specify the start of a range where the output frame will be created as a
  7858. linear interpolation of two frames. The range is [@code{0}-@code{255}],
  7859. the default is @code{15}.
  7860. @item interp_end
  7861. Specify the end of a range where the output frame will be created as a
  7862. linear interpolation of two frames. The range is [@code{0}-@code{255}],
  7863. the default is @code{240}.
  7864. @item scene
  7865. Specify the level at which a scene change is detected as a value between
  7866. 0 and 100 to indicate a new scene; a low value reflects a low
  7867. probability for the current frame to introduce a new scene, while a higher
  7868. value means the current frame is more likely to be one.
  7869. The default is @code{8.2}.
  7870. @item flags
  7871. Specify flags influencing the filter process.
  7872. Available value for @var{flags} is:
  7873. @table @option
  7874. @item scene_change_detect, scd
  7875. Enable scene change detection using the value of the option @var{scene}.
  7876. This flag is enabled by default.
  7877. @end table
  7878. @end table
  7879. @section framestep
  7880. Select one frame every N-th frame.
  7881. This filter accepts the following option:
  7882. @table @option
  7883. @item step
  7884. Select frame after every @code{step} frames.
  7885. Allowed values are positive integers higher than 0. Default value is @code{1}.
  7886. @end table
  7887. @section freezedetect
  7888. Detect frozen video.
  7889. This filter logs a message and sets frame metadata when it detects that the
  7890. input video has no significant change in content during a specified duration.
  7891. Video freeze detection calculates the mean average absolute difference of all
  7892. the components of video frames and compares it to a noise floor.
  7893. The printed times and duration are expressed in seconds. The
  7894. @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
  7895. whose timestamp equals or exceeds the detection duration and it contains the
  7896. timestamp of the first frame of the freeze. The
  7897. @code{lavfi.freezedetect.freeze_duration} and
  7898. @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
  7899. after the freeze.
  7900. The filter accepts the following options:
  7901. @table @option
  7902. @item noise, n
  7903. Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
  7904. specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
  7905. 0.001.
  7906. @item duration, d
  7907. Set freeze duration until notification (default is 2 seconds).
  7908. @end table
  7909. @anchor{frei0r}
  7910. @section frei0r
  7911. Apply a frei0r effect to the input video.
  7912. To enable the compilation of this filter, you need to install the frei0r
  7913. header and configure FFmpeg with @code{--enable-frei0r}.
  7914. It accepts the following parameters:
  7915. @table @option
  7916. @item filter_name
  7917. The name of the frei0r effect to load. If the environment variable
  7918. @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
  7919. directories specified by the colon-separated list in @env{FREI0R_PATH}.
  7920. Otherwise, the standard frei0r paths are searched, in this order:
  7921. @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
  7922. @file{/usr/lib/frei0r-1/}.
  7923. @item filter_params
  7924. A '|'-separated list of parameters to pass to the frei0r effect.
  7925. @end table
  7926. A frei0r effect parameter can be a boolean (its value is either
  7927. "y" or "n"), a double, a color (specified as
  7928. @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
  7929. numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
  7930. @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
  7931. a position (specified as @var{X}/@var{Y}, where
  7932. @var{X} and @var{Y} are floating point numbers) and/or a string.
  7933. The number and types of parameters depend on the loaded effect. If an
  7934. effect parameter is not specified, the default value is set.
  7935. @subsection Examples
  7936. @itemize
  7937. @item
  7938. Apply the distort0r effect, setting the first two double parameters:
  7939. @example
  7940. frei0r=filter_name=distort0r:filter_params=0.5|0.01
  7941. @end example
  7942. @item
  7943. Apply the colordistance effect, taking a color as the first parameter:
  7944. @example
  7945. frei0r=colordistance:0.2/0.3/0.4
  7946. frei0r=colordistance:violet
  7947. frei0r=colordistance:0x112233
  7948. @end example
  7949. @item
  7950. Apply the perspective effect, specifying the top left and top right image
  7951. positions:
  7952. @example
  7953. frei0r=perspective:0.2/0.2|0.8/0.2
  7954. @end example
  7955. @end itemize
  7956. For more information, see
  7957. @url{http://frei0r.dyne.org}
  7958. @section fspp
  7959. Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
  7960. It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
  7961. processing filter, one of them is performed once per block, not per pixel.
  7962. This allows for much higher speed.
  7963. The filter accepts the following options:
  7964. @table @option
  7965. @item quality
  7966. Set quality. This option defines the number of levels for averaging. It accepts
  7967. an integer in the range 4-5. Default value is @code{4}.
  7968. @item qp
  7969. Force a constant quantization parameter. It accepts an integer in range 0-63.
  7970. If not set, the filter will use the QP from the video stream (if available).
  7971. @item strength
  7972. Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
  7973. more details but also more artifacts, while higher values make the image smoother
  7974. but also blurrier. Default value is @code{0} − PSNR optimal.
  7975. @item use_bframe_qp
  7976. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  7977. option may cause flicker since the B-Frames have often larger QP. Default is
  7978. @code{0} (not enabled).
  7979. @end table
  7980. @section gblur
  7981. Apply Gaussian blur filter.
  7982. The filter accepts the following options:
  7983. @table @option
  7984. @item sigma
  7985. Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
  7986. @item steps
  7987. Set number of steps for Gaussian approximation. Default is @code{1}.
  7988. @item planes
  7989. Set which planes to filter. By default all planes are filtered.
  7990. @item sigmaV
  7991. Set vertical sigma, if negative it will be same as @code{sigma}.
  7992. Default is @code{-1}.
  7993. @end table
  7994. @section geq
  7995. Apply generic equation to each pixel.
  7996. The filter accepts the following options:
  7997. @table @option
  7998. @item lum_expr, lum
  7999. Set the luminance expression.
  8000. @item cb_expr, cb
  8001. Set the chrominance blue expression.
  8002. @item cr_expr, cr
  8003. Set the chrominance red expression.
  8004. @item alpha_expr, a
  8005. Set the alpha expression.
  8006. @item red_expr, r
  8007. Set the red expression.
  8008. @item green_expr, g
  8009. Set the green expression.
  8010. @item blue_expr, b
  8011. Set the blue expression.
  8012. @end table
  8013. The colorspace is selected according to the specified options. If one
  8014. of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
  8015. options is specified, the filter will automatically select a YCbCr
  8016. colorspace. If one of the @option{red_expr}, @option{green_expr}, or
  8017. @option{blue_expr} options is specified, it will select an RGB
  8018. colorspace.
  8019. If one of the chrominance expression is not defined, it falls back on the other
  8020. one. If no alpha expression is specified it will evaluate to opaque value.
  8021. If none of chrominance expressions are specified, they will evaluate
  8022. to the luminance expression.
  8023. The expressions can use the following variables and functions:
  8024. @table @option
  8025. @item N
  8026. The sequential number of the filtered frame, starting from @code{0}.
  8027. @item X
  8028. @item Y
  8029. The coordinates of the current sample.
  8030. @item W
  8031. @item H
  8032. The width and height of the image.
  8033. @item SW
  8034. @item SH
  8035. Width and height scale depending on the currently filtered plane. It is the
  8036. ratio between the corresponding luma plane number of pixels and the current
  8037. plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
  8038. @code{0.5,0.5} for chroma planes.
  8039. @item T
  8040. Time of the current frame, expressed in seconds.
  8041. @item p(x, y)
  8042. Return the value of the pixel at location (@var{x},@var{y}) of the current
  8043. plane.
  8044. @item lum(x, y)
  8045. Return the value of the pixel at location (@var{x},@var{y}) of the luminance
  8046. plane.
  8047. @item cb(x, y)
  8048. Return the value of the pixel at location (@var{x},@var{y}) of the
  8049. blue-difference chroma plane. Return 0 if there is no such plane.
  8050. @item cr(x, y)
  8051. Return the value of the pixel at location (@var{x},@var{y}) of the
  8052. red-difference chroma plane. Return 0 if there is no such plane.
  8053. @item r(x, y)
  8054. @item g(x, y)
  8055. @item b(x, y)
  8056. Return the value of the pixel at location (@var{x},@var{y}) of the
  8057. red/green/blue component. Return 0 if there is no such component.
  8058. @item alpha(x, y)
  8059. Return the value of the pixel at location (@var{x},@var{y}) of the alpha
  8060. plane. Return 0 if there is no such plane.
  8061. @end table
  8062. For functions, if @var{x} and @var{y} are outside the area, the value will be
  8063. automatically clipped to the closer edge.
  8064. @subsection Examples
  8065. @itemize
  8066. @item
  8067. Flip the image horizontally:
  8068. @example
  8069. geq=p(W-X\,Y)
  8070. @end example
  8071. @item
  8072. Generate a bidimensional sine wave, with angle @code{PI/3} and a
  8073. wavelength of 100 pixels:
  8074. @example
  8075. geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
  8076. @end example
  8077. @item
  8078. Generate a fancy enigmatic moving light:
  8079. @example
  8080. 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
  8081. @end example
  8082. @item
  8083. Generate a quick emboss effect:
  8084. @example
  8085. format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
  8086. @end example
  8087. @item
  8088. Modify RGB components depending on pixel position:
  8089. @example
  8090. geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
  8091. @end example
  8092. @item
  8093. Create a radial gradient that is the same size as the input (also see
  8094. the @ref{vignette} filter):
  8095. @example
  8096. geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
  8097. @end example
  8098. @end itemize
  8099. @section gradfun
  8100. Fix the banding artifacts that are sometimes introduced into nearly flat
  8101. regions by truncation to 8-bit color depth.
  8102. Interpolate the gradients that should go where the bands are, and
  8103. dither them.
  8104. It is designed for playback only. Do not use it prior to
  8105. lossy compression, because compression tends to lose the dither and
  8106. bring back the bands.
  8107. It accepts the following parameters:
  8108. @table @option
  8109. @item strength
  8110. The maximum amount by which the filter will change any one pixel. This is also
  8111. the threshold for detecting nearly flat regions. Acceptable values range from
  8112. .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
  8113. valid range.
  8114. @item radius
  8115. The neighborhood to fit the gradient to. A larger radius makes for smoother
  8116. gradients, but also prevents the filter from modifying the pixels near detailed
  8117. regions. Acceptable values are 8-32; the default value is 16. Out-of-range
  8118. values will be clipped to the valid range.
  8119. @end table
  8120. Alternatively, the options can be specified as a flat string:
  8121. @var{strength}[:@var{radius}]
  8122. @subsection Examples
  8123. @itemize
  8124. @item
  8125. Apply the filter with a @code{3.5} strength and radius of @code{8}:
  8126. @example
  8127. gradfun=3.5:8
  8128. @end example
  8129. @item
  8130. Specify radius, omitting the strength (which will fall-back to the default
  8131. value):
  8132. @example
  8133. gradfun=radius=8
  8134. @end example
  8135. @end itemize
  8136. @section graphmonitor, agraphmonitor
  8137. Show various filtergraph stats.
  8138. With this filter one can debug complete filtergraph.
  8139. Especially issues with links filling with queued frames.
  8140. The filter accepts the following options:
  8141. @table @option
  8142. @item size, s
  8143. Set video output size. Default is @var{hd720}.
  8144. @item opacity, o
  8145. Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
  8146. @item mode, m
  8147. Set output mode, can be @var{fulll} or @var{compact}.
  8148. In @var{compact} mode only filters with some queued frames have displayed stats.
  8149. @item flags, f
  8150. Set flags which enable which stats are shown in video.
  8151. Available values for flags are:
  8152. @table @samp
  8153. @item queue
  8154. Display number of queued frames in each link.
  8155. @item frame_count_in
  8156. Display number of frames taken from filter.
  8157. @item frame_count_out
  8158. Display number of frames given out from filter.
  8159. @item pts
  8160. Display current filtered frame pts.
  8161. @item time
  8162. Display current filtered frame time.
  8163. @item timebase
  8164. Display time base for filter link.
  8165. @item format
  8166. Display used format for filter link.
  8167. @item size
  8168. Display video size or number of audio channels in case of audio used by filter link.
  8169. @item rate
  8170. Display video frame rate or sample rate in case of audio used by filter link.
  8171. @end table
  8172. @item rate, r
  8173. Set upper limit for video rate of output stream, Default value is @var{25}.
  8174. This guarantee that output video frame rate will not be higher than this value.
  8175. @end table
  8176. @section greyedge
  8177. A color constancy variation filter which estimates scene illumination via grey edge algorithm
  8178. and corrects the scene colors accordingly.
  8179. See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
  8180. The filter accepts the following options:
  8181. @table @option
  8182. @item difford
  8183. The order of differentiation to be applied on the scene. Must be chosen in the range
  8184. [0,2] and default value is 1.
  8185. @item minknorm
  8186. The Minkowski parameter to be used for calculating the Minkowski distance. Must
  8187. be chosen in the range [0,20] and default value is 1. Set to 0 for getting
  8188. max value instead of calculating Minkowski distance.
  8189. @item sigma
  8190. The standard deviation of Gaussian blur to be applied on the scene. Must be
  8191. chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
  8192. can't be equal to 0 if @var{difford} is greater than 0.
  8193. @end table
  8194. @subsection Examples
  8195. @itemize
  8196. @item
  8197. Grey Edge:
  8198. @example
  8199. greyedge=difford=1:minknorm=5:sigma=2
  8200. @end example
  8201. @item
  8202. Max Edge:
  8203. @example
  8204. greyedge=difford=1:minknorm=0:sigma=2
  8205. @end example
  8206. @end itemize
  8207. @anchor{haldclut}
  8208. @section haldclut
  8209. Apply a Hald CLUT to a video stream.
  8210. First input is the video stream to process, and second one is the Hald CLUT.
  8211. The Hald CLUT input can be a simple picture or a complete video stream.
  8212. The filter accepts the following options:
  8213. @table @option
  8214. @item shortest
  8215. Force termination when the shortest input terminates. Default is @code{0}.
  8216. @item repeatlast
  8217. Continue applying the last CLUT after the end of the stream. A value of
  8218. @code{0} disable the filter after the last frame of the CLUT is reached.
  8219. Default is @code{1}.
  8220. @end table
  8221. @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
  8222. filters share the same internals).
  8223. More information about the Hald CLUT can be found on Eskil Steenberg's website
  8224. (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
  8225. @subsection Workflow examples
  8226. @subsubsection Hald CLUT video stream
  8227. Generate an identity Hald CLUT stream altered with various effects:
  8228. @example
  8229. 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
  8230. @end example
  8231. Note: make sure you use a lossless codec.
  8232. Then use it with @code{haldclut} to apply it on some random stream:
  8233. @example
  8234. ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
  8235. @end example
  8236. The Hald CLUT will be applied to the 10 first seconds (duration of
  8237. @file{clut.nut}), then the latest picture of that CLUT stream will be applied
  8238. to the remaining frames of the @code{mandelbrot} stream.
  8239. @subsubsection Hald CLUT with preview
  8240. A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
  8241. @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
  8242. biggest possible square starting at the top left of the picture. The remaining
  8243. padding pixels (bottom or right) will be ignored. This area can be used to add
  8244. a preview of the Hald CLUT.
  8245. Typically, the following generated Hald CLUT will be supported by the
  8246. @code{haldclut} filter:
  8247. @example
  8248. ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
  8249. pad=iw+320 [padded_clut];
  8250. smptebars=s=320x256, split [a][b];
  8251. [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
  8252. [main][b] overlay=W-320" -frames:v 1 clut.png
  8253. @end example
  8254. It contains the original and a preview of the effect of the CLUT: SMPTE color
  8255. bars are displayed on the right-top, and below the same color bars processed by
  8256. the color changes.
  8257. Then, the effect of this Hald CLUT can be visualized with:
  8258. @example
  8259. ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
  8260. @end example
  8261. @section hflip
  8262. Flip the input video horizontally.
  8263. For example, to horizontally flip the input video with @command{ffmpeg}:
  8264. @example
  8265. ffmpeg -i in.avi -vf "hflip" out.avi
  8266. @end example
  8267. @section histeq
  8268. This filter applies a global color histogram equalization on a
  8269. per-frame basis.
  8270. It can be used to correct video that has a compressed range of pixel
  8271. intensities. The filter redistributes the pixel intensities to
  8272. equalize their distribution across the intensity range. It may be
  8273. viewed as an "automatically adjusting contrast filter". This filter is
  8274. useful only for correcting degraded or poorly captured source
  8275. video.
  8276. The filter accepts the following options:
  8277. @table @option
  8278. @item strength
  8279. Determine the amount of equalization to be applied. As the strength
  8280. is reduced, the distribution of pixel intensities more-and-more
  8281. approaches that of the input frame. The value must be a float number
  8282. in the range [0,1] and defaults to 0.200.
  8283. @item intensity
  8284. Set the maximum intensity that can generated and scale the output
  8285. values appropriately. The strength should be set as desired and then
  8286. the intensity can be limited if needed to avoid washing-out. The value
  8287. must be a float number in the range [0,1] and defaults to 0.210.
  8288. @item antibanding
  8289. Set the antibanding level. If enabled the filter will randomly vary
  8290. the luminance of output pixels by a small amount to avoid banding of
  8291. the histogram. Possible values are @code{none}, @code{weak} or
  8292. @code{strong}. It defaults to @code{none}.
  8293. @end table
  8294. @section histogram
  8295. Compute and draw a color distribution histogram for the input video.
  8296. The computed histogram is a representation of the color component
  8297. distribution in an image.
  8298. Standard histogram displays the color components distribution in an image.
  8299. Displays color graph for each color component. Shows distribution of
  8300. the Y, U, V, A or R, G, B components, depending on input format, in the
  8301. current frame. Below each graph a color component scale meter is shown.
  8302. The filter accepts the following options:
  8303. @table @option
  8304. @item level_height
  8305. Set height of level. Default value is @code{200}.
  8306. Allowed range is [50, 2048].
  8307. @item scale_height
  8308. Set height of color scale. Default value is @code{12}.
  8309. Allowed range is [0, 40].
  8310. @item display_mode
  8311. Set display mode.
  8312. It accepts the following values:
  8313. @table @samp
  8314. @item stack
  8315. Per color component graphs are placed below each other.
  8316. @item parade
  8317. Per color component graphs are placed side by side.
  8318. @item overlay
  8319. Presents information identical to that in the @code{parade}, except
  8320. that the graphs representing color components are superimposed directly
  8321. over one another.
  8322. @end table
  8323. Default is @code{stack}.
  8324. @item levels_mode
  8325. Set mode. Can be either @code{linear}, or @code{logarithmic}.
  8326. Default is @code{linear}.
  8327. @item components
  8328. Set what color components to display.
  8329. Default is @code{7}.
  8330. @item fgopacity
  8331. Set foreground opacity. Default is @code{0.7}.
  8332. @item bgopacity
  8333. Set background opacity. Default is @code{0.5}.
  8334. @end table
  8335. @subsection Examples
  8336. @itemize
  8337. @item
  8338. Calculate and draw histogram:
  8339. @example
  8340. ffplay -i input -vf histogram
  8341. @end example
  8342. @end itemize
  8343. @anchor{hqdn3d}
  8344. @section hqdn3d
  8345. This is a high precision/quality 3d denoise filter. It aims to reduce
  8346. image noise, producing smooth images and making still images really
  8347. still. It should enhance compressibility.
  8348. It accepts the following optional parameters:
  8349. @table @option
  8350. @item luma_spatial
  8351. A non-negative floating point number which specifies spatial luma strength.
  8352. It defaults to 4.0.
  8353. @item chroma_spatial
  8354. A non-negative floating point number which specifies spatial chroma strength.
  8355. It defaults to 3.0*@var{luma_spatial}/4.0.
  8356. @item luma_tmp
  8357. A floating point number which specifies luma temporal strength. It defaults to
  8358. 6.0*@var{luma_spatial}/4.0.
  8359. @item chroma_tmp
  8360. A floating point number which specifies chroma temporal strength. It defaults to
  8361. @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
  8362. @end table
  8363. @anchor{hwdownload}
  8364. @section hwdownload
  8365. Download hardware frames to system memory.
  8366. The input must be in hardware frames, and the output a non-hardware format.
  8367. Not all formats will be supported on the output - it may be necessary to insert
  8368. an additional @option{format} filter immediately following in the graph to get
  8369. the output in a supported format.
  8370. @section hwmap
  8371. Map hardware frames to system memory or to another device.
  8372. This filter has several different modes of operation; which one is used depends
  8373. on the input and output formats:
  8374. @itemize
  8375. @item
  8376. Hardware frame input, normal frame output
  8377. Map the input frames to system memory and pass them to the output. If the
  8378. original hardware frame is later required (for example, after overlaying
  8379. something else on part of it), the @option{hwmap} filter can be used again
  8380. in the next mode to retrieve it.
  8381. @item
  8382. Normal frame input, hardware frame output
  8383. If the input is actually a software-mapped hardware frame, then unmap it -
  8384. that is, return the original hardware frame.
  8385. Otherwise, a device must be provided. Create new hardware surfaces on that
  8386. device for the output, then map them back to the software format at the input
  8387. and give those frames to the preceding filter. This will then act like the
  8388. @option{hwupload} filter, but may be able to avoid an additional copy when
  8389. the input is already in a compatible format.
  8390. @item
  8391. Hardware frame input and output
  8392. A device must be supplied for the output, either directly or with the
  8393. @option{derive_device} option. The input and output devices must be of
  8394. different types and compatible - the exact meaning of this is
  8395. system-dependent, but typically it means that they must refer to the same
  8396. underlying hardware context (for example, refer to the same graphics card).
  8397. If the input frames were originally created on the output device, then unmap
  8398. to retrieve the original frames.
  8399. Otherwise, map the frames to the output device - create new hardware frames
  8400. on the output corresponding to the frames on the input.
  8401. @end itemize
  8402. The following additional parameters are accepted:
  8403. @table @option
  8404. @item mode
  8405. Set the frame mapping mode. Some combination of:
  8406. @table @var
  8407. @item read
  8408. The mapped frame should be readable.
  8409. @item write
  8410. The mapped frame should be writeable.
  8411. @item overwrite
  8412. The mapping will always overwrite the entire frame.
  8413. This may improve performance in some cases, as the original contents of the
  8414. frame need not be loaded.
  8415. @item direct
  8416. The mapping must not involve any copying.
  8417. Indirect mappings to copies of frames are created in some cases where either
  8418. direct mapping is not possible or it would have unexpected properties.
  8419. Setting this flag ensures that the mapping is direct and will fail if that is
  8420. not possible.
  8421. @end table
  8422. Defaults to @var{read+write} if not specified.
  8423. @item derive_device @var{type}
  8424. Rather than using the device supplied at initialisation, instead derive a new
  8425. device of type @var{type} from the device the input frames exist on.
  8426. @item reverse
  8427. In a hardware to hardware mapping, map in reverse - create frames in the sink
  8428. and map them back to the source. This may be necessary in some cases where
  8429. a mapping in one direction is required but only the opposite direction is
  8430. supported by the devices being used.
  8431. This option is dangerous - it may break the preceding filter in undefined
  8432. ways if there are any additional constraints on that filter's output.
  8433. Do not use it without fully understanding the implications of its use.
  8434. @end table
  8435. @anchor{hwupload}
  8436. @section hwupload
  8437. Upload system memory frames to hardware surfaces.
  8438. The device to upload to must be supplied when the filter is initialised. If
  8439. using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
  8440. option.
  8441. @anchor{hwupload_cuda}
  8442. @section hwupload_cuda
  8443. Upload system memory frames to a CUDA device.
  8444. It accepts the following optional parameters:
  8445. @table @option
  8446. @item device
  8447. The number of the CUDA device to use
  8448. @end table
  8449. @section hqx
  8450. Apply a high-quality magnification filter designed for pixel art. This filter
  8451. was originally created by Maxim Stepin.
  8452. It accepts the following option:
  8453. @table @option
  8454. @item n
  8455. Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
  8456. @code{hq3x} and @code{4} for @code{hq4x}.
  8457. Default is @code{3}.
  8458. @end table
  8459. @section hstack
  8460. Stack input videos horizontally.
  8461. All streams must be of same pixel format and of same height.
  8462. Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
  8463. to create same output.
  8464. The filter accept the following option:
  8465. @table @option
  8466. @item inputs
  8467. Set number of input streams. Default is 2.
  8468. @item shortest
  8469. If set to 1, force the output to terminate when the shortest input
  8470. terminates. Default value is 0.
  8471. @end table
  8472. @section hue
  8473. Modify the hue and/or the saturation of the input.
  8474. It accepts the following parameters:
  8475. @table @option
  8476. @item h
  8477. Specify the hue angle as a number of degrees. It accepts an expression,
  8478. and defaults to "0".
  8479. @item s
  8480. Specify the saturation in the [-10,10] range. It accepts an expression and
  8481. defaults to "1".
  8482. @item H
  8483. Specify the hue angle as a number of radians. It accepts an
  8484. expression, and defaults to "0".
  8485. @item b
  8486. Specify the brightness in the [-10,10] range. It accepts an expression and
  8487. defaults to "0".
  8488. @end table
  8489. @option{h} and @option{H} are mutually exclusive, and can't be
  8490. specified at the same time.
  8491. The @option{b}, @option{h}, @option{H} and @option{s} option values are
  8492. expressions containing the following constants:
  8493. @table @option
  8494. @item n
  8495. frame count of the input frame starting from 0
  8496. @item pts
  8497. presentation timestamp of the input frame expressed in time base units
  8498. @item r
  8499. frame rate of the input video, NAN if the input frame rate is unknown
  8500. @item t
  8501. timestamp expressed in seconds, NAN if the input timestamp is unknown
  8502. @item tb
  8503. time base of the input video
  8504. @end table
  8505. @subsection Examples
  8506. @itemize
  8507. @item
  8508. Set the hue to 90 degrees and the saturation to 1.0:
  8509. @example
  8510. hue=h=90:s=1
  8511. @end example
  8512. @item
  8513. Same command but expressing the hue in radians:
  8514. @example
  8515. hue=H=PI/2:s=1
  8516. @end example
  8517. @item
  8518. Rotate hue and make the saturation swing between 0
  8519. and 2 over a period of 1 second:
  8520. @example
  8521. hue="H=2*PI*t: s=sin(2*PI*t)+1"
  8522. @end example
  8523. @item
  8524. Apply a 3 seconds saturation fade-in effect starting at 0:
  8525. @example
  8526. hue="s=min(t/3\,1)"
  8527. @end example
  8528. The general fade-in expression can be written as:
  8529. @example
  8530. hue="s=min(0\, max((t-START)/DURATION\, 1))"
  8531. @end example
  8532. @item
  8533. Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
  8534. @example
  8535. hue="s=max(0\, min(1\, (8-t)/3))"
  8536. @end example
  8537. The general fade-out expression can be written as:
  8538. @example
  8539. hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
  8540. @end example
  8541. @end itemize
  8542. @subsection Commands
  8543. This filter supports the following commands:
  8544. @table @option
  8545. @item b
  8546. @item s
  8547. @item h
  8548. @item H
  8549. Modify the hue and/or the saturation and/or brightness of the input video.
  8550. The command accepts the same syntax of the corresponding option.
  8551. If the specified expression is not valid, it is kept at its current
  8552. value.
  8553. @end table
  8554. @section hysteresis
  8555. Grow first stream into second stream by connecting components.
  8556. This makes it possible to build more robust edge masks.
  8557. This filter accepts the following options:
  8558. @table @option
  8559. @item planes
  8560. Set which planes will be processed as bitmap, unprocessed planes will be
  8561. copied from first stream.
  8562. By default value 0xf, all planes will be processed.
  8563. @item threshold
  8564. Set threshold which is used in filtering. If pixel component value is higher than
  8565. this value filter algorithm for connecting components is activated.
  8566. By default value is 0.
  8567. @end table
  8568. @section idet
  8569. Detect video interlacing type.
  8570. This filter tries to detect if the input frames are interlaced, progressive,
  8571. top or bottom field first. It will also try to detect fields that are
  8572. repeated between adjacent frames (a sign of telecine).
  8573. Single frame detection considers only immediately adjacent frames when classifying each frame.
  8574. Multiple frame detection incorporates the classification history of previous frames.
  8575. The filter will log these metadata values:
  8576. @table @option
  8577. @item single.current_frame
  8578. Detected type of current frame using single-frame detection. One of:
  8579. ``tff'' (top field first), ``bff'' (bottom field first),
  8580. ``progressive'', or ``undetermined''
  8581. @item single.tff
  8582. Cumulative number of frames detected as top field first using single-frame detection.
  8583. @item multiple.tff
  8584. Cumulative number of frames detected as top field first using multiple-frame detection.
  8585. @item single.bff
  8586. Cumulative number of frames detected as bottom field first using single-frame detection.
  8587. @item multiple.current_frame
  8588. Detected type of current frame using multiple-frame detection. One of:
  8589. ``tff'' (top field first), ``bff'' (bottom field first),
  8590. ``progressive'', or ``undetermined''
  8591. @item multiple.bff
  8592. Cumulative number of frames detected as bottom field first using multiple-frame detection.
  8593. @item single.progressive
  8594. Cumulative number of frames detected as progressive using single-frame detection.
  8595. @item multiple.progressive
  8596. Cumulative number of frames detected as progressive using multiple-frame detection.
  8597. @item single.undetermined
  8598. Cumulative number of frames that could not be classified using single-frame detection.
  8599. @item multiple.undetermined
  8600. Cumulative number of frames that could not be classified using multiple-frame detection.
  8601. @item repeated.current_frame
  8602. Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
  8603. @item repeated.neither
  8604. Cumulative number of frames with no repeated field.
  8605. @item repeated.top
  8606. Cumulative number of frames with the top field repeated from the previous frame's top field.
  8607. @item repeated.bottom
  8608. Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
  8609. @end table
  8610. The filter accepts the following options:
  8611. @table @option
  8612. @item intl_thres
  8613. Set interlacing threshold.
  8614. @item prog_thres
  8615. Set progressive threshold.
  8616. @item rep_thres
  8617. Threshold for repeated field detection.
  8618. @item half_life
  8619. Number of frames after which a given frame's contribution to the
  8620. statistics is halved (i.e., it contributes only 0.5 to its
  8621. classification). The default of 0 means that all frames seen are given
  8622. full weight of 1.0 forever.
  8623. @item analyze_interlaced_flag
  8624. When this is not 0 then idet will use the specified number of frames to determine
  8625. if the interlaced flag is accurate, it will not count undetermined frames.
  8626. If the flag is found to be accurate it will be used without any further
  8627. computations, if it is found to be inaccurate it will be cleared without any
  8628. further computations. This allows inserting the idet filter as a low computational
  8629. method to clean up the interlaced flag
  8630. @end table
  8631. @section il
  8632. Deinterleave or interleave fields.
  8633. This filter allows one to process interlaced images fields without
  8634. deinterlacing them. Deinterleaving splits the input frame into 2
  8635. fields (so called half pictures). Odd lines are moved to the top
  8636. half of the output image, even lines to the bottom half.
  8637. You can process (filter) them independently and then re-interleave them.
  8638. The filter accepts the following options:
  8639. @table @option
  8640. @item luma_mode, l
  8641. @item chroma_mode, c
  8642. @item alpha_mode, a
  8643. Available values for @var{luma_mode}, @var{chroma_mode} and
  8644. @var{alpha_mode} are:
  8645. @table @samp
  8646. @item none
  8647. Do nothing.
  8648. @item deinterleave, d
  8649. Deinterleave fields, placing one above the other.
  8650. @item interleave, i
  8651. Interleave fields. Reverse the effect of deinterleaving.
  8652. @end table
  8653. Default value is @code{none}.
  8654. @item luma_swap, ls
  8655. @item chroma_swap, cs
  8656. @item alpha_swap, as
  8657. Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
  8658. @end table
  8659. @section inflate
  8660. Apply inflate effect to the video.
  8661. This filter replaces the pixel by the local(3x3) average by taking into account
  8662. only values higher than the pixel.
  8663. It accepts the following options:
  8664. @table @option
  8665. @item threshold0
  8666. @item threshold1
  8667. @item threshold2
  8668. @item threshold3
  8669. Limit the maximum change for each plane, default is 65535.
  8670. If 0, plane will remain unchanged.
  8671. @end table
  8672. @section interlace
  8673. Simple interlacing filter from progressive contents. This interleaves upper (or
  8674. lower) lines from odd frames with lower (or upper) lines from even frames,
  8675. halving the frame rate and preserving image height.
  8676. @example
  8677. Original Original New Frame
  8678. Frame 'j' Frame 'j+1' (tff)
  8679. ========== =========== ==================
  8680. Line 0 --------------------> Frame 'j' Line 0
  8681. Line 1 Line 1 ----> Frame 'j+1' Line 1
  8682. Line 2 ---------------------> Frame 'j' Line 2
  8683. Line 3 Line 3 ----> Frame 'j+1' Line 3
  8684. ... ... ...
  8685. New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
  8686. @end example
  8687. It accepts the following optional parameters:
  8688. @table @option
  8689. @item scan
  8690. This determines whether the interlaced frame is taken from the even
  8691. (tff - default) or odd (bff) lines of the progressive frame.
  8692. @item lowpass
  8693. Vertical lowpass filter to avoid twitter interlacing and
  8694. reduce moire patterns.
  8695. @table @samp
  8696. @item 0, off
  8697. Disable vertical lowpass filter
  8698. @item 1, linear
  8699. Enable linear filter (default)
  8700. @item 2, complex
  8701. Enable complex filter. This will slightly less reduce twitter and moire
  8702. but better retain detail and subjective sharpness impression.
  8703. @end table
  8704. @end table
  8705. @section kerndeint
  8706. Deinterlace input video by applying Donald Graft's adaptive kernel
  8707. deinterling. Work on interlaced parts of a video to produce
  8708. progressive frames.
  8709. The description of the accepted parameters follows.
  8710. @table @option
  8711. @item thresh
  8712. Set the threshold which affects the filter's tolerance when
  8713. determining if a pixel line must be processed. It must be an integer
  8714. in the range [0,255] and defaults to 10. A value of 0 will result in
  8715. applying the process on every pixels.
  8716. @item map
  8717. Paint pixels exceeding the threshold value to white if set to 1.
  8718. Default is 0.
  8719. @item order
  8720. Set the fields order. Swap fields if set to 1, leave fields alone if
  8721. 0. Default is 0.
  8722. @item sharp
  8723. Enable additional sharpening if set to 1. Default is 0.
  8724. @item twoway
  8725. Enable twoway sharpening if set to 1. Default is 0.
  8726. @end table
  8727. @subsection Examples
  8728. @itemize
  8729. @item
  8730. Apply default values:
  8731. @example
  8732. kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
  8733. @end example
  8734. @item
  8735. Enable additional sharpening:
  8736. @example
  8737. kerndeint=sharp=1
  8738. @end example
  8739. @item
  8740. Paint processed pixels in white:
  8741. @example
  8742. kerndeint=map=1
  8743. @end example
  8744. @end itemize
  8745. @section lagfun
  8746. Slowly update darker pixels.
  8747. This filter makes short flashes of light appear longer.
  8748. This filter accepts the following options:
  8749. @table @option
  8750. @item decay
  8751. Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
  8752. @item planes
  8753. Set which planes to filter. Default is all. Allowed range is from 0 to 15.
  8754. @end table
  8755. @section lenscorrection
  8756. Correct radial lens distortion
  8757. This filter can be used to correct for radial distortion as can result from the use
  8758. of wide angle lenses, and thereby re-rectify the image. To find the right parameters
  8759. one can use tools available for example as part of opencv or simply trial-and-error.
  8760. To use opencv use the calibration sample (under samples/cpp) from the opencv sources
  8761. and extract the k1 and k2 coefficients from the resulting matrix.
  8762. Note that effectively the same filter is available in the open-source tools Krita and
  8763. Digikam from the KDE project.
  8764. In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
  8765. this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
  8766. brightness distribution, so you may want to use both filters together in certain
  8767. cases, though you will have to take care of ordering, i.e. whether vignetting should
  8768. be applied before or after lens correction.
  8769. @subsection Options
  8770. The filter accepts the following options:
  8771. @table @option
  8772. @item cx
  8773. Relative x-coordinate of the focal point of the image, and thereby the center of the
  8774. distortion. This value has a range [0,1] and is expressed as fractions of the image
  8775. width. Default is 0.5.
  8776. @item cy
  8777. Relative y-coordinate of the focal point of the image, and thereby the center of the
  8778. distortion. This value has a range [0,1] and is expressed as fractions of the image
  8779. height. Default is 0.5.
  8780. @item k1
  8781. Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
  8782. no correction. Default is 0.
  8783. @item k2
  8784. Coefficient of the double quadratic correction term. This value has a range [-1,1].
  8785. 0 means no correction. Default is 0.
  8786. @end table
  8787. The formula that generates the correction is:
  8788. @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)
  8789. where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
  8790. distances from the focal point in the source and target images, respectively.
  8791. @section lensfun
  8792. Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
  8793. The @code{lensfun} filter requires the camera make, camera model, and lens model
  8794. to apply the lens correction. The filter will load the lensfun database and
  8795. query it to find the corresponding camera and lens entries in the database. As
  8796. long as these entries can be found with the given options, the filter can
  8797. perform corrections on frames. Note that incomplete strings will result in the
  8798. filter choosing the best match with the given options, and the filter will
  8799. output the chosen camera and lens models (logged with level "info"). You must
  8800. provide the make, camera model, and lens model as they are required.
  8801. The filter accepts the following options:
  8802. @table @option
  8803. @item make
  8804. The make of the camera (for example, "Canon"). This option is required.
  8805. @item model
  8806. The model of the camera (for example, "Canon EOS 100D"). This option is
  8807. required.
  8808. @item lens_model
  8809. The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
  8810. option is required.
  8811. @item mode
  8812. The type of correction to apply. The following values are valid options:
  8813. @table @samp
  8814. @item vignetting
  8815. Enables fixing lens vignetting.
  8816. @item geometry
  8817. Enables fixing lens geometry. This is the default.
  8818. @item subpixel
  8819. Enables fixing chromatic aberrations.
  8820. @item vig_geo
  8821. Enables fixing lens vignetting and lens geometry.
  8822. @item vig_subpixel
  8823. Enables fixing lens vignetting and chromatic aberrations.
  8824. @item distortion
  8825. Enables fixing both lens geometry and chromatic aberrations.
  8826. @item all
  8827. Enables all possible corrections.
  8828. @end table
  8829. @item focal_length
  8830. The focal length of the image/video (zoom; expected constant for video). For
  8831. example, a 18--55mm lens has focal length range of [18--55], so a value in that
  8832. range should be chosen when using that lens. Default 18.
  8833. @item aperture
  8834. The aperture of the image/video (expected constant for video). Note that
  8835. aperture is only used for vignetting correction. Default 3.5.
  8836. @item focus_distance
  8837. The focus distance of the image/video (expected constant for video). Note that
  8838. focus distance is only used for vignetting and only slightly affects the
  8839. vignetting correction process. If unknown, leave it at the default value (which
  8840. is 1000).
  8841. @item scale
  8842. The scale factor which is applied after transformation. After correction the
  8843. video is no longer necessarily rectangular. This parameter controls how much of
  8844. the resulting image is visible. The value 0 means that a value will be chosen
  8845. automatically such that there is little or no unmapped area in the output
  8846. image. 1.0 means that no additional scaling is done. Lower values may result
  8847. in more of the corrected image being visible, while higher values may avoid
  8848. unmapped areas in the output.
  8849. @item target_geometry
  8850. The target geometry of the output image/video. The following values are valid
  8851. options:
  8852. @table @samp
  8853. @item rectilinear (default)
  8854. @item fisheye
  8855. @item panoramic
  8856. @item equirectangular
  8857. @item fisheye_orthographic
  8858. @item fisheye_stereographic
  8859. @item fisheye_equisolid
  8860. @item fisheye_thoby
  8861. @end table
  8862. @item reverse
  8863. Apply the reverse of image correction (instead of correcting distortion, apply
  8864. it).
  8865. @item interpolation
  8866. The type of interpolation used when correcting distortion. The following values
  8867. are valid options:
  8868. @table @samp
  8869. @item nearest
  8870. @item linear (default)
  8871. @item lanczos
  8872. @end table
  8873. @end table
  8874. @subsection Examples
  8875. @itemize
  8876. @item
  8877. Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
  8878. model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
  8879. aperture of "8.0".
  8880. @example
  8881. ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
  8882. @end example
  8883. @item
  8884. Apply the same as before, but only for the first 5 seconds of video.
  8885. @example
  8886. ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov
  8887. @end example
  8888. @end itemize
  8889. @section libvmaf
  8890. Obtain the VMAF (Video Multi-Method Assessment Fusion)
  8891. score between two input videos.
  8892. The obtained VMAF score is printed through the logging system.
  8893. It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
  8894. After installing the library it can be enabled using:
  8895. @code{./configure --enable-libvmaf --enable-version3}.
  8896. If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
  8897. The filter has following options:
  8898. @table @option
  8899. @item model_path
  8900. Set the model path which is to be used for SVM.
  8901. Default value: @code{"vmaf_v0.6.1.pkl"}
  8902. @item log_path
  8903. Set the file path to be used to store logs.
  8904. @item log_fmt
  8905. Set the format of the log file (xml or json).
  8906. @item enable_transform
  8907. This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
  8908. if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
  8909. Default value: @code{false}
  8910. @item phone_model
  8911. Invokes the phone model which will generate VMAF scores higher than in the
  8912. regular model, which is more suitable for laptop, TV, etc. viewing conditions.
  8913. @item psnr
  8914. Enables computing psnr along with vmaf.
  8915. @item ssim
  8916. Enables computing ssim along with vmaf.
  8917. @item ms_ssim
  8918. Enables computing ms_ssim along with vmaf.
  8919. @item pool
  8920. Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
  8921. @item n_threads
  8922. Set number of threads to be used when computing vmaf.
  8923. @item n_subsample
  8924. Set interval for frame subsampling used when computing vmaf.
  8925. @item enable_conf_interval
  8926. Enables confidence interval.
  8927. @end table
  8928. This filter also supports the @ref{framesync} options.
  8929. On the below examples the input file @file{main.mpg} being processed is
  8930. compared with the reference file @file{ref.mpg}.
  8931. @example
  8932. ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
  8933. @end example
  8934. Example with options:
  8935. @example
  8936. ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
  8937. @end example
  8938. @section limiter
  8939. Limits the pixel components values to the specified range [min, max].
  8940. The filter accepts the following options:
  8941. @table @option
  8942. @item min
  8943. Lower bound. Defaults to the lowest allowed value for the input.
  8944. @item max
  8945. Upper bound. Defaults to the highest allowed value for the input.
  8946. @item planes
  8947. Specify which planes will be processed. Defaults to all available.
  8948. @end table
  8949. @section loop
  8950. Loop video frames.
  8951. The filter accepts the following options:
  8952. @table @option
  8953. @item loop
  8954. Set the number of loops. Setting this value to -1 will result in infinite loops.
  8955. Default is 0.
  8956. @item size
  8957. Set maximal size in number of frames. Default is 0.
  8958. @item start
  8959. Set first frame of loop. Default is 0.
  8960. @end table
  8961. @subsection Examples
  8962. @itemize
  8963. @item
  8964. Loop single first frame infinitely:
  8965. @example
  8966. loop=loop=-1:size=1:start=0
  8967. @end example
  8968. @item
  8969. Loop single first frame 10 times:
  8970. @example
  8971. loop=loop=10:size=1:start=0
  8972. @end example
  8973. @item
  8974. Loop 10 first frames 5 times:
  8975. @example
  8976. loop=loop=5:size=10:start=0
  8977. @end example
  8978. @end itemize
  8979. @section lut1d
  8980. Apply a 1D LUT to an input video.
  8981. The filter accepts the following options:
  8982. @table @option
  8983. @item file
  8984. Set the 1D LUT file name.
  8985. Currently supported formats:
  8986. @table @samp
  8987. @item cube
  8988. Iridas
  8989. @item csp
  8990. cineSpace
  8991. @end table
  8992. @item interp
  8993. Select interpolation mode.
  8994. Available values are:
  8995. @table @samp
  8996. @item nearest
  8997. Use values from the nearest defined point.
  8998. @item linear
  8999. Interpolate values using the linear interpolation.
  9000. @item cosine
  9001. Interpolate values using the cosine interpolation.
  9002. @item cubic
  9003. Interpolate values using the cubic interpolation.
  9004. @item spline
  9005. Interpolate values using the spline interpolation.
  9006. @end table
  9007. @end table
  9008. @anchor{lut3d}
  9009. @section lut3d
  9010. Apply a 3D LUT to an input video.
  9011. The filter accepts the following options:
  9012. @table @option
  9013. @item file
  9014. Set the 3D LUT file name.
  9015. Currently supported formats:
  9016. @table @samp
  9017. @item 3dl
  9018. AfterEffects
  9019. @item cube
  9020. Iridas
  9021. @item dat
  9022. DaVinci
  9023. @item m3d
  9024. Pandora
  9025. @item csp
  9026. cineSpace
  9027. @end table
  9028. @item interp
  9029. Select interpolation mode.
  9030. Available values are:
  9031. @table @samp
  9032. @item nearest
  9033. Use values from the nearest defined point.
  9034. @item trilinear
  9035. Interpolate values using the 8 points defining a cube.
  9036. @item tetrahedral
  9037. Interpolate values using a tetrahedron.
  9038. @end table
  9039. @end table
  9040. This filter also supports the @ref{framesync} options.
  9041. @section lumakey
  9042. Turn certain luma values into transparency.
  9043. The filter accepts the following options:
  9044. @table @option
  9045. @item threshold
  9046. Set the luma which will be used as base for transparency.
  9047. Default value is @code{0}.
  9048. @item tolerance
  9049. Set the range of luma values to be keyed out.
  9050. Default value is @code{0}.
  9051. @item softness
  9052. Set the range of softness. Default value is @code{0}.
  9053. Use this to control gradual transition from zero to full transparency.
  9054. @end table
  9055. @section lut, lutrgb, lutyuv
  9056. Compute a look-up table for binding each pixel component input value
  9057. to an output value, and apply it to the input video.
  9058. @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
  9059. to an RGB input video.
  9060. These filters accept the following parameters:
  9061. @table @option
  9062. @item c0
  9063. set first pixel component expression
  9064. @item c1
  9065. set second pixel component expression
  9066. @item c2
  9067. set third pixel component expression
  9068. @item c3
  9069. set fourth pixel component expression, corresponds to the alpha component
  9070. @item r
  9071. set red component expression
  9072. @item g
  9073. set green component expression
  9074. @item b
  9075. set blue component expression
  9076. @item a
  9077. alpha component expression
  9078. @item y
  9079. set Y/luminance component expression
  9080. @item u
  9081. set U/Cb component expression
  9082. @item v
  9083. set V/Cr component expression
  9084. @end table
  9085. Each of them specifies the expression to use for computing the lookup table for
  9086. the corresponding pixel component values.
  9087. The exact component associated to each of the @var{c*} options depends on the
  9088. format in input.
  9089. The @var{lut} filter requires either YUV or RGB pixel formats in input,
  9090. @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
  9091. The expressions can contain the following constants and functions:
  9092. @table @option
  9093. @item w
  9094. @item h
  9095. The input width and height.
  9096. @item val
  9097. The input value for the pixel component.
  9098. @item clipval
  9099. The input value, clipped to the @var{minval}-@var{maxval} range.
  9100. @item maxval
  9101. The maximum value for the pixel component.
  9102. @item minval
  9103. The minimum value for the pixel component.
  9104. @item negval
  9105. The negated value for the pixel component value, clipped to the
  9106. @var{minval}-@var{maxval} range; it corresponds to the expression
  9107. "maxval-clipval+minval".
  9108. @item clip(val)
  9109. The computed value in @var{val}, clipped to the
  9110. @var{minval}-@var{maxval} range.
  9111. @item gammaval(gamma)
  9112. The computed gamma correction value of the pixel component value,
  9113. clipped to the @var{minval}-@var{maxval} range. It corresponds to the
  9114. expression
  9115. "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
  9116. @end table
  9117. All expressions default to "val".
  9118. @subsection Examples
  9119. @itemize
  9120. @item
  9121. Negate input video:
  9122. @example
  9123. lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
  9124. lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
  9125. @end example
  9126. The above is the same as:
  9127. @example
  9128. lutrgb="r=negval:g=negval:b=negval"
  9129. lutyuv="y=negval:u=negval:v=negval"
  9130. @end example
  9131. @item
  9132. Negate luminance:
  9133. @example
  9134. lutyuv=y=negval
  9135. @end example
  9136. @item
  9137. Remove chroma components, turning the video into a graytone image:
  9138. @example
  9139. lutyuv="u=128:v=128"
  9140. @end example
  9141. @item
  9142. Apply a luma burning effect:
  9143. @example
  9144. lutyuv="y=2*val"
  9145. @end example
  9146. @item
  9147. Remove green and blue components:
  9148. @example
  9149. lutrgb="g=0:b=0"
  9150. @end example
  9151. @item
  9152. Set a constant alpha channel value on input:
  9153. @example
  9154. format=rgba,lutrgb=a="maxval-minval/2"
  9155. @end example
  9156. @item
  9157. Correct luminance gamma by a factor of 0.5:
  9158. @example
  9159. lutyuv=y=gammaval(0.5)
  9160. @end example
  9161. @item
  9162. Discard least significant bits of luma:
  9163. @example
  9164. lutyuv=y='bitand(val, 128+64+32)'
  9165. @end example
  9166. @item
  9167. Technicolor like effect:
  9168. @example
  9169. lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
  9170. @end example
  9171. @end itemize
  9172. @section lut2, tlut2
  9173. The @code{lut2} filter takes two input streams and outputs one
  9174. stream.
  9175. The @code{tlut2} (time lut2) filter takes two consecutive frames
  9176. from one single stream.
  9177. This filter accepts the following parameters:
  9178. @table @option
  9179. @item c0
  9180. set first pixel component expression
  9181. @item c1
  9182. set second pixel component expression
  9183. @item c2
  9184. set third pixel component expression
  9185. @item c3
  9186. set fourth pixel component expression, corresponds to the alpha component
  9187. @item d
  9188. set output bit depth, only available for @code{lut2} filter. By default is 0,
  9189. which means bit depth is automatically picked from first input format.
  9190. @end table
  9191. Each of them specifies the expression to use for computing the lookup table for
  9192. the corresponding pixel component values.
  9193. The exact component associated to each of the @var{c*} options depends on the
  9194. format in inputs.
  9195. The expressions can contain the following constants:
  9196. @table @option
  9197. @item w
  9198. @item h
  9199. The input width and height.
  9200. @item x
  9201. The first input value for the pixel component.
  9202. @item y
  9203. The second input value for the pixel component.
  9204. @item bdx
  9205. The first input video bit depth.
  9206. @item bdy
  9207. The second input video bit depth.
  9208. @end table
  9209. All expressions default to "x".
  9210. @subsection Examples
  9211. @itemize
  9212. @item
  9213. Highlight differences between two RGB video streams:
  9214. @example
  9215. 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)'
  9216. @end example
  9217. @item
  9218. Highlight differences between two YUV video streams:
  9219. @example
  9220. 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)'
  9221. @end example
  9222. @item
  9223. Show max difference between two video streams:
  9224. @example
  9225. lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'
  9226. @end example
  9227. @end itemize
  9228. @section maskedclamp
  9229. Clamp the first input stream with the second input and third input stream.
  9230. Returns the value of first stream to be between second input
  9231. stream - @code{undershoot} and third input stream + @code{overshoot}.
  9232. This filter accepts the following options:
  9233. @table @option
  9234. @item undershoot
  9235. Default value is @code{0}.
  9236. @item overshoot
  9237. Default value is @code{0}.
  9238. @item planes
  9239. Set which planes will be processed as bitmap, unprocessed planes will be
  9240. copied from first stream.
  9241. By default value 0xf, all planes will be processed.
  9242. @end table
  9243. @section maskedmerge
  9244. Merge the first input stream with the second input stream using per pixel
  9245. weights in the third input stream.
  9246. A value of 0 in the third stream pixel component means that pixel component
  9247. from first stream is returned unchanged, while maximum value (eg. 255 for
  9248. 8-bit videos) means that pixel component from second stream is returned
  9249. unchanged. Intermediate values define the amount of merging between both
  9250. input stream's pixel components.
  9251. This filter accepts the following options:
  9252. @table @option
  9253. @item planes
  9254. Set which planes will be processed as bitmap, unprocessed planes will be
  9255. copied from first stream.
  9256. By default value 0xf, all planes will be processed.
  9257. @end table
  9258. @section maskfun
  9259. Create mask from input video.
  9260. For example it is useful to create motion masks after @code{tblend} filter.
  9261. This filter accepts the following options:
  9262. @table @option
  9263. @item low
  9264. Set low threshold. Any pixel component lower or exact than this value will be set to 0.
  9265. @item high
  9266. Set high threshold. Any pixel component higher than this value will be set to max value
  9267. allowed for current pixel format.
  9268. @item planes
  9269. Set planes to filter, by default all available planes are filtered.
  9270. @item fill
  9271. Fill all frame pixels with this value.
  9272. @item sum
  9273. Set max average pixel value for frame. If sum of all pixel components is higher that this
  9274. average, output frame will be completely filled with value set by @var{fill} option.
  9275. Typically useful for scene changes when used in combination with @code{tblend} filter.
  9276. @end table
  9277. @section mcdeint
  9278. Apply motion-compensation deinterlacing.
  9279. It needs one field per frame as input and must thus be used together
  9280. with yadif=1/3 or equivalent.
  9281. This filter accepts the following options:
  9282. @table @option
  9283. @item mode
  9284. Set the deinterlacing mode.
  9285. It accepts one of the following values:
  9286. @table @samp
  9287. @item fast
  9288. @item medium
  9289. @item slow
  9290. use iterative motion estimation
  9291. @item extra_slow
  9292. like @samp{slow}, but use multiple reference frames.
  9293. @end table
  9294. Default value is @samp{fast}.
  9295. @item parity
  9296. Set the picture field parity assumed for the input video. It must be
  9297. one of the following values:
  9298. @table @samp
  9299. @item 0, tff
  9300. assume top field first
  9301. @item 1, bff
  9302. assume bottom field first
  9303. @end table
  9304. Default value is @samp{bff}.
  9305. @item qp
  9306. Set per-block quantization parameter (QP) used by the internal
  9307. encoder.
  9308. Higher values should result in a smoother motion vector field but less
  9309. optimal individual vectors. Default value is 1.
  9310. @end table
  9311. @section mergeplanes
  9312. Merge color channel components from several video streams.
  9313. The filter accepts up to 4 input streams, and merge selected input
  9314. planes to the output video.
  9315. This filter accepts the following options:
  9316. @table @option
  9317. @item mapping
  9318. Set input to output plane mapping. Default is @code{0}.
  9319. The mappings is specified as a bitmap. It should be specified as a
  9320. hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
  9321. mapping for the first plane of the output stream. 'A' sets the number of
  9322. the input stream to use (from 0 to 3), and 'a' the plane number of the
  9323. corresponding input to use (from 0 to 3). The rest of the mappings is
  9324. similar, 'Bb' describes the mapping for the output stream second
  9325. plane, 'Cc' describes the mapping for the output stream third plane and
  9326. 'Dd' describes the mapping for the output stream fourth plane.
  9327. @item format
  9328. Set output pixel format. Default is @code{yuva444p}.
  9329. @end table
  9330. @subsection Examples
  9331. @itemize
  9332. @item
  9333. Merge three gray video streams of same width and height into single video stream:
  9334. @example
  9335. [a0][a1][a2]mergeplanes=0x001020:yuv444p
  9336. @end example
  9337. @item
  9338. Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
  9339. @example
  9340. [a0][a1]mergeplanes=0x00010210:yuva444p
  9341. @end example
  9342. @item
  9343. Swap Y and A plane in yuva444p stream:
  9344. @example
  9345. format=yuva444p,mergeplanes=0x03010200:yuva444p
  9346. @end example
  9347. @item
  9348. Swap U and V plane in yuv420p stream:
  9349. @example
  9350. format=yuv420p,mergeplanes=0x000201:yuv420p
  9351. @end example
  9352. @item
  9353. Cast a rgb24 clip to yuv444p:
  9354. @example
  9355. format=rgb24,mergeplanes=0x000102:yuv444p
  9356. @end example
  9357. @end itemize
  9358. @section mestimate
  9359. Estimate and export motion vectors using block matching algorithms.
  9360. Motion vectors are stored in frame side data to be used by other filters.
  9361. This filter accepts the following options:
  9362. @table @option
  9363. @item method
  9364. Specify the motion estimation method. Accepts one of the following values:
  9365. @table @samp
  9366. @item esa
  9367. Exhaustive search algorithm.
  9368. @item tss
  9369. Three step search algorithm.
  9370. @item tdls
  9371. Two dimensional logarithmic search algorithm.
  9372. @item ntss
  9373. New three step search algorithm.
  9374. @item fss
  9375. Four step search algorithm.
  9376. @item ds
  9377. Diamond search algorithm.
  9378. @item hexbs
  9379. Hexagon-based search algorithm.
  9380. @item epzs
  9381. Enhanced predictive zonal search algorithm.
  9382. @item umh
  9383. Uneven multi-hexagon search algorithm.
  9384. @end table
  9385. Default value is @samp{esa}.
  9386. @item mb_size
  9387. Macroblock size. Default @code{16}.
  9388. @item search_param
  9389. Search parameter. Default @code{7}.
  9390. @end table
  9391. @section midequalizer
  9392. Apply Midway Image Equalization effect using two video streams.
  9393. Midway Image Equalization adjusts a pair of images to have the same
  9394. histogram, while maintaining their dynamics as much as possible. It's
  9395. useful for e.g. matching exposures from a pair of stereo cameras.
  9396. This filter has two inputs and one output, which must be of same pixel format, but
  9397. may be of different sizes. The output of filter is first input adjusted with
  9398. midway histogram of both inputs.
  9399. This filter accepts the following option:
  9400. @table @option
  9401. @item planes
  9402. Set which planes to process. Default is @code{15}, which is all available planes.
  9403. @end table
  9404. @section minterpolate
  9405. Convert the video to specified frame rate using motion interpolation.
  9406. This filter accepts the following options:
  9407. @table @option
  9408. @item fps
  9409. 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}.
  9410. @item mi_mode
  9411. Motion interpolation mode. Following values are accepted:
  9412. @table @samp
  9413. @item dup
  9414. Duplicate previous or next frame for interpolating new ones.
  9415. @item blend
  9416. Blend source frames. Interpolated frame is mean of previous and next frames.
  9417. @item mci
  9418. Motion compensated interpolation. Following options are effective when this mode is selected:
  9419. @table @samp
  9420. @item mc_mode
  9421. Motion compensation mode. Following values are accepted:
  9422. @table @samp
  9423. @item obmc
  9424. Overlapped block motion compensation.
  9425. @item aobmc
  9426. Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
  9427. @end table
  9428. Default mode is @samp{obmc}.
  9429. @item me_mode
  9430. Motion estimation mode. Following values are accepted:
  9431. @table @samp
  9432. @item bidir
  9433. Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
  9434. @item bilat
  9435. Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
  9436. @end table
  9437. Default mode is @samp{bilat}.
  9438. @item me
  9439. The algorithm to be used for motion estimation. Following values are accepted:
  9440. @table @samp
  9441. @item esa
  9442. Exhaustive search algorithm.
  9443. @item tss
  9444. Three step search algorithm.
  9445. @item tdls
  9446. Two dimensional logarithmic search algorithm.
  9447. @item ntss
  9448. New three step search algorithm.
  9449. @item fss
  9450. Four step search algorithm.
  9451. @item ds
  9452. Diamond search algorithm.
  9453. @item hexbs
  9454. Hexagon-based search algorithm.
  9455. @item epzs
  9456. Enhanced predictive zonal search algorithm.
  9457. @item umh
  9458. Uneven multi-hexagon search algorithm.
  9459. @end table
  9460. Default algorithm is @samp{epzs}.
  9461. @item mb_size
  9462. Macroblock size. Default @code{16}.
  9463. @item search_param
  9464. Motion estimation search parameter. Default @code{32}.
  9465. @item vsbmc
  9466. 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).
  9467. @end table
  9468. @end table
  9469. @item scd
  9470. 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:
  9471. @table @samp
  9472. @item none
  9473. Disable scene change detection.
  9474. @item fdiff
  9475. Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
  9476. @end table
  9477. Default method is @samp{fdiff}.
  9478. @item scd_threshold
  9479. Scene change detection threshold. Default is @code{5.0}.
  9480. @end table
  9481. @section mix
  9482. Mix several video input streams into one video stream.
  9483. A description of the accepted options follows.
  9484. @table @option
  9485. @item nb_inputs
  9486. The number of inputs. If unspecified, it defaults to 2.
  9487. @item weights
  9488. Specify weight of each input video stream as sequence.
  9489. Each weight is separated by space. If number of weights
  9490. is smaller than number of @var{frames} last specified
  9491. weight will be used for all remaining unset weights.
  9492. @item scale
  9493. Specify scale, if it is set it will be multiplied with sum
  9494. of each weight multiplied with pixel values to give final destination
  9495. pixel value. By default @var{scale} is auto scaled to sum of weights.
  9496. @item duration
  9497. Specify how end of stream is determined.
  9498. @table @samp
  9499. @item longest
  9500. The duration of the longest input. (default)
  9501. @item shortest
  9502. The duration of the shortest input.
  9503. @item first
  9504. The duration of the first input.
  9505. @end table
  9506. @end table
  9507. @section mpdecimate
  9508. Drop frames that do not differ greatly from the previous frame in
  9509. order to reduce frame rate.
  9510. The main use of this filter is for very-low-bitrate encoding
  9511. (e.g. streaming over dialup modem), but it could in theory be used for
  9512. fixing movies that were inverse-telecined incorrectly.
  9513. A description of the accepted options follows.
  9514. @table @option
  9515. @item max
  9516. Set the maximum number of consecutive frames which can be dropped (if
  9517. positive), or the minimum interval between dropped frames (if
  9518. negative). If the value is 0, the frame is dropped disregarding the
  9519. number of previous sequentially dropped frames.
  9520. Default value is 0.
  9521. @item hi
  9522. @item lo
  9523. @item frac
  9524. Set the dropping threshold values.
  9525. Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
  9526. represent actual pixel value differences, so a threshold of 64
  9527. corresponds to 1 unit of difference for each pixel, or the same spread
  9528. out differently over the block.
  9529. A frame is a candidate for dropping if no 8x8 blocks differ by more
  9530. than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
  9531. meaning the whole image) differ by more than a threshold of @option{lo}.
  9532. Default value for @option{hi} is 64*12, default value for @option{lo} is
  9533. 64*5, and default value for @option{frac} is 0.33.
  9534. @end table
  9535. @section negate
  9536. Negate (invert) the input video.
  9537. It accepts the following option:
  9538. @table @option
  9539. @item negate_alpha
  9540. With value 1, it negates the alpha component, if present. Default value is 0.
  9541. @end table
  9542. @anchor{nlmeans}
  9543. @section nlmeans
  9544. Denoise frames using Non-Local Means algorithm.
  9545. Each pixel is adjusted by looking for other pixels with similar contexts. This
  9546. context similarity is defined by comparing their surrounding patches of size
  9547. @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
  9548. around the pixel.
  9549. Note that the research area defines centers for patches, which means some
  9550. patches will be made of pixels outside that research area.
  9551. The filter accepts the following options.
  9552. @table @option
  9553. @item s
  9554. Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
  9555. @item p
  9556. Set patch size. Default is 7. Must be odd number in range [0, 99].
  9557. @item pc
  9558. Same as @option{p} but for chroma planes.
  9559. The default value is @var{0} and means automatic.
  9560. @item r
  9561. Set research size. Default is 15. Must be odd number in range [0, 99].
  9562. @item rc
  9563. Same as @option{r} but for chroma planes.
  9564. The default value is @var{0} and means automatic.
  9565. @end table
  9566. @section nnedi
  9567. Deinterlace video using neural network edge directed interpolation.
  9568. This filter accepts the following options:
  9569. @table @option
  9570. @item weights
  9571. Mandatory option, without binary file filter can not work.
  9572. Currently file can be found here:
  9573. https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
  9574. @item deint
  9575. Set which frames to deinterlace, by default it is @code{all}.
  9576. Can be @code{all} or @code{interlaced}.
  9577. @item field
  9578. Set mode of operation.
  9579. Can be one of the following:
  9580. @table @samp
  9581. @item af
  9582. Use frame flags, both fields.
  9583. @item a
  9584. Use frame flags, single field.
  9585. @item t
  9586. Use top field only.
  9587. @item b
  9588. Use bottom field only.
  9589. @item tf
  9590. Use both fields, top first.
  9591. @item bf
  9592. Use both fields, bottom first.
  9593. @end table
  9594. @item planes
  9595. Set which planes to process, by default filter process all frames.
  9596. @item nsize
  9597. Set size of local neighborhood around each pixel, used by the predictor neural
  9598. network.
  9599. Can be one of the following:
  9600. @table @samp
  9601. @item s8x6
  9602. @item s16x6
  9603. @item s32x6
  9604. @item s48x6
  9605. @item s8x4
  9606. @item s16x4
  9607. @item s32x4
  9608. @end table
  9609. @item nns
  9610. Set the number of neurons in predictor neural network.
  9611. Can be one of the following:
  9612. @table @samp
  9613. @item n16
  9614. @item n32
  9615. @item n64
  9616. @item n128
  9617. @item n256
  9618. @end table
  9619. @item qual
  9620. Controls the number of different neural network predictions that are blended
  9621. together to compute the final output value. Can be @code{fast}, default or
  9622. @code{slow}.
  9623. @item etype
  9624. Set which set of weights to use in the predictor.
  9625. Can be one of the following:
  9626. @table @samp
  9627. @item a
  9628. weights trained to minimize absolute error
  9629. @item s
  9630. weights trained to minimize squared error
  9631. @end table
  9632. @item pscrn
  9633. Controls whether or not the prescreener neural network is used to decide
  9634. which pixels should be processed by the predictor neural network and which
  9635. can be handled by simple cubic interpolation.
  9636. The prescreener is trained to know whether cubic interpolation will be
  9637. sufficient for a pixel or whether it should be predicted by the predictor nn.
  9638. The computational complexity of the prescreener nn is much less than that of
  9639. the predictor nn. Since most pixels can be handled by cubic interpolation,
  9640. using the prescreener generally results in much faster processing.
  9641. The prescreener is pretty accurate, so the difference between using it and not
  9642. using it is almost always unnoticeable.
  9643. Can be one of the following:
  9644. @table @samp
  9645. @item none
  9646. @item original
  9647. @item new
  9648. @end table
  9649. Default is @code{new}.
  9650. @item fapprox
  9651. Set various debugging flags.
  9652. @end table
  9653. @section noformat
  9654. Force libavfilter not to use any of the specified pixel formats for the
  9655. input to the next filter.
  9656. It accepts the following parameters:
  9657. @table @option
  9658. @item pix_fmts
  9659. A '|'-separated list of pixel format names, such as
  9660. pix_fmts=yuv420p|monow|rgb24".
  9661. @end table
  9662. @subsection Examples
  9663. @itemize
  9664. @item
  9665. Force libavfilter to use a format different from @var{yuv420p} for the
  9666. input to the vflip filter:
  9667. @example
  9668. noformat=pix_fmts=yuv420p,vflip
  9669. @end example
  9670. @item
  9671. Convert the input video to any of the formats not contained in the list:
  9672. @example
  9673. noformat=yuv420p|yuv444p|yuv410p
  9674. @end example
  9675. @end itemize
  9676. @section noise
  9677. Add noise on video input frame.
  9678. The filter accepts the following options:
  9679. @table @option
  9680. @item all_seed
  9681. @item c0_seed
  9682. @item c1_seed
  9683. @item c2_seed
  9684. @item c3_seed
  9685. Set noise seed for specific pixel component or all pixel components in case
  9686. of @var{all_seed}. Default value is @code{123457}.
  9687. @item all_strength, alls
  9688. @item c0_strength, c0s
  9689. @item c1_strength, c1s
  9690. @item c2_strength, c2s
  9691. @item c3_strength, c3s
  9692. Set noise strength for specific pixel component or all pixel components in case
  9693. @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
  9694. @item all_flags, allf
  9695. @item c0_flags, c0f
  9696. @item c1_flags, c1f
  9697. @item c2_flags, c2f
  9698. @item c3_flags, c3f
  9699. Set pixel component flags or set flags for all components if @var{all_flags}.
  9700. Available values for component flags are:
  9701. @table @samp
  9702. @item a
  9703. averaged temporal noise (smoother)
  9704. @item p
  9705. mix random noise with a (semi)regular pattern
  9706. @item t
  9707. temporal noise (noise pattern changes between frames)
  9708. @item u
  9709. uniform noise (gaussian otherwise)
  9710. @end table
  9711. @end table
  9712. @subsection Examples
  9713. Add temporal and uniform noise to input video:
  9714. @example
  9715. noise=alls=20:allf=t+u
  9716. @end example
  9717. @section normalize
  9718. Normalize RGB video (aka histogram stretching, contrast stretching).
  9719. See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
  9720. For each channel of each frame, the filter computes the input range and maps
  9721. it linearly to the user-specified output range. The output range defaults
  9722. to the full dynamic range from pure black to pure white.
  9723. Temporal smoothing can be used on the input range to reduce flickering (rapid
  9724. changes in brightness) caused when small dark or bright objects enter or leave
  9725. the scene. This is similar to the auto-exposure (automatic gain control) on a
  9726. video camera, and, like a video camera, it may cause a period of over- or
  9727. under-exposure of the video.
  9728. The R,G,B channels can be normalized independently, which may cause some
  9729. color shifting, or linked together as a single channel, which prevents
  9730. color shifting. Linked normalization preserves hue. Independent normalization
  9731. does not, so it can be used to remove some color casts. Independent and linked
  9732. normalization can be combined in any ratio.
  9733. The normalize filter accepts the following options:
  9734. @table @option
  9735. @item blackpt
  9736. @item whitept
  9737. Colors which define the output range. The minimum input value is mapped to
  9738. the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
  9739. The defaults are black and white respectively. Specifying white for
  9740. @var{blackpt} and black for @var{whitept} will give color-inverted,
  9741. normalized video. Shades of grey can be used to reduce the dynamic range
  9742. (contrast). Specifying saturated colors here can create some interesting
  9743. effects.
  9744. @item smoothing
  9745. The number of previous frames to use for temporal smoothing. The input range
  9746. of each channel is smoothed using a rolling average over the current frame
  9747. and the @var{smoothing} previous frames. The default is 0 (no temporal
  9748. smoothing).
  9749. @item independence
  9750. Controls the ratio of independent (color shifting) channel normalization to
  9751. linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
  9752. independent. Defaults to 1.0 (fully independent).
  9753. @item strength
  9754. Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
  9755. expensive no-op. Defaults to 1.0 (full strength).
  9756. @end table
  9757. @subsection Examples
  9758. Stretch video contrast to use the full dynamic range, with no temporal
  9759. smoothing; may flicker depending on the source content:
  9760. @example
  9761. normalize=blackpt=black:whitept=white:smoothing=0
  9762. @end example
  9763. As above, but with 50 frames of temporal smoothing; flicker should be
  9764. reduced, depending on the source content:
  9765. @example
  9766. normalize=blackpt=black:whitept=white:smoothing=50
  9767. @end example
  9768. As above, but with hue-preserving linked channel normalization:
  9769. @example
  9770. normalize=blackpt=black:whitept=white:smoothing=50:independence=0
  9771. @end example
  9772. As above, but with half strength:
  9773. @example
  9774. normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
  9775. @end example
  9776. Map the darkest input color to red, the brightest input color to cyan:
  9777. @example
  9778. normalize=blackpt=red:whitept=cyan
  9779. @end example
  9780. @section null
  9781. Pass the video source unchanged to the output.
  9782. @section ocr
  9783. Optical Character Recognition
  9784. This filter uses Tesseract for optical character recognition. To enable
  9785. compilation of this filter, you need to configure FFmpeg with
  9786. @code{--enable-libtesseract}.
  9787. It accepts the following options:
  9788. @table @option
  9789. @item datapath
  9790. Set datapath to tesseract data. Default is to use whatever was
  9791. set at installation.
  9792. @item language
  9793. Set language, default is "eng".
  9794. @item whitelist
  9795. Set character whitelist.
  9796. @item blacklist
  9797. Set character blacklist.
  9798. @end table
  9799. The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
  9800. @section ocv
  9801. Apply a video transform using libopencv.
  9802. To enable this filter, install the libopencv library and headers and
  9803. configure FFmpeg with @code{--enable-libopencv}.
  9804. It accepts the following parameters:
  9805. @table @option
  9806. @item filter_name
  9807. The name of the libopencv filter to apply.
  9808. @item filter_params
  9809. The parameters to pass to the libopencv filter. If not specified, the default
  9810. values are assumed.
  9811. @end table
  9812. Refer to the official libopencv documentation for more precise
  9813. information:
  9814. @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
  9815. Several libopencv filters are supported; see the following subsections.
  9816. @anchor{dilate}
  9817. @subsection dilate
  9818. Dilate an image by using a specific structuring element.
  9819. It corresponds to the libopencv function @code{cvDilate}.
  9820. It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
  9821. @var{struct_el} represents a structuring element, and has the syntax:
  9822. @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
  9823. @var{cols} and @var{rows} represent the number of columns and rows of
  9824. the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
  9825. point, and @var{shape} the shape for the structuring element. @var{shape}
  9826. must be "rect", "cross", "ellipse", or "custom".
  9827. If the value for @var{shape} is "custom", it must be followed by a
  9828. string of the form "=@var{filename}". The file with name
  9829. @var{filename} is assumed to represent a binary image, with each
  9830. printable character corresponding to a bright pixel. When a custom
  9831. @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
  9832. or columns and rows of the read file are assumed instead.
  9833. The default value for @var{struct_el} is "3x3+0x0/rect".
  9834. @var{nb_iterations} specifies the number of times the transform is
  9835. applied to the image, and defaults to 1.
  9836. Some examples:
  9837. @example
  9838. # Use the default values
  9839. ocv=dilate
  9840. # Dilate using a structuring element with a 5x5 cross, iterating two times
  9841. ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
  9842. # Read the shape from the file diamond.shape, iterating two times.
  9843. # The file diamond.shape may contain a pattern of characters like this
  9844. # *
  9845. # ***
  9846. # *****
  9847. # ***
  9848. # *
  9849. # The specified columns and rows are ignored
  9850. # but the anchor point coordinates are not
  9851. ocv=dilate:0x0+2x2/custom=diamond.shape|2
  9852. @end example
  9853. @subsection erode
  9854. Erode an image by using a specific structuring element.
  9855. It corresponds to the libopencv function @code{cvErode}.
  9856. It accepts the parameters: @var{struct_el}:@var{nb_iterations},
  9857. with the same syntax and semantics as the @ref{dilate} filter.
  9858. @subsection smooth
  9859. Smooth the input video.
  9860. The filter takes the following parameters:
  9861. @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
  9862. @var{type} is the type of smooth filter to apply, and must be one of
  9863. the following values: "blur", "blur_no_scale", "median", "gaussian",
  9864. or "bilateral". The default value is "gaussian".
  9865. The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
  9866. depend on the smooth type. @var{param1} and
  9867. @var{param2} accept integer positive values or 0. @var{param3} and
  9868. @var{param4} accept floating point values.
  9869. The default value for @var{param1} is 3. The default value for the
  9870. other parameters is 0.
  9871. These parameters correspond to the parameters assigned to the
  9872. libopencv function @code{cvSmooth}.
  9873. @section oscilloscope
  9874. 2D Video Oscilloscope.
  9875. Useful to measure spatial impulse, step responses, chroma delays, etc.
  9876. It accepts the following parameters:
  9877. @table @option
  9878. @item x
  9879. Set scope center x position.
  9880. @item y
  9881. Set scope center y position.
  9882. @item s
  9883. Set scope size, relative to frame diagonal.
  9884. @item t
  9885. Set scope tilt/rotation.
  9886. @item o
  9887. Set trace opacity.
  9888. @item tx
  9889. Set trace center x position.
  9890. @item ty
  9891. Set trace center y position.
  9892. @item tw
  9893. Set trace width, relative to width of frame.
  9894. @item th
  9895. Set trace height, relative to height of frame.
  9896. @item c
  9897. Set which components to trace. By default it traces first three components.
  9898. @item g
  9899. Draw trace grid. By default is enabled.
  9900. @item st
  9901. Draw some statistics. By default is enabled.
  9902. @item sc
  9903. Draw scope. By default is enabled.
  9904. @end table
  9905. @subsection Examples
  9906. @itemize
  9907. @item
  9908. Inspect full first row of video frame.
  9909. @example
  9910. oscilloscope=x=0.5:y=0:s=1
  9911. @end example
  9912. @item
  9913. Inspect full last row of video frame.
  9914. @example
  9915. oscilloscope=x=0.5:y=1:s=1
  9916. @end example
  9917. @item
  9918. Inspect full 5th line of video frame of height 1080.
  9919. @example
  9920. oscilloscope=x=0.5:y=5/1080:s=1
  9921. @end example
  9922. @item
  9923. Inspect full last column of video frame.
  9924. @example
  9925. oscilloscope=x=1:y=0.5:s=1:t=1
  9926. @end example
  9927. @end itemize
  9928. @anchor{overlay}
  9929. @section overlay
  9930. Overlay one video on top of another.
  9931. It takes two inputs and has one output. The first input is the "main"
  9932. video on which the second input is overlaid.
  9933. It accepts the following parameters:
  9934. A description of the accepted options follows.
  9935. @table @option
  9936. @item x
  9937. @item y
  9938. Set the expression for the x and y coordinates of the overlaid video
  9939. on the main video. Default value is "0" for both expressions. In case
  9940. the expression is invalid, it is set to a huge value (meaning that the
  9941. overlay will not be displayed within the output visible area).
  9942. @item eof_action
  9943. See @ref{framesync}.
  9944. @item eval
  9945. Set when the expressions for @option{x}, and @option{y} are evaluated.
  9946. It accepts the following values:
  9947. @table @samp
  9948. @item init
  9949. only evaluate expressions once during the filter initialization or
  9950. when a command is processed
  9951. @item frame
  9952. evaluate expressions for each incoming frame
  9953. @end table
  9954. Default value is @samp{frame}.
  9955. @item shortest
  9956. See @ref{framesync}.
  9957. @item format
  9958. Set the format for the output video.
  9959. It accepts the following values:
  9960. @table @samp
  9961. @item yuv420
  9962. force YUV420 output
  9963. @item yuv422
  9964. force YUV422 output
  9965. @item yuv444
  9966. force YUV444 output
  9967. @item rgb
  9968. force packed RGB output
  9969. @item gbrp
  9970. force planar RGB output
  9971. @item auto
  9972. automatically pick format
  9973. @end table
  9974. Default value is @samp{yuv420}.
  9975. @item repeatlast
  9976. See @ref{framesync}.
  9977. @item alpha
  9978. Set format of alpha of the overlaid video, it can be @var{straight} or
  9979. @var{premultiplied}. Default is @var{straight}.
  9980. @end table
  9981. The @option{x}, and @option{y} expressions can contain the following
  9982. parameters.
  9983. @table @option
  9984. @item main_w, W
  9985. @item main_h, H
  9986. The main input width and height.
  9987. @item overlay_w, w
  9988. @item overlay_h, h
  9989. The overlay input width and height.
  9990. @item x
  9991. @item y
  9992. The computed values for @var{x} and @var{y}. They are evaluated for
  9993. each new frame.
  9994. @item hsub
  9995. @item vsub
  9996. horizontal and vertical chroma subsample values of the output
  9997. format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
  9998. @var{vsub} is 1.
  9999. @item n
  10000. the number of input frame, starting from 0
  10001. @item pos
  10002. the position in the file of the input frame, NAN if unknown
  10003. @item t
  10004. The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
  10005. @end table
  10006. This filter also supports the @ref{framesync} options.
  10007. Note that the @var{n}, @var{pos}, @var{t} variables are available only
  10008. when evaluation is done @emph{per frame}, and will evaluate to NAN
  10009. when @option{eval} is set to @samp{init}.
  10010. Be aware that frames are taken from each input video in timestamp
  10011. order, hence, if their initial timestamps differ, it is a good idea
  10012. to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
  10013. have them begin in the same zero timestamp, as the example for
  10014. the @var{movie} filter does.
  10015. You can chain together more overlays but you should test the
  10016. efficiency of such approach.
  10017. @subsection Commands
  10018. This filter supports the following commands:
  10019. @table @option
  10020. @item x
  10021. @item y
  10022. Modify the x and y of the overlay input.
  10023. The command accepts the same syntax of the corresponding option.
  10024. If the specified expression is not valid, it is kept at its current
  10025. value.
  10026. @end table
  10027. @subsection Examples
  10028. @itemize
  10029. @item
  10030. Draw the overlay at 10 pixels from the bottom right corner of the main
  10031. video:
  10032. @example
  10033. overlay=main_w-overlay_w-10:main_h-overlay_h-10
  10034. @end example
  10035. Using named options the example above becomes:
  10036. @example
  10037. overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
  10038. @end example
  10039. @item
  10040. Insert a transparent PNG logo in the bottom left corner of the input,
  10041. using the @command{ffmpeg} tool with the @code{-filter_complex} option:
  10042. @example
  10043. ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
  10044. @end example
  10045. @item
  10046. Insert 2 different transparent PNG logos (second logo on bottom
  10047. right corner) using the @command{ffmpeg} tool:
  10048. @example
  10049. 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
  10050. @end example
  10051. @item
  10052. Add a transparent color layer on top of the main video; @code{WxH}
  10053. must specify the size of the main input to the overlay filter:
  10054. @example
  10055. color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
  10056. @end example
  10057. @item
  10058. Play an original video and a filtered version (here with the deshake
  10059. filter) side by side using the @command{ffplay} tool:
  10060. @example
  10061. ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
  10062. @end example
  10063. The above command is the same as:
  10064. @example
  10065. ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
  10066. @end example
  10067. @item
  10068. Make a sliding overlay appearing from the left to the right top part of the
  10069. screen starting since time 2:
  10070. @example
  10071. overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
  10072. @end example
  10073. @item
  10074. Compose output by putting two input videos side to side:
  10075. @example
  10076. ffmpeg -i left.avi -i right.avi -filter_complex "
  10077. nullsrc=size=200x100 [background];
  10078. [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
  10079. [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
  10080. [background][left] overlay=shortest=1 [background+left];
  10081. [background+left][right] overlay=shortest=1:x=100 [left+right]
  10082. "
  10083. @end example
  10084. @item
  10085. Mask 10-20 seconds of a video by applying the delogo filter to a section
  10086. @example
  10087. ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
  10088. -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]'
  10089. masked.avi
  10090. @end example
  10091. @item
  10092. Chain several overlays in cascade:
  10093. @example
  10094. nullsrc=s=200x200 [bg];
  10095. testsrc=s=100x100, split=4 [in0][in1][in2][in3];
  10096. [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
  10097. [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
  10098. [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
  10099. [in3] null, [mid2] overlay=100:100 [out0]
  10100. @end example
  10101. @end itemize
  10102. @section owdenoise
  10103. Apply Overcomplete Wavelet denoiser.
  10104. The filter accepts the following options:
  10105. @table @option
  10106. @item depth
  10107. Set depth.
  10108. Larger depth values will denoise lower frequency components more, but
  10109. slow down filtering.
  10110. Must be an int in the range 8-16, default is @code{8}.
  10111. @item luma_strength, ls
  10112. Set luma strength.
  10113. Must be a double value in the range 0-1000, default is @code{1.0}.
  10114. @item chroma_strength, cs
  10115. Set chroma strength.
  10116. Must be a double value in the range 0-1000, default is @code{1.0}.
  10117. @end table
  10118. @anchor{pad}
  10119. @section pad
  10120. Add paddings to the input image, and place the original input at the
  10121. provided @var{x}, @var{y} coordinates.
  10122. It accepts the following parameters:
  10123. @table @option
  10124. @item width, w
  10125. @item height, h
  10126. Specify an expression for the size of the output image with the
  10127. paddings added. If the value for @var{width} or @var{height} is 0, the
  10128. corresponding input size is used for the output.
  10129. The @var{width} expression can reference the value set by the
  10130. @var{height} expression, and vice versa.
  10131. The default value of @var{width} and @var{height} is 0.
  10132. @item x
  10133. @item y
  10134. Specify the offsets to place the input image at within the padded area,
  10135. with respect to the top/left border of the output image.
  10136. The @var{x} expression can reference the value set by the @var{y}
  10137. expression, and vice versa.
  10138. The default value of @var{x} and @var{y} is 0.
  10139. If @var{x} or @var{y} evaluate to a negative number, they'll be changed
  10140. so the input image is centered on the padded area.
  10141. @item color
  10142. Specify the color of the padded area. For the syntax of this option,
  10143. check the @ref{color syntax,,"Color" section in the ffmpeg-utils
  10144. manual,ffmpeg-utils}.
  10145. The default value of @var{color} is "black".
  10146. @item eval
  10147. Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
  10148. It accepts the following values:
  10149. @table @samp
  10150. @item init
  10151. Only evaluate expressions once during the filter initialization or when
  10152. a command is processed.
  10153. @item frame
  10154. Evaluate expressions for each incoming frame.
  10155. @end table
  10156. Default value is @samp{init}.
  10157. @item aspect
  10158. Pad to aspect instead to a resolution.
  10159. @end table
  10160. The value for the @var{width}, @var{height}, @var{x}, and @var{y}
  10161. options are expressions containing the following constants:
  10162. @table @option
  10163. @item in_w
  10164. @item in_h
  10165. The input video width and height.
  10166. @item iw
  10167. @item ih
  10168. These are the same as @var{in_w} and @var{in_h}.
  10169. @item out_w
  10170. @item out_h
  10171. The output width and height (the size of the padded area), as
  10172. specified by the @var{width} and @var{height} expressions.
  10173. @item ow
  10174. @item oh
  10175. These are the same as @var{out_w} and @var{out_h}.
  10176. @item x
  10177. @item y
  10178. The x and y offsets as specified by the @var{x} and @var{y}
  10179. expressions, or NAN if not yet specified.
  10180. @item a
  10181. same as @var{iw} / @var{ih}
  10182. @item sar
  10183. input sample aspect ratio
  10184. @item dar
  10185. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  10186. @item hsub
  10187. @item vsub
  10188. The horizontal and vertical chroma subsample values. For example for the
  10189. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  10190. @end table
  10191. @subsection Examples
  10192. @itemize
  10193. @item
  10194. Add paddings with the color "violet" to the input video. The output video
  10195. size is 640x480, and the top-left corner of the input video is placed at
  10196. column 0, row 40
  10197. @example
  10198. pad=640:480:0:40:violet
  10199. @end example
  10200. The example above is equivalent to the following command:
  10201. @example
  10202. pad=width=640:height=480:x=0:y=40:color=violet
  10203. @end example
  10204. @item
  10205. Pad the input to get an output with dimensions increased by 3/2,
  10206. and put the input video at the center of the padded area:
  10207. @example
  10208. pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
  10209. @end example
  10210. @item
  10211. Pad the input to get a squared output with size equal to the maximum
  10212. value between the input width and height, and put the input video at
  10213. the center of the padded area:
  10214. @example
  10215. pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
  10216. @end example
  10217. @item
  10218. Pad the input to get a final w/h ratio of 16:9:
  10219. @example
  10220. pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
  10221. @end example
  10222. @item
  10223. In case of anamorphic video, in order to set the output display aspect
  10224. correctly, it is necessary to use @var{sar} in the expression,
  10225. according to the relation:
  10226. @example
  10227. (ih * X / ih) * sar = output_dar
  10228. X = output_dar / sar
  10229. @end example
  10230. Thus the previous example needs to be modified to:
  10231. @example
  10232. pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
  10233. @end example
  10234. @item
  10235. Double the output size and put the input video in the bottom-right
  10236. corner of the output padded area:
  10237. @example
  10238. pad="2*iw:2*ih:ow-iw:oh-ih"
  10239. @end example
  10240. @end itemize
  10241. @anchor{palettegen}
  10242. @section palettegen
  10243. Generate one palette for a whole video stream.
  10244. It accepts the following options:
  10245. @table @option
  10246. @item max_colors
  10247. Set the maximum number of colors to quantize in the palette.
  10248. Note: the palette will still contain 256 colors; the unused palette entries
  10249. will be black.
  10250. @item reserve_transparent
  10251. Create a palette of 255 colors maximum and reserve the last one for
  10252. transparency. Reserving the transparency color is useful for GIF optimization.
  10253. If not set, the maximum of colors in the palette will be 256. You probably want
  10254. to disable this option for a standalone image.
  10255. Set by default.
  10256. @item transparency_color
  10257. Set the color that will be used as background for transparency.
  10258. @item stats_mode
  10259. Set statistics mode.
  10260. It accepts the following values:
  10261. @table @samp
  10262. @item full
  10263. Compute full frame histograms.
  10264. @item diff
  10265. Compute histograms only for the part that differs from previous frame. This
  10266. might be relevant to give more importance to the moving part of your input if
  10267. the background is static.
  10268. @item single
  10269. Compute new histogram for each frame.
  10270. @end table
  10271. Default value is @var{full}.
  10272. @end table
  10273. The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
  10274. (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
  10275. color quantization of the palette. This information is also visible at
  10276. @var{info} logging level.
  10277. @subsection Examples
  10278. @itemize
  10279. @item
  10280. Generate a representative palette of a given video using @command{ffmpeg}:
  10281. @example
  10282. ffmpeg -i input.mkv -vf palettegen palette.png
  10283. @end example
  10284. @end itemize
  10285. @section paletteuse
  10286. Use a palette to downsample an input video stream.
  10287. The filter takes two inputs: one video stream and a palette. The palette must
  10288. be a 256 pixels image.
  10289. It accepts the following options:
  10290. @table @option
  10291. @item dither
  10292. Select dithering mode. Available algorithms are:
  10293. @table @samp
  10294. @item bayer
  10295. Ordered 8x8 bayer dithering (deterministic)
  10296. @item heckbert
  10297. Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
  10298. Note: this dithering is sometimes considered "wrong" and is included as a
  10299. reference.
  10300. @item floyd_steinberg
  10301. Floyd and Steingberg dithering (error diffusion)
  10302. @item sierra2
  10303. Frankie Sierra dithering v2 (error diffusion)
  10304. @item sierra2_4a
  10305. Frankie Sierra dithering v2 "Lite" (error diffusion)
  10306. @end table
  10307. Default is @var{sierra2_4a}.
  10308. @item bayer_scale
  10309. When @var{bayer} dithering is selected, this option defines the scale of the
  10310. pattern (how much the crosshatch pattern is visible). A low value means more
  10311. visible pattern for less banding, and higher value means less visible pattern
  10312. at the cost of more banding.
  10313. The option must be an integer value in the range [0,5]. Default is @var{2}.
  10314. @item diff_mode
  10315. If set, define the zone to process
  10316. @table @samp
  10317. @item rectangle
  10318. Only the changing rectangle will be reprocessed. This is similar to GIF
  10319. cropping/offsetting compression mechanism. This option can be useful for speed
  10320. if only a part of the image is changing, and has use cases such as limiting the
  10321. scope of the error diffusal @option{dither} to the rectangle that bounds the
  10322. moving scene (it leads to more deterministic output if the scene doesn't change
  10323. much, and as a result less moving noise and better GIF compression).
  10324. @end table
  10325. Default is @var{none}.
  10326. @item new
  10327. Take new palette for each output frame.
  10328. @item alpha_threshold
  10329. Sets the alpha threshold for transparency. Alpha values above this threshold
  10330. will be treated as completely opaque, and values below this threshold will be
  10331. treated as completely transparent.
  10332. The option must be an integer value in the range [0,255]. Default is @var{128}.
  10333. @end table
  10334. @subsection Examples
  10335. @itemize
  10336. @item
  10337. Use a palette (generated for example with @ref{palettegen}) to encode a GIF
  10338. using @command{ffmpeg}:
  10339. @example
  10340. ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
  10341. @end example
  10342. @end itemize
  10343. @section perspective
  10344. Correct perspective of video not recorded perpendicular to the screen.
  10345. A description of the accepted parameters follows.
  10346. @table @option
  10347. @item x0
  10348. @item y0
  10349. @item x1
  10350. @item y1
  10351. @item x2
  10352. @item y2
  10353. @item x3
  10354. @item y3
  10355. Set coordinates expression for top left, top right, bottom left and bottom right corners.
  10356. Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
  10357. If the @code{sense} option is set to @code{source}, then the specified points will be sent
  10358. to the corners of the destination. If the @code{sense} option is set to @code{destination},
  10359. then the corners of the source will be sent to the specified coordinates.
  10360. The expressions can use the following variables:
  10361. @table @option
  10362. @item W
  10363. @item H
  10364. the width and height of video frame.
  10365. @item in
  10366. Input frame count.
  10367. @item on
  10368. Output frame count.
  10369. @end table
  10370. @item interpolation
  10371. Set interpolation for perspective correction.
  10372. It accepts the following values:
  10373. @table @samp
  10374. @item linear
  10375. @item cubic
  10376. @end table
  10377. Default value is @samp{linear}.
  10378. @item sense
  10379. Set interpretation of coordinate options.
  10380. It accepts the following values:
  10381. @table @samp
  10382. @item 0, source
  10383. Send point in the source specified by the given coordinates to
  10384. the corners of the destination.
  10385. @item 1, destination
  10386. Send the corners of the source to the point in the destination specified
  10387. by the given coordinates.
  10388. Default value is @samp{source}.
  10389. @end table
  10390. @item eval
  10391. Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
  10392. It accepts the following values:
  10393. @table @samp
  10394. @item init
  10395. only evaluate expressions once during the filter initialization or
  10396. when a command is processed
  10397. @item frame
  10398. evaluate expressions for each incoming frame
  10399. @end table
  10400. Default value is @samp{init}.
  10401. @end table
  10402. @section phase
  10403. Delay interlaced video by one field time so that the field order changes.
  10404. The intended use is to fix PAL movies that have been captured with the
  10405. opposite field order to the film-to-video transfer.
  10406. A description of the accepted parameters follows.
  10407. @table @option
  10408. @item mode
  10409. Set phase mode.
  10410. It accepts the following values:
  10411. @table @samp
  10412. @item t
  10413. Capture field order top-first, transfer bottom-first.
  10414. Filter will delay the bottom field.
  10415. @item b
  10416. Capture field order bottom-first, transfer top-first.
  10417. Filter will delay the top field.
  10418. @item p
  10419. Capture and transfer with the same field order. This mode only exists
  10420. for the documentation of the other options to refer to, but if you
  10421. actually select it, the filter will faithfully do nothing.
  10422. @item a
  10423. Capture field order determined automatically by field flags, transfer
  10424. opposite.
  10425. Filter selects among @samp{t} and @samp{b} modes on a frame by frame
  10426. basis using field flags. If no field information is available,
  10427. then this works just like @samp{u}.
  10428. @item u
  10429. Capture unknown or varying, transfer opposite.
  10430. Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
  10431. analyzing the images and selecting the alternative that produces best
  10432. match between the fields.
  10433. @item T
  10434. Capture top-first, transfer unknown or varying.
  10435. Filter selects among @samp{t} and @samp{p} using image analysis.
  10436. @item B
  10437. Capture bottom-first, transfer unknown or varying.
  10438. Filter selects among @samp{b} and @samp{p} using image analysis.
  10439. @item A
  10440. Capture determined by field flags, transfer unknown or varying.
  10441. Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
  10442. image analysis. If no field information is available, then this works just
  10443. like @samp{U}. This is the default mode.
  10444. @item U
  10445. Both capture and transfer unknown or varying.
  10446. Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
  10447. @end table
  10448. @end table
  10449. @section pixdesctest
  10450. Pixel format descriptor test filter, mainly useful for internal
  10451. testing. The output video should be equal to the input video.
  10452. For example:
  10453. @example
  10454. format=monow, pixdesctest
  10455. @end example
  10456. can be used to test the monowhite pixel format descriptor definition.
  10457. @section pixscope
  10458. Display sample values of color channels. Mainly useful for checking color
  10459. and levels. Minimum supported resolution is 640x480.
  10460. The filters accept the following options:
  10461. @table @option
  10462. @item x
  10463. Set scope X position, relative offset on X axis.
  10464. @item y
  10465. Set scope Y position, relative offset on Y axis.
  10466. @item w
  10467. Set scope width.
  10468. @item h
  10469. Set scope height.
  10470. @item o
  10471. Set window opacity. This window also holds statistics about pixel area.
  10472. @item wx
  10473. Set window X position, relative offset on X axis.
  10474. @item wy
  10475. Set window Y position, relative offset on Y axis.
  10476. @end table
  10477. @section pp
  10478. Enable the specified chain of postprocessing subfilters using libpostproc. This
  10479. library should be automatically selected with a GPL build (@code{--enable-gpl}).
  10480. Subfilters must be separated by '/' and can be disabled by prepending a '-'.
  10481. Each subfilter and some options have a short and a long name that can be used
  10482. interchangeably, i.e. dr/dering are the same.
  10483. The filters accept the following options:
  10484. @table @option
  10485. @item subfilters
  10486. Set postprocessing subfilters string.
  10487. @end table
  10488. All subfilters share common options to determine their scope:
  10489. @table @option
  10490. @item a/autoq
  10491. Honor the quality commands for this subfilter.
  10492. @item c/chrom
  10493. Do chrominance filtering, too (default).
  10494. @item y/nochrom
  10495. Do luminance filtering only (no chrominance).
  10496. @item n/noluma
  10497. Do chrominance filtering only (no luminance).
  10498. @end table
  10499. These options can be appended after the subfilter name, separated by a '|'.
  10500. Available subfilters are:
  10501. @table @option
  10502. @item hb/hdeblock[|difference[|flatness]]
  10503. Horizontal deblocking filter
  10504. @table @option
  10505. @item difference
  10506. Difference factor where higher values mean more deblocking (default: @code{32}).
  10507. @item flatness
  10508. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  10509. @end table
  10510. @item vb/vdeblock[|difference[|flatness]]
  10511. Vertical deblocking filter
  10512. @table @option
  10513. @item difference
  10514. Difference factor where higher values mean more deblocking (default: @code{32}).
  10515. @item flatness
  10516. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  10517. @end table
  10518. @item ha/hadeblock[|difference[|flatness]]
  10519. Accurate horizontal deblocking filter
  10520. @table @option
  10521. @item difference
  10522. Difference factor where higher values mean more deblocking (default: @code{32}).
  10523. @item flatness
  10524. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  10525. @end table
  10526. @item va/vadeblock[|difference[|flatness]]
  10527. Accurate vertical deblocking filter
  10528. @table @option
  10529. @item difference
  10530. Difference factor where higher values mean more deblocking (default: @code{32}).
  10531. @item flatness
  10532. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  10533. @end table
  10534. @end table
  10535. The horizontal and vertical deblocking filters share the difference and
  10536. flatness values so you cannot set different horizontal and vertical
  10537. thresholds.
  10538. @table @option
  10539. @item h1/x1hdeblock
  10540. Experimental horizontal deblocking filter
  10541. @item v1/x1vdeblock
  10542. Experimental vertical deblocking filter
  10543. @item dr/dering
  10544. Deringing filter
  10545. @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
  10546. @table @option
  10547. @item threshold1
  10548. larger -> stronger filtering
  10549. @item threshold2
  10550. larger -> stronger filtering
  10551. @item threshold3
  10552. larger -> stronger filtering
  10553. @end table
  10554. @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
  10555. @table @option
  10556. @item f/fullyrange
  10557. Stretch luminance to @code{0-255}.
  10558. @end table
  10559. @item lb/linblenddeint
  10560. Linear blend deinterlacing filter that deinterlaces the given block by
  10561. filtering all lines with a @code{(1 2 1)} filter.
  10562. @item li/linipoldeint
  10563. Linear interpolating deinterlacing filter that deinterlaces the given block by
  10564. linearly interpolating every second line.
  10565. @item ci/cubicipoldeint
  10566. Cubic interpolating deinterlacing filter deinterlaces the given block by
  10567. cubically interpolating every second line.
  10568. @item md/mediandeint
  10569. Median deinterlacing filter that deinterlaces the given block by applying a
  10570. median filter to every second line.
  10571. @item fd/ffmpegdeint
  10572. FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
  10573. second line with a @code{(-1 4 2 4 -1)} filter.
  10574. @item l5/lowpass5
  10575. Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
  10576. block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
  10577. @item fq/forceQuant[|quantizer]
  10578. Overrides the quantizer table from the input with the constant quantizer you
  10579. specify.
  10580. @table @option
  10581. @item quantizer
  10582. Quantizer to use
  10583. @end table
  10584. @item de/default
  10585. Default pp filter combination (@code{hb|a,vb|a,dr|a})
  10586. @item fa/fast
  10587. Fast pp filter combination (@code{h1|a,v1|a,dr|a})
  10588. @item ac
  10589. High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
  10590. @end table
  10591. @subsection Examples
  10592. @itemize
  10593. @item
  10594. Apply horizontal and vertical deblocking, deringing and automatic
  10595. brightness/contrast:
  10596. @example
  10597. pp=hb/vb/dr/al
  10598. @end example
  10599. @item
  10600. Apply default filters without brightness/contrast correction:
  10601. @example
  10602. pp=de/-al
  10603. @end example
  10604. @item
  10605. Apply default filters and temporal denoiser:
  10606. @example
  10607. pp=default/tmpnoise|1|2|3
  10608. @end example
  10609. @item
  10610. Apply deblocking on luminance only, and switch vertical deblocking on or off
  10611. automatically depending on available CPU time:
  10612. @example
  10613. pp=hb|y/vb|a
  10614. @end example
  10615. @end itemize
  10616. @section pp7
  10617. Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
  10618. similar to spp = 6 with 7 point DCT, where only the center sample is
  10619. used after IDCT.
  10620. The filter accepts the following options:
  10621. @table @option
  10622. @item qp
  10623. Force a constant quantization parameter. It accepts an integer in range
  10624. 0 to 63. If not set, the filter will use the QP from the video stream
  10625. (if available).
  10626. @item mode
  10627. Set thresholding mode. Available modes are:
  10628. @table @samp
  10629. @item hard
  10630. Set hard thresholding.
  10631. @item soft
  10632. Set soft thresholding (better de-ringing effect, but likely blurrier).
  10633. @item medium
  10634. Set medium thresholding (good results, default).
  10635. @end table
  10636. @end table
  10637. @section premultiply
  10638. Apply alpha premultiply effect to input video stream using first plane
  10639. of second stream as alpha.
  10640. Both streams must have same dimensions and same pixel format.
  10641. The filter accepts the following option:
  10642. @table @option
  10643. @item planes
  10644. Set which planes will be processed, unprocessed planes will be copied.
  10645. By default value 0xf, all planes will be processed.
  10646. @item inplace
  10647. Do not require 2nd input for processing, instead use alpha plane from input stream.
  10648. @end table
  10649. @section prewitt
  10650. Apply prewitt operator to input video stream.
  10651. The filter accepts the following option:
  10652. @table @option
  10653. @item planes
  10654. Set which planes will be processed, unprocessed planes will be copied.
  10655. By default value 0xf, all planes will be processed.
  10656. @item scale
  10657. Set value which will be multiplied with filtered result.
  10658. @item delta
  10659. Set value which will be added to filtered result.
  10660. @end table
  10661. @anchor{program_opencl}
  10662. @section program_opencl
  10663. Filter video using an OpenCL program.
  10664. @table @option
  10665. @item source
  10666. OpenCL program source file.
  10667. @item kernel
  10668. Kernel name in program.
  10669. @item inputs
  10670. Number of inputs to the filter. Defaults to 1.
  10671. @item size, s
  10672. Size of output frames. Defaults to the same as the first input.
  10673. @end table
  10674. The program source file must contain a kernel function with the given name,
  10675. which will be run once for each plane of the output. Each run on a plane
  10676. gets enqueued as a separate 2D global NDRange with one work-item for each
  10677. pixel to be generated. The global ID offset for each work-item is therefore
  10678. the coordinates of a pixel in the destination image.
  10679. The kernel function needs to take the following arguments:
  10680. @itemize
  10681. @item
  10682. Destination image, @var{__write_only image2d_t}.
  10683. This image will become the output; the kernel should write all of it.
  10684. @item
  10685. Frame index, @var{unsigned int}.
  10686. This is a counter starting from zero and increasing by one for each frame.
  10687. @item
  10688. Source images, @var{__read_only image2d_t}.
  10689. These are the most recent images on each input. The kernel may read from
  10690. them to generate the output, but they can't be written to.
  10691. @end itemize
  10692. Example programs:
  10693. @itemize
  10694. @item
  10695. Copy the input to the output (output must be the same size as the input).
  10696. @verbatim
  10697. __kernel void copy(__write_only image2d_t destination,
  10698. unsigned int index,
  10699. __read_only image2d_t source)
  10700. {
  10701. const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
  10702. int2 location = (int2)(get_global_id(0), get_global_id(1));
  10703. float4 value = read_imagef(source, sampler, location);
  10704. write_imagef(destination, location, value);
  10705. }
  10706. @end verbatim
  10707. @item
  10708. Apply a simple transformation, rotating the input by an amount increasing
  10709. with the index counter. Pixel values are linearly interpolated by the
  10710. sampler, and the output need not have the same dimensions as the input.
  10711. @verbatim
  10712. __kernel void rotate_image(__write_only image2d_t dst,
  10713. unsigned int index,
  10714. __read_only image2d_t src)
  10715. {
  10716. const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
  10717. CLK_FILTER_LINEAR);
  10718. float angle = (float)index / 100.0f;
  10719. float2 dst_dim = convert_float2(get_image_dim(dst));
  10720. float2 src_dim = convert_float2(get_image_dim(src));
  10721. float2 dst_cen = dst_dim / 2.0f;
  10722. float2 src_cen = src_dim / 2.0f;
  10723. int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
  10724. float2 dst_pos = convert_float2(dst_loc) - dst_cen;
  10725. float2 src_pos = {
  10726. cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
  10727. sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
  10728. };
  10729. src_pos = src_pos * src_dim / dst_dim;
  10730. float2 src_loc = src_pos + src_cen;
  10731. if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
  10732. src_loc.x > src_dim.x || src_loc.y > src_dim.y)
  10733. write_imagef(dst, dst_loc, 0.5f);
  10734. else
  10735. write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
  10736. }
  10737. @end verbatim
  10738. @item
  10739. Blend two inputs together, with the amount of each input used varying
  10740. with the index counter.
  10741. @verbatim
  10742. __kernel void blend_images(__write_only image2d_t dst,
  10743. unsigned int index,
  10744. __read_only image2d_t src1,
  10745. __read_only image2d_t src2)
  10746. {
  10747. const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
  10748. CLK_FILTER_LINEAR);
  10749. float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
  10750. int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
  10751. int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
  10752. int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
  10753. float4 val1 = read_imagef(src1, sampler, src1_loc);
  10754. float4 val2 = read_imagef(src2, sampler, src2_loc);
  10755. write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
  10756. }
  10757. @end verbatim
  10758. @end itemize
  10759. @section pseudocolor
  10760. Alter frame colors in video with pseudocolors.
  10761. This filter accept the following options:
  10762. @table @option
  10763. @item c0
  10764. set pixel first component expression
  10765. @item c1
  10766. set pixel second component expression
  10767. @item c2
  10768. set pixel third component expression
  10769. @item c3
  10770. set pixel fourth component expression, corresponds to the alpha component
  10771. @item i
  10772. set component to use as base for altering colors
  10773. @end table
  10774. Each of them specifies the expression to use for computing the lookup table for
  10775. the corresponding pixel component values.
  10776. The expressions can contain the following constants and functions:
  10777. @table @option
  10778. @item w
  10779. @item h
  10780. The input width and height.
  10781. @item val
  10782. The input value for the pixel component.
  10783. @item ymin, umin, vmin, amin
  10784. The minimum allowed component value.
  10785. @item ymax, umax, vmax, amax
  10786. The maximum allowed component value.
  10787. @end table
  10788. All expressions default to "val".
  10789. @subsection Examples
  10790. @itemize
  10791. @item
  10792. Change too high luma values to gradient:
  10793. @example
  10794. pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
  10795. @end example
  10796. @end itemize
  10797. @section psnr
  10798. Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
  10799. Ratio) between two input videos.
  10800. This filter takes in input two input videos, the first input is
  10801. considered the "main" source and is passed unchanged to the
  10802. output. The second input is used as a "reference" video for computing
  10803. the PSNR.
  10804. Both video inputs must have the same resolution and pixel format for
  10805. this filter to work correctly. Also it assumes that both inputs
  10806. have the same number of frames, which are compared one by one.
  10807. The obtained average PSNR is printed through the logging system.
  10808. The filter stores the accumulated MSE (mean squared error) of each
  10809. frame, and at the end of the processing it is averaged across all frames
  10810. equally, and the following formula is applied to obtain the PSNR:
  10811. @example
  10812. PSNR = 10*log10(MAX^2/MSE)
  10813. @end example
  10814. Where MAX is the average of the maximum values of each component of the
  10815. image.
  10816. The description of the accepted parameters follows.
  10817. @table @option
  10818. @item stats_file, f
  10819. If specified the filter will use the named file to save the PSNR of
  10820. each individual frame. When filename equals "-" the data is sent to
  10821. standard output.
  10822. @item stats_version
  10823. Specifies which version of the stats file format to use. Details of
  10824. each format are written below.
  10825. Default value is 1.
  10826. @item stats_add_max
  10827. Determines whether the max value is output to the stats log.
  10828. Default value is 0.
  10829. Requires stats_version >= 2. If this is set and stats_version < 2,
  10830. the filter will return an error.
  10831. @end table
  10832. This filter also supports the @ref{framesync} options.
  10833. The file printed if @var{stats_file} is selected, contains a sequence of
  10834. key/value pairs of the form @var{key}:@var{value} for each compared
  10835. couple of frames.
  10836. If a @var{stats_version} greater than 1 is specified, a header line precedes
  10837. the list of per-frame-pair stats, with key value pairs following the frame
  10838. format with the following parameters:
  10839. @table @option
  10840. @item psnr_log_version
  10841. The version of the log file format. Will match @var{stats_version}.
  10842. @item fields
  10843. A comma separated list of the per-frame-pair parameters included in
  10844. the log.
  10845. @end table
  10846. A description of each shown per-frame-pair parameter follows:
  10847. @table @option
  10848. @item n
  10849. sequential number of the input frame, starting from 1
  10850. @item mse_avg
  10851. Mean Square Error pixel-by-pixel average difference of the compared
  10852. frames, averaged over all the image components.
  10853. @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
  10854. Mean Square Error pixel-by-pixel average difference of the compared
  10855. frames for the component specified by the suffix.
  10856. @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
  10857. Peak Signal to Noise ratio of the compared frames for the component
  10858. specified by the suffix.
  10859. @item max_avg, max_y, max_u, max_v
  10860. Maximum allowed value for each channel, and average over all
  10861. channels.
  10862. @end table
  10863. For example:
  10864. @example
  10865. movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
  10866. [main][ref] psnr="stats_file=stats.log" [out]
  10867. @end example
  10868. On this example the input file being processed is compared with the
  10869. reference file @file{ref_movie.mpg}. The PSNR of each individual frame
  10870. is stored in @file{stats.log}.
  10871. @anchor{pullup}
  10872. @section pullup
  10873. Pulldown reversal (inverse telecine) filter, capable of handling mixed
  10874. hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
  10875. content.
  10876. The pullup filter is designed to take advantage of future context in making
  10877. its decisions. This filter is stateless in the sense that it does not lock
  10878. onto a pattern to follow, but it instead looks forward to the following
  10879. fields in order to identify matches and rebuild progressive frames.
  10880. To produce content with an even framerate, insert the fps filter after
  10881. pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
  10882. @code{fps=24} for 30fps and the (rare) telecined 25fps input.
  10883. The filter accepts the following options:
  10884. @table @option
  10885. @item jl
  10886. @item jr
  10887. @item jt
  10888. @item jb
  10889. These options set the amount of "junk" to ignore at the left, right, top, and
  10890. bottom of the image, respectively. Left and right are in units of 8 pixels,
  10891. while top and bottom are in units of 2 lines.
  10892. The default is 8 pixels on each side.
  10893. @item sb
  10894. Set the strict breaks. Setting this option to 1 will reduce the chances of
  10895. filter generating an occasional mismatched frame, but it may also cause an
  10896. excessive number of frames to be dropped during high motion sequences.
  10897. Conversely, setting it to -1 will make filter match fields more easily.
  10898. This may help processing of video where there is slight blurring between
  10899. the fields, but may also cause there to be interlaced frames in the output.
  10900. Default value is @code{0}.
  10901. @item mp
  10902. Set the metric plane to use. It accepts the following values:
  10903. @table @samp
  10904. @item l
  10905. Use luma plane.
  10906. @item u
  10907. Use chroma blue plane.
  10908. @item v
  10909. Use chroma red plane.
  10910. @end table
  10911. This option may be set to use chroma plane instead of the default luma plane
  10912. for doing filter's computations. This may improve accuracy on very clean
  10913. source material, but more likely will decrease accuracy, especially if there
  10914. is chroma noise (rainbow effect) or any grayscale video.
  10915. The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
  10916. load and make pullup usable in realtime on slow machines.
  10917. @end table
  10918. For best results (without duplicated frames in the output file) it is
  10919. necessary to change the output frame rate. For example, to inverse
  10920. telecine NTSC input:
  10921. @example
  10922. ffmpeg -i input -vf pullup -r 24000/1001 ...
  10923. @end example
  10924. @section qp
  10925. Change video quantization parameters (QP).
  10926. The filter accepts the following option:
  10927. @table @option
  10928. @item qp
  10929. Set expression for quantization parameter.
  10930. @end table
  10931. The expression is evaluated through the eval API and can contain, among others,
  10932. the following constants:
  10933. @table @var
  10934. @item known
  10935. 1 if index is not 129, 0 otherwise.
  10936. @item qp
  10937. Sequential index starting from -129 to 128.
  10938. @end table
  10939. @subsection Examples
  10940. @itemize
  10941. @item
  10942. Some equation like:
  10943. @example
  10944. qp=2+2*sin(PI*qp)
  10945. @end example
  10946. @end itemize
  10947. @section random
  10948. Flush video frames from internal cache of frames into a random order.
  10949. No frame is discarded.
  10950. Inspired by @ref{frei0r} nervous filter.
  10951. @table @option
  10952. @item frames
  10953. Set size in number of frames of internal cache, in range from @code{2} to
  10954. @code{512}. Default is @code{30}.
  10955. @item seed
  10956. Set seed for random number generator, must be an integer included between
  10957. @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
  10958. less than @code{0}, the filter will try to use a good random seed on a
  10959. best effort basis.
  10960. @end table
  10961. @section readeia608
  10962. Read closed captioning (EIA-608) information from the top lines of a video frame.
  10963. This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
  10964. @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
  10965. with EIA-608 data (starting from 0). A description of each metadata value follows:
  10966. @table @option
  10967. @item lavfi.readeia608.X.cc
  10968. The two bytes stored as EIA-608 data (printed in hexadecimal).
  10969. @item lavfi.readeia608.X.line
  10970. The number of the line on which the EIA-608 data was identified and read.
  10971. @end table
  10972. This filter accepts the following options:
  10973. @table @option
  10974. @item scan_min
  10975. Set the line to start scanning for EIA-608 data. Default is @code{0}.
  10976. @item scan_max
  10977. Set the line to end scanning for EIA-608 data. Default is @code{29}.
  10978. @item mac
  10979. Set minimal acceptable amplitude change for sync codes detection.
  10980. Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
  10981. @item spw
  10982. Set the ratio of width reserved for sync code detection.
  10983. Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
  10984. @item mhd
  10985. Set the max peaks height difference for sync code detection.
  10986. Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
  10987. @item mpd
  10988. Set max peaks period difference for sync code detection.
  10989. Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
  10990. @item msd
  10991. Set the first two max start code bits differences.
  10992. Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
  10993. @item bhd
  10994. Set the minimum ratio of bits height compared to 3rd start code bit.
  10995. Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
  10996. @item th_w
  10997. Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
  10998. @item th_b
  10999. Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
  11000. @item chp
  11001. Enable checking the parity bit. In the event of a parity error, the filter will output
  11002. @code{0x00} for that character. Default is false.
  11003. @end table
  11004. @subsection Examples
  11005. @itemize
  11006. @item
  11007. Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
  11008. @example
  11009. ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pkt_pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv
  11010. @end example
  11011. @end itemize
  11012. @section readvitc
  11013. Read vertical interval timecode (VITC) information from the top lines of a
  11014. video frame.
  11015. The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
  11016. timecode value, if a valid timecode has been detected. Further metadata key
  11017. @code{lavfi.readvitc.found} is set to 0/1 depending on whether
  11018. timecode data has been found or not.
  11019. This filter accepts the following options:
  11020. @table @option
  11021. @item scan_max
  11022. Set the maximum number of lines to scan for VITC data. If the value is set to
  11023. @code{-1} the full video frame is scanned. Default is @code{45}.
  11024. @item thr_b
  11025. Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
  11026. default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
  11027. @item thr_w
  11028. Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
  11029. default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
  11030. @end table
  11031. @subsection Examples
  11032. @itemize
  11033. @item
  11034. Detect and draw VITC data onto the video frame; if no valid VITC is detected,
  11035. draw @code{--:--:--:--} as a placeholder:
  11036. @example
  11037. ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
  11038. @end example
  11039. @end itemize
  11040. @section remap
  11041. Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
  11042. Destination pixel at position (X, Y) will be picked from source (x, y) position
  11043. where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
  11044. value for pixel will be used for destination pixel.
  11045. Xmap and Ymap input video streams must be of same dimensions. Output video stream
  11046. will have Xmap/Ymap video stream dimensions.
  11047. Xmap and Ymap input video streams are 16bit depth, single channel.
  11048. @section removegrain
  11049. The removegrain filter is a spatial denoiser for progressive video.
  11050. @table @option
  11051. @item m0
  11052. Set mode for the first plane.
  11053. @item m1
  11054. Set mode for the second plane.
  11055. @item m2
  11056. Set mode for the third plane.
  11057. @item m3
  11058. Set mode for the fourth plane.
  11059. @end table
  11060. Range of mode is from 0 to 24. Description of each mode follows:
  11061. @table @var
  11062. @item 0
  11063. Leave input plane unchanged. Default.
  11064. @item 1
  11065. Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
  11066. @item 2
  11067. Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
  11068. @item 3
  11069. Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
  11070. @item 4
  11071. Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
  11072. This is equivalent to a median filter.
  11073. @item 5
  11074. Line-sensitive clipping giving the minimal change.
  11075. @item 6
  11076. Line-sensitive clipping, intermediate.
  11077. @item 7
  11078. Line-sensitive clipping, intermediate.
  11079. @item 8
  11080. Line-sensitive clipping, intermediate.
  11081. @item 9
  11082. Line-sensitive clipping on a line where the neighbours pixels are the closest.
  11083. @item 10
  11084. Replaces the target pixel with the closest neighbour.
  11085. @item 11
  11086. [1 2 1] horizontal and vertical kernel blur.
  11087. @item 12
  11088. Same as mode 11.
  11089. @item 13
  11090. Bob mode, interpolates top field from the line where the neighbours
  11091. pixels are the closest.
  11092. @item 14
  11093. Bob mode, interpolates bottom field from the line where the neighbours
  11094. pixels are the closest.
  11095. @item 15
  11096. Bob mode, interpolates top field. Same as 13 but with a more complicated
  11097. interpolation formula.
  11098. @item 16
  11099. Bob mode, interpolates bottom field. Same as 14 but with a more complicated
  11100. interpolation formula.
  11101. @item 17
  11102. Clips the pixel with the minimum and maximum of respectively the maximum and
  11103. minimum of each pair of opposite neighbour pixels.
  11104. @item 18
  11105. Line-sensitive clipping using opposite neighbours whose greatest distance from
  11106. the current pixel is minimal.
  11107. @item 19
  11108. Replaces the pixel with the average of its 8 neighbours.
  11109. @item 20
  11110. Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
  11111. @item 21
  11112. Clips pixels using the averages of opposite neighbour.
  11113. @item 22
  11114. Same as mode 21 but simpler and faster.
  11115. @item 23
  11116. Small edge and halo removal, but reputed useless.
  11117. @item 24
  11118. Similar as 23.
  11119. @end table
  11120. @section removelogo
  11121. Suppress a TV station logo, using an image file to determine which
  11122. pixels comprise the logo. It works by filling in the pixels that
  11123. comprise the logo with neighboring pixels.
  11124. The filter accepts the following options:
  11125. @table @option
  11126. @item filename, f
  11127. Set the filter bitmap file, which can be any image format supported by
  11128. libavformat. The width and height of the image file must match those of the
  11129. video stream being processed.
  11130. @end table
  11131. Pixels in the provided bitmap image with a value of zero are not
  11132. considered part of the logo, non-zero pixels are considered part of
  11133. the logo. If you use white (255) for the logo and black (0) for the
  11134. rest, you will be safe. For making the filter bitmap, it is
  11135. recommended to take a screen capture of a black frame with the logo
  11136. visible, and then using a threshold filter followed by the erode
  11137. filter once or twice.
  11138. If needed, little splotches can be fixed manually. Remember that if
  11139. logo pixels are not covered, the filter quality will be much
  11140. reduced. Marking too many pixels as part of the logo does not hurt as
  11141. much, but it will increase the amount of blurring needed to cover over
  11142. the image and will destroy more information than necessary, and extra
  11143. pixels will slow things down on a large logo.
  11144. @section repeatfields
  11145. This filter uses the repeat_field flag from the Video ES headers and hard repeats
  11146. fields based on its value.
  11147. @section reverse
  11148. Reverse a video clip.
  11149. Warning: This filter requires memory to buffer the entire clip, so trimming
  11150. is suggested.
  11151. @subsection Examples
  11152. @itemize
  11153. @item
  11154. Take the first 5 seconds of a clip, and reverse it.
  11155. @example
  11156. trim=end=5,reverse
  11157. @end example
  11158. @end itemize
  11159. @section rgbashift
  11160. Shift R/G/B/A pixels horizontally and/or vertically.
  11161. The filter accepts the following options:
  11162. @table @option
  11163. @item rh
  11164. Set amount to shift red horizontally.
  11165. @item rv
  11166. Set amount to shift red vertically.
  11167. @item gh
  11168. Set amount to shift green horizontally.
  11169. @item gv
  11170. Set amount to shift green vertically.
  11171. @item bh
  11172. Set amount to shift blue horizontally.
  11173. @item bv
  11174. Set amount to shift blue vertically.
  11175. @item ah
  11176. Set amount to shift alpha horizontally.
  11177. @item av
  11178. Set amount to shift alpha vertically.
  11179. @item edge
  11180. Set edge mode, can be @var{smear}, default, or @var{warp}.
  11181. @end table
  11182. @section roberts
  11183. Apply roberts cross operator to input video stream.
  11184. The filter accepts the following option:
  11185. @table @option
  11186. @item planes
  11187. Set which planes will be processed, unprocessed planes will be copied.
  11188. By default value 0xf, all planes will be processed.
  11189. @item scale
  11190. Set value which will be multiplied with filtered result.
  11191. @item delta
  11192. Set value which will be added to filtered result.
  11193. @end table
  11194. @section rotate
  11195. Rotate video by an arbitrary angle expressed in radians.
  11196. The filter accepts the following options:
  11197. A description of the optional parameters follows.
  11198. @table @option
  11199. @item angle, a
  11200. Set an expression for the angle by which to rotate the input video
  11201. clockwise, expressed as a number of radians. A negative value will
  11202. result in a counter-clockwise rotation. By default it is set to "0".
  11203. This expression is evaluated for each frame.
  11204. @item out_w, ow
  11205. Set the output width expression, default value is "iw".
  11206. This expression is evaluated just once during configuration.
  11207. @item out_h, oh
  11208. Set the output height expression, default value is "ih".
  11209. This expression is evaluated just once during configuration.
  11210. @item bilinear
  11211. Enable bilinear interpolation if set to 1, a value of 0 disables
  11212. it. Default value is 1.
  11213. @item fillcolor, c
  11214. Set the color used to fill the output area not covered by the rotated
  11215. image. For the general syntax of this option, check the
  11216. @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11217. If the special value "none" is selected then no
  11218. background is printed (useful for example if the background is never shown).
  11219. Default value is "black".
  11220. @end table
  11221. The expressions for the angle and the output size can contain the
  11222. following constants and functions:
  11223. @table @option
  11224. @item n
  11225. sequential number of the input frame, starting from 0. It is always NAN
  11226. before the first frame is filtered.
  11227. @item t
  11228. time in seconds of the input frame, it is set to 0 when the filter is
  11229. configured. It is always NAN before the first frame is filtered.
  11230. @item hsub
  11231. @item vsub
  11232. horizontal and vertical chroma subsample values. For example for the
  11233. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11234. @item in_w, iw
  11235. @item in_h, ih
  11236. the input video width and height
  11237. @item out_w, ow
  11238. @item out_h, oh
  11239. the output width and height, that is the size of the padded area as
  11240. specified by the @var{width} and @var{height} expressions
  11241. @item rotw(a)
  11242. @item roth(a)
  11243. the minimal width/height required for completely containing the input
  11244. video rotated by @var{a} radians.
  11245. These are only available when computing the @option{out_w} and
  11246. @option{out_h} expressions.
  11247. @end table
  11248. @subsection Examples
  11249. @itemize
  11250. @item
  11251. Rotate the input by PI/6 radians clockwise:
  11252. @example
  11253. rotate=PI/6
  11254. @end example
  11255. @item
  11256. Rotate the input by PI/6 radians counter-clockwise:
  11257. @example
  11258. rotate=-PI/6
  11259. @end example
  11260. @item
  11261. Rotate the input by 45 degrees clockwise:
  11262. @example
  11263. rotate=45*PI/180
  11264. @end example
  11265. @item
  11266. Apply a constant rotation with period T, starting from an angle of PI/3:
  11267. @example
  11268. rotate=PI/3+2*PI*t/T
  11269. @end example
  11270. @item
  11271. Make the input video rotation oscillating with a period of T
  11272. seconds and an amplitude of A radians:
  11273. @example
  11274. rotate=A*sin(2*PI/T*t)
  11275. @end example
  11276. @item
  11277. Rotate the video, output size is chosen so that the whole rotating
  11278. input video is always completely contained in the output:
  11279. @example
  11280. rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
  11281. @end example
  11282. @item
  11283. Rotate the video, reduce the output size so that no background is ever
  11284. shown:
  11285. @example
  11286. rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
  11287. @end example
  11288. @end itemize
  11289. @subsection Commands
  11290. The filter supports the following commands:
  11291. @table @option
  11292. @item a, angle
  11293. Set the angle expression.
  11294. The command accepts the same syntax of the corresponding option.
  11295. If the specified expression is not valid, it is kept at its current
  11296. value.
  11297. @end table
  11298. @section sab
  11299. Apply Shape Adaptive Blur.
  11300. The filter accepts the following options:
  11301. @table @option
  11302. @item luma_radius, lr
  11303. Set luma blur filter strength, must be a value in range 0.1-4.0, default
  11304. value is 1.0. A greater value will result in a more blurred image, and
  11305. in slower processing.
  11306. @item luma_pre_filter_radius, lpfr
  11307. Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
  11308. value is 1.0.
  11309. @item luma_strength, ls
  11310. Set luma maximum difference between pixels to still be considered, must
  11311. be a value in the 0.1-100.0 range, default value is 1.0.
  11312. @item chroma_radius, cr
  11313. Set chroma blur filter strength, must be a value in range -0.9-4.0. A
  11314. greater value will result in a more blurred image, and in slower
  11315. processing.
  11316. @item chroma_pre_filter_radius, cpfr
  11317. Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
  11318. @item chroma_strength, cs
  11319. Set chroma maximum difference between pixels to still be considered,
  11320. must be a value in the -0.9-100.0 range.
  11321. @end table
  11322. Each chroma option value, if not explicitly specified, is set to the
  11323. corresponding luma option value.
  11324. @anchor{scale}
  11325. @section scale
  11326. Scale (resize) the input video, using the libswscale library.
  11327. The scale filter forces the output display aspect ratio to be the same
  11328. of the input, by changing the output sample aspect ratio.
  11329. If the input image format is different from the format requested by
  11330. the next filter, the scale filter will convert the input to the
  11331. requested format.
  11332. @subsection Options
  11333. The filter accepts the following options, or any of the options
  11334. supported by the libswscale scaler.
  11335. See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
  11336. the complete list of scaler options.
  11337. @table @option
  11338. @item width, w
  11339. @item height, h
  11340. Set the output video dimension expression. Default value is the input
  11341. dimension.
  11342. If the @var{width} or @var{w} value is 0, the input width is used for
  11343. the output. If the @var{height} or @var{h} value is 0, the input height
  11344. is used for the output.
  11345. If one and only one of the values is -n with n >= 1, the scale filter
  11346. will use a value that maintains the aspect ratio of the input image,
  11347. calculated from the other specified dimension. After that it will,
  11348. however, make sure that the calculated dimension is divisible by n and
  11349. adjust the value if necessary.
  11350. If both values are -n with n >= 1, the behavior will be identical to
  11351. both values being set to 0 as previously detailed.
  11352. See below for the list of accepted constants for use in the dimension
  11353. expression.
  11354. @item eval
  11355. Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
  11356. @table @samp
  11357. @item init
  11358. Only evaluate expressions once during the filter initialization or when a command is processed.
  11359. @item frame
  11360. Evaluate expressions for each incoming frame.
  11361. @end table
  11362. Default value is @samp{init}.
  11363. @item interl
  11364. Set the interlacing mode. It accepts the following values:
  11365. @table @samp
  11366. @item 1
  11367. Force interlaced aware scaling.
  11368. @item 0
  11369. Do not apply interlaced scaling.
  11370. @item -1
  11371. Select interlaced aware scaling depending on whether the source frames
  11372. are flagged as interlaced or not.
  11373. @end table
  11374. Default value is @samp{0}.
  11375. @item flags
  11376. Set libswscale scaling flags. See
  11377. @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
  11378. complete list of values. If not explicitly specified the filter applies
  11379. the default flags.
  11380. @item param0, param1
  11381. Set libswscale input parameters for scaling algorithms that need them. See
  11382. @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
  11383. complete documentation. If not explicitly specified the filter applies
  11384. empty parameters.
  11385. @item size, s
  11386. Set the video size. For the syntax of this option, check the
  11387. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11388. @item in_color_matrix
  11389. @item out_color_matrix
  11390. Set in/output YCbCr color space type.
  11391. This allows the autodetected value to be overridden as well as allows forcing
  11392. a specific value used for the output and encoder.
  11393. If not specified, the color space type depends on the pixel format.
  11394. Possible values:
  11395. @table @samp
  11396. @item auto
  11397. Choose automatically.
  11398. @item bt709
  11399. Format conforming to International Telecommunication Union (ITU)
  11400. Recommendation BT.709.
  11401. @item fcc
  11402. Set color space conforming to the United States Federal Communications
  11403. Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
  11404. @item bt601
  11405. Set color space conforming to:
  11406. @itemize
  11407. @item
  11408. ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
  11409. @item
  11410. ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
  11411. @item
  11412. Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
  11413. @end itemize
  11414. @item smpte240m
  11415. Set color space conforming to SMPTE ST 240:1999.
  11416. @end table
  11417. @item in_range
  11418. @item out_range
  11419. Set in/output YCbCr sample range.
  11420. This allows the autodetected value to be overridden as well as allows forcing
  11421. a specific value used for the output and encoder. If not specified, the
  11422. range depends on the pixel format. Possible values:
  11423. @table @samp
  11424. @item auto/unknown
  11425. Choose automatically.
  11426. @item jpeg/full/pc
  11427. Set full range (0-255 in case of 8-bit luma).
  11428. @item mpeg/limited/tv
  11429. Set "MPEG" range (16-235 in case of 8-bit luma).
  11430. @end table
  11431. @item force_original_aspect_ratio
  11432. Enable decreasing or increasing output video width or height if necessary to
  11433. keep the original aspect ratio. Possible values:
  11434. @table @samp
  11435. @item disable
  11436. Scale the video as specified and disable this feature.
  11437. @item decrease
  11438. The output video dimensions will automatically be decreased if needed.
  11439. @item increase
  11440. The output video dimensions will automatically be increased if needed.
  11441. @end table
  11442. One useful instance of this option is that when you know a specific device's
  11443. maximum allowed resolution, you can use this to limit the output video to
  11444. that, while retaining the aspect ratio. For example, device A allows
  11445. 1280x720 playback, and your video is 1920x800. Using this option (set it to
  11446. decrease) and specifying 1280x720 to the command line makes the output
  11447. 1280x533.
  11448. Please note that this is a different thing than specifying -1 for @option{w}
  11449. or @option{h}, you still need to specify the output resolution for this option
  11450. to work.
  11451. @end table
  11452. The values of the @option{w} and @option{h} options are expressions
  11453. containing the following constants:
  11454. @table @var
  11455. @item in_w
  11456. @item in_h
  11457. The input width and height
  11458. @item iw
  11459. @item ih
  11460. These are the same as @var{in_w} and @var{in_h}.
  11461. @item out_w
  11462. @item out_h
  11463. The output (scaled) width and height
  11464. @item ow
  11465. @item oh
  11466. These are the same as @var{out_w} and @var{out_h}
  11467. @item a
  11468. The same as @var{iw} / @var{ih}
  11469. @item sar
  11470. input sample aspect ratio
  11471. @item dar
  11472. The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
  11473. @item hsub
  11474. @item vsub
  11475. horizontal and vertical input chroma subsample values. For example for the
  11476. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11477. @item ohsub
  11478. @item ovsub
  11479. horizontal and vertical output chroma subsample values. For example for the
  11480. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11481. @end table
  11482. @subsection Examples
  11483. @itemize
  11484. @item
  11485. Scale the input video to a size of 200x100
  11486. @example
  11487. scale=w=200:h=100
  11488. @end example
  11489. This is equivalent to:
  11490. @example
  11491. scale=200:100
  11492. @end example
  11493. or:
  11494. @example
  11495. scale=200x100
  11496. @end example
  11497. @item
  11498. Specify a size abbreviation for the output size:
  11499. @example
  11500. scale=qcif
  11501. @end example
  11502. which can also be written as:
  11503. @example
  11504. scale=size=qcif
  11505. @end example
  11506. @item
  11507. Scale the input to 2x:
  11508. @example
  11509. scale=w=2*iw:h=2*ih
  11510. @end example
  11511. @item
  11512. The above is the same as:
  11513. @example
  11514. scale=2*in_w:2*in_h
  11515. @end example
  11516. @item
  11517. Scale the input to 2x with forced interlaced scaling:
  11518. @example
  11519. scale=2*iw:2*ih:interl=1
  11520. @end example
  11521. @item
  11522. Scale the input to half size:
  11523. @example
  11524. scale=w=iw/2:h=ih/2
  11525. @end example
  11526. @item
  11527. Increase the width, and set the height to the same size:
  11528. @example
  11529. scale=3/2*iw:ow
  11530. @end example
  11531. @item
  11532. Seek Greek harmony:
  11533. @example
  11534. scale=iw:1/PHI*iw
  11535. scale=ih*PHI:ih
  11536. @end example
  11537. @item
  11538. Increase the height, and set the width to 3/2 of the height:
  11539. @example
  11540. scale=w=3/2*oh:h=3/5*ih
  11541. @end example
  11542. @item
  11543. Increase the size, making the size a multiple of the chroma
  11544. subsample values:
  11545. @example
  11546. scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
  11547. @end example
  11548. @item
  11549. Increase the width to a maximum of 500 pixels,
  11550. keeping the same aspect ratio as the input:
  11551. @example
  11552. scale=w='min(500\, iw*3/2):h=-1'
  11553. @end example
  11554. @item
  11555. Make pixels square by combining scale and setsar:
  11556. @example
  11557. scale='trunc(ih*dar):ih',setsar=1/1
  11558. @end example
  11559. @item
  11560. Make pixels square by combining scale and setsar,
  11561. making sure the resulting resolution is even (required by some codecs):
  11562. @example
  11563. scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
  11564. @end example
  11565. @end itemize
  11566. @subsection Commands
  11567. This filter supports the following commands:
  11568. @table @option
  11569. @item width, w
  11570. @item height, h
  11571. Set the output video dimension expression.
  11572. The command accepts the same syntax of the corresponding option.
  11573. If the specified expression is not valid, it is kept at its current
  11574. value.
  11575. @end table
  11576. @section scale_npp
  11577. Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
  11578. format conversion on CUDA video frames. Setting the output width and height
  11579. works in the same way as for the @var{scale} filter.
  11580. The following additional options are accepted:
  11581. @table @option
  11582. @item format
  11583. The pixel format of the output CUDA frames. If set to the string "same" (the
  11584. default), the input format will be kept. Note that automatic format negotiation
  11585. and conversion is not yet supported for hardware frames
  11586. @item interp_algo
  11587. The interpolation algorithm used for resizing. One of the following:
  11588. @table @option
  11589. @item nn
  11590. Nearest neighbour.
  11591. @item linear
  11592. @item cubic
  11593. @item cubic2p_bspline
  11594. 2-parameter cubic (B=1, C=0)
  11595. @item cubic2p_catmullrom
  11596. 2-parameter cubic (B=0, C=1/2)
  11597. @item cubic2p_b05c03
  11598. 2-parameter cubic (B=1/2, C=3/10)
  11599. @item super
  11600. Supersampling
  11601. @item lanczos
  11602. @end table
  11603. @end table
  11604. @section scale2ref
  11605. Scale (resize) the input video, based on a reference video.
  11606. See the scale filter for available options, scale2ref supports the same but
  11607. uses the reference video instead of the main input as basis. scale2ref also
  11608. supports the following additional constants for the @option{w} and
  11609. @option{h} options:
  11610. @table @var
  11611. @item main_w
  11612. @item main_h
  11613. The main input video's width and height
  11614. @item main_a
  11615. The same as @var{main_w} / @var{main_h}
  11616. @item main_sar
  11617. The main input video's sample aspect ratio
  11618. @item main_dar, mdar
  11619. The main input video's display aspect ratio. Calculated from
  11620. @code{(main_w / main_h) * main_sar}.
  11621. @item main_hsub
  11622. @item main_vsub
  11623. The main input video's horizontal and vertical chroma subsample values.
  11624. For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
  11625. is 1.
  11626. @end table
  11627. @subsection Examples
  11628. @itemize
  11629. @item
  11630. Scale a subtitle stream (b) to match the main video (a) in size before overlaying
  11631. @example
  11632. 'scale2ref[b][a];[a][b]overlay'
  11633. @end example
  11634. @end itemize
  11635. @anchor{selectivecolor}
  11636. @section selectivecolor
  11637. Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
  11638. as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
  11639. by the "purity" of the color (that is, how saturated it already is).
  11640. This filter is similar to the Adobe Photoshop Selective Color tool.
  11641. The filter accepts the following options:
  11642. @table @option
  11643. @item correction_method
  11644. Select color correction method.
  11645. Available values are:
  11646. @table @samp
  11647. @item absolute
  11648. Specified adjustments are applied "as-is" (added/subtracted to original pixel
  11649. component value).
  11650. @item relative
  11651. Specified adjustments are relative to the original component value.
  11652. @end table
  11653. Default is @code{absolute}.
  11654. @item reds
  11655. Adjustments for red pixels (pixels where the red component is the maximum)
  11656. @item yellows
  11657. Adjustments for yellow pixels (pixels where the blue component is the minimum)
  11658. @item greens
  11659. Adjustments for green pixels (pixels where the green component is the maximum)
  11660. @item cyans
  11661. Adjustments for cyan pixels (pixels where the red component is the minimum)
  11662. @item blues
  11663. Adjustments for blue pixels (pixels where the blue component is the maximum)
  11664. @item magentas
  11665. Adjustments for magenta pixels (pixels where the green component is the minimum)
  11666. @item whites
  11667. Adjustments for white pixels (pixels where all components are greater than 128)
  11668. @item neutrals
  11669. Adjustments for all pixels except pure black and pure white
  11670. @item blacks
  11671. Adjustments for black pixels (pixels where all components are lesser than 128)
  11672. @item psfile
  11673. Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
  11674. @end table
  11675. All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
  11676. 4 space separated floating point adjustment values in the [-1,1] range,
  11677. respectively to adjust the amount of cyan, magenta, yellow and black for the
  11678. pixels of its range.
  11679. @subsection Examples
  11680. @itemize
  11681. @item
  11682. Increase cyan by 50% and reduce yellow by 33% in every green areas, and
  11683. increase magenta by 27% in blue areas:
  11684. @example
  11685. selectivecolor=greens=.5 0 -.33 0:blues=0 .27
  11686. @end example
  11687. @item
  11688. Use a Photoshop selective color preset:
  11689. @example
  11690. selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
  11691. @end example
  11692. @end itemize
  11693. @anchor{separatefields}
  11694. @section separatefields
  11695. The @code{separatefields} takes a frame-based video input and splits
  11696. each frame into its components fields, producing a new half height clip
  11697. with twice the frame rate and twice the frame count.
  11698. This filter use field-dominance information in frame to decide which
  11699. of each pair of fields to place first in the output.
  11700. If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
  11701. @section setdar, setsar
  11702. The @code{setdar} filter sets the Display Aspect Ratio for the filter
  11703. output video.
  11704. This is done by changing the specified Sample (aka Pixel) Aspect
  11705. Ratio, according to the following equation:
  11706. @example
  11707. @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
  11708. @end example
  11709. Keep in mind that the @code{setdar} filter does not modify the pixel
  11710. dimensions of the video frame. Also, the display aspect ratio set by
  11711. this filter may be changed by later filters in the filterchain,
  11712. e.g. in case of scaling or if another "setdar" or a "setsar" filter is
  11713. applied.
  11714. The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
  11715. the filter output video.
  11716. Note that as a consequence of the application of this filter, the
  11717. output display aspect ratio will change according to the equation
  11718. above.
  11719. Keep in mind that the sample aspect ratio set by the @code{setsar}
  11720. filter may be changed by later filters in the filterchain, e.g. if
  11721. another "setsar" or a "setdar" filter is applied.
  11722. It accepts the following parameters:
  11723. @table @option
  11724. @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
  11725. Set the aspect ratio used by the filter.
  11726. The parameter can be a floating point number string, an expression, or
  11727. a string of the form @var{num}:@var{den}, where @var{num} and
  11728. @var{den} are the numerator and denominator of the aspect ratio. If
  11729. the parameter is not specified, it is assumed the value "0".
  11730. In case the form "@var{num}:@var{den}" is used, the @code{:} character
  11731. should be escaped.
  11732. @item max
  11733. Set the maximum integer value to use for expressing numerator and
  11734. denominator when reducing the expressed aspect ratio to a rational.
  11735. Default value is @code{100}.
  11736. @end table
  11737. The parameter @var{sar} is an expression containing
  11738. the following constants:
  11739. @table @option
  11740. @item E, PI, PHI
  11741. These are approximated values for the mathematical constants e
  11742. (Euler's number), pi (Greek pi), and phi (the golden ratio).
  11743. @item w, h
  11744. The input width and height.
  11745. @item a
  11746. These are the same as @var{w} / @var{h}.
  11747. @item sar
  11748. The input sample aspect ratio.
  11749. @item dar
  11750. The input display aspect ratio. It is the same as
  11751. (@var{w} / @var{h}) * @var{sar}.
  11752. @item hsub, vsub
  11753. Horizontal and vertical chroma subsample values. For example, for the
  11754. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  11755. @end table
  11756. @subsection Examples
  11757. @itemize
  11758. @item
  11759. To change the display aspect ratio to 16:9, specify one of the following:
  11760. @example
  11761. setdar=dar=1.77777
  11762. setdar=dar=16/9
  11763. @end example
  11764. @item
  11765. To change the sample aspect ratio to 10:11, specify:
  11766. @example
  11767. setsar=sar=10/11
  11768. @end example
  11769. @item
  11770. To set a display aspect ratio of 16:9, and specify a maximum integer value of
  11771. 1000 in the aspect ratio reduction, use the command:
  11772. @example
  11773. setdar=ratio=16/9:max=1000
  11774. @end example
  11775. @end itemize
  11776. @anchor{setfield}
  11777. @section setfield
  11778. Force field for the output video frame.
  11779. The @code{setfield} filter marks the interlace type field for the
  11780. output frames. It does not change the input frame, but only sets the
  11781. corresponding property, which affects how the frame is treated by
  11782. following filters (e.g. @code{fieldorder} or @code{yadif}).
  11783. The filter accepts the following options:
  11784. @table @option
  11785. @item mode
  11786. Available values are:
  11787. @table @samp
  11788. @item auto
  11789. Keep the same field property.
  11790. @item bff
  11791. Mark the frame as bottom-field-first.
  11792. @item tff
  11793. Mark the frame as top-field-first.
  11794. @item prog
  11795. Mark the frame as progressive.
  11796. @end table
  11797. @end table
  11798. @anchor{setparams}
  11799. @section setparams
  11800. Force frame parameter for the output video frame.
  11801. The @code{setparams} filter marks interlace and color range for the
  11802. output frames. It does not change the input frame, but only sets the
  11803. corresponding property, which affects how the frame is treated by
  11804. filters/encoders.
  11805. @table @option
  11806. @item field_mode
  11807. Available values are:
  11808. @table @samp
  11809. @item auto
  11810. Keep the same field property (default).
  11811. @item bff
  11812. Mark the frame as bottom-field-first.
  11813. @item tff
  11814. Mark the frame as top-field-first.
  11815. @item prog
  11816. Mark the frame as progressive.
  11817. @end table
  11818. @item range
  11819. Available values are:
  11820. @table @samp
  11821. @item auto
  11822. Keep the same color range property (default).
  11823. @item unspecified, unknown
  11824. Mark the frame as unspecified color range.
  11825. @item limited, tv, mpeg
  11826. Mark the frame as limited range.
  11827. @item full, pc, jpeg
  11828. Mark the frame as full range.
  11829. @end table
  11830. @item color_primaries
  11831. Set the color primaries.
  11832. Available values are:
  11833. @table @samp
  11834. @item auto
  11835. Keep the same color primaries property (default).
  11836. @item bt709
  11837. @item unknown
  11838. @item bt470m
  11839. @item bt470bg
  11840. @item smpte170m
  11841. @item smpte240m
  11842. @item film
  11843. @item bt2020
  11844. @item smpte428
  11845. @item smpte431
  11846. @item smpte432
  11847. @item jedec-p22
  11848. @end table
  11849. @item color_trc
  11850. Set the color transfer.
  11851. Available values are:
  11852. @table @samp
  11853. @item auto
  11854. Keep the same color trc property (default).
  11855. @item bt709
  11856. @item unknown
  11857. @item bt470m
  11858. @item bt470bg
  11859. @item smpte170m
  11860. @item smpte240m
  11861. @item linear
  11862. @item log100
  11863. @item log316
  11864. @item iec61966-2-4
  11865. @item bt1361e
  11866. @item iec61966-2-1
  11867. @item bt2020-10
  11868. @item bt2020-12
  11869. @item smpte2084
  11870. @item smpte428
  11871. @item arib-std-b67
  11872. @end table
  11873. @item colorspace
  11874. Set the colorspace.
  11875. Available values are:
  11876. @table @samp
  11877. @item auto
  11878. Keep the same colorspace property (default).
  11879. @item gbr
  11880. @item bt709
  11881. @item unknown
  11882. @item fcc
  11883. @item bt470bg
  11884. @item smpte170m
  11885. @item smpte240m
  11886. @item ycgco
  11887. @item bt2020nc
  11888. @item bt2020c
  11889. @item smpte2085
  11890. @item chroma-derived-nc
  11891. @item chroma-derived-c
  11892. @item ictcp
  11893. @end table
  11894. @end table
  11895. @section showinfo
  11896. Show a line containing various information for each input video frame.
  11897. The input video is not modified.
  11898. This filter supports the following options:
  11899. @table @option
  11900. @item checksum
  11901. Calculate checksums of each plane. By default enabled.
  11902. @end table
  11903. The shown line contains a sequence of key/value pairs of the form
  11904. @var{key}:@var{value}.
  11905. The following values are shown in the output:
  11906. @table @option
  11907. @item n
  11908. The (sequential) number of the input frame, starting from 0.
  11909. @item pts
  11910. The Presentation TimeStamp of the input frame, expressed as a number of
  11911. time base units. The time base unit depends on the filter input pad.
  11912. @item pts_time
  11913. The Presentation TimeStamp of the input frame, expressed as a number of
  11914. seconds.
  11915. @item pos
  11916. The position of the frame in the input stream, or -1 if this information is
  11917. unavailable and/or meaningless (for example in case of synthetic video).
  11918. @item fmt
  11919. The pixel format name.
  11920. @item sar
  11921. The sample aspect ratio of the input frame, expressed in the form
  11922. @var{num}/@var{den}.
  11923. @item s
  11924. The size of the input frame. For the syntax of this option, check the
  11925. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  11926. @item i
  11927. The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
  11928. for bottom field first).
  11929. @item iskey
  11930. This is 1 if the frame is a key frame, 0 otherwise.
  11931. @item type
  11932. The picture type of the input frame ("I" for an I-frame, "P" for a
  11933. P-frame, "B" for a B-frame, or "?" for an unknown type).
  11934. Also refer to the documentation of the @code{AVPictureType} enum and of
  11935. the @code{av_get_picture_type_char} function defined in
  11936. @file{libavutil/avutil.h}.
  11937. @item checksum
  11938. The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
  11939. @item plane_checksum
  11940. The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
  11941. expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
  11942. @end table
  11943. @section showpalette
  11944. Displays the 256 colors palette of each frame. This filter is only relevant for
  11945. @var{pal8} pixel format frames.
  11946. It accepts the following option:
  11947. @table @option
  11948. @item s
  11949. Set the size of the box used to represent one palette color entry. Default is
  11950. @code{30} (for a @code{30x30} pixel box).
  11951. @end table
  11952. @section shuffleframes
  11953. Reorder and/or duplicate and/or drop video frames.
  11954. It accepts the following parameters:
  11955. @table @option
  11956. @item mapping
  11957. Set the destination indexes of input frames.
  11958. This is space or '|' separated list of indexes that maps input frames to output
  11959. frames. Number of indexes also sets maximal value that each index may have.
  11960. '-1' index have special meaning and that is to drop frame.
  11961. @end table
  11962. The first frame has the index 0. The default is to keep the input unchanged.
  11963. @subsection Examples
  11964. @itemize
  11965. @item
  11966. Swap second and third frame of every three frames of the input:
  11967. @example
  11968. ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
  11969. @end example
  11970. @item
  11971. Swap 10th and 1st frame of every ten frames of the input:
  11972. @example
  11973. ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
  11974. @end example
  11975. @end itemize
  11976. @section shuffleplanes
  11977. Reorder and/or duplicate video planes.
  11978. It accepts the following parameters:
  11979. @table @option
  11980. @item map0
  11981. The index of the input plane to be used as the first output plane.
  11982. @item map1
  11983. The index of the input plane to be used as the second output plane.
  11984. @item map2
  11985. The index of the input plane to be used as the third output plane.
  11986. @item map3
  11987. The index of the input plane to be used as the fourth output plane.
  11988. @end table
  11989. The first plane has the index 0. The default is to keep the input unchanged.
  11990. @subsection Examples
  11991. @itemize
  11992. @item
  11993. Swap the second and third planes of the input:
  11994. @example
  11995. ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
  11996. @end example
  11997. @end itemize
  11998. @anchor{signalstats}
  11999. @section signalstats
  12000. Evaluate various visual metrics that assist in determining issues associated
  12001. with the digitization of analog video media.
  12002. By default the filter will log these metadata values:
  12003. @table @option
  12004. @item YMIN
  12005. Display the minimal Y value contained within the input frame. Expressed in
  12006. range of [0-255].
  12007. @item YLOW
  12008. Display the Y value at the 10% percentile within the input frame. Expressed in
  12009. range of [0-255].
  12010. @item YAVG
  12011. Display the average Y value within the input frame. Expressed in range of
  12012. [0-255].
  12013. @item YHIGH
  12014. Display the Y value at the 90% percentile within the input frame. Expressed in
  12015. range of [0-255].
  12016. @item YMAX
  12017. Display the maximum Y value contained within the input frame. Expressed in
  12018. range of [0-255].
  12019. @item UMIN
  12020. Display the minimal U value contained within the input frame. Expressed in
  12021. range of [0-255].
  12022. @item ULOW
  12023. Display the U value at the 10% percentile within the input frame. Expressed in
  12024. range of [0-255].
  12025. @item UAVG
  12026. Display the average U value within the input frame. Expressed in range of
  12027. [0-255].
  12028. @item UHIGH
  12029. Display the U value at the 90% percentile within the input frame. Expressed in
  12030. range of [0-255].
  12031. @item UMAX
  12032. Display the maximum U value contained within the input frame. Expressed in
  12033. range of [0-255].
  12034. @item VMIN
  12035. Display the minimal V value contained within the input frame. Expressed in
  12036. range of [0-255].
  12037. @item VLOW
  12038. Display the V value at the 10% percentile within the input frame. Expressed in
  12039. range of [0-255].
  12040. @item VAVG
  12041. Display the average V value within the input frame. Expressed in range of
  12042. [0-255].
  12043. @item VHIGH
  12044. Display the V value at the 90% percentile within the input frame. Expressed in
  12045. range of [0-255].
  12046. @item VMAX
  12047. Display the maximum V value contained within the input frame. Expressed in
  12048. range of [0-255].
  12049. @item SATMIN
  12050. Display the minimal saturation value contained within the input frame.
  12051. Expressed in range of [0-~181.02].
  12052. @item SATLOW
  12053. Display the saturation value at the 10% percentile within the input frame.
  12054. Expressed in range of [0-~181.02].
  12055. @item SATAVG
  12056. Display the average saturation value within the input frame. Expressed in range
  12057. of [0-~181.02].
  12058. @item SATHIGH
  12059. Display the saturation value at the 90% percentile within the input frame.
  12060. Expressed in range of [0-~181.02].
  12061. @item SATMAX
  12062. Display the maximum saturation value contained within the input frame.
  12063. Expressed in range of [0-~181.02].
  12064. @item HUEMED
  12065. Display the median value for hue within the input frame. Expressed in range of
  12066. [0-360].
  12067. @item HUEAVG
  12068. Display the average value for hue within the input frame. Expressed in range of
  12069. [0-360].
  12070. @item YDIF
  12071. Display the average of sample value difference between all values of the Y
  12072. plane in the current frame and corresponding values of the previous input frame.
  12073. Expressed in range of [0-255].
  12074. @item UDIF
  12075. Display the average of sample value difference between all values of the U
  12076. plane in the current frame and corresponding values of the previous input frame.
  12077. Expressed in range of [0-255].
  12078. @item VDIF
  12079. Display the average of sample value difference between all values of the V
  12080. plane in the current frame and corresponding values of the previous input frame.
  12081. Expressed in range of [0-255].
  12082. @item YBITDEPTH
  12083. Display bit depth of Y plane in current frame.
  12084. Expressed in range of [0-16].
  12085. @item UBITDEPTH
  12086. Display bit depth of U plane in current frame.
  12087. Expressed in range of [0-16].
  12088. @item VBITDEPTH
  12089. Display bit depth of V plane in current frame.
  12090. Expressed in range of [0-16].
  12091. @end table
  12092. The filter accepts the following options:
  12093. @table @option
  12094. @item stat
  12095. @item out
  12096. @option{stat} specify an additional form of image analysis.
  12097. @option{out} output video with the specified type of pixel highlighted.
  12098. Both options accept the following values:
  12099. @table @samp
  12100. @item tout
  12101. Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
  12102. unlike the neighboring pixels of the same field. Examples of temporal outliers
  12103. include the results of video dropouts, head clogs, or tape tracking issues.
  12104. @item vrep
  12105. Identify @var{vertical line repetition}. Vertical line repetition includes
  12106. similar rows of pixels within a frame. In born-digital video vertical line
  12107. repetition is common, but this pattern is uncommon in video digitized from an
  12108. analog source. When it occurs in video that results from the digitization of an
  12109. analog source it can indicate concealment from a dropout compensator.
  12110. @item brng
  12111. Identify pixels that fall outside of legal broadcast range.
  12112. @end table
  12113. @item color, c
  12114. Set the highlight color for the @option{out} option. The default color is
  12115. yellow.
  12116. @end table
  12117. @subsection Examples
  12118. @itemize
  12119. @item
  12120. Output data of various video metrics:
  12121. @example
  12122. ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
  12123. @end example
  12124. @item
  12125. Output specific data about the minimum and maximum values of the Y plane per frame:
  12126. @example
  12127. ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
  12128. @end example
  12129. @item
  12130. Playback video while highlighting pixels that are outside of broadcast range in red.
  12131. @example
  12132. ffplay example.mov -vf signalstats="out=brng:color=red"
  12133. @end example
  12134. @item
  12135. Playback video with signalstats metadata drawn over the frame.
  12136. @example
  12137. ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
  12138. @end example
  12139. The contents of signalstat_drawtext.txt used in the command are:
  12140. @example
  12141. time %@{pts:hms@}
  12142. Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
  12143. U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
  12144. V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
  12145. saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
  12146. @end example
  12147. @end itemize
  12148. @anchor{signature}
  12149. @section signature
  12150. Calculates the MPEG-7 Video Signature. The filter can handle more than one
  12151. input. In this case the matching between the inputs can be calculated additionally.
  12152. The filter always passes through the first input. The signature of each stream can
  12153. be written into a file.
  12154. It accepts the following options:
  12155. @table @option
  12156. @item detectmode
  12157. Enable or disable the matching process.
  12158. Available values are:
  12159. @table @samp
  12160. @item off
  12161. Disable the calculation of a matching (default).
  12162. @item full
  12163. Calculate the matching for the whole video and output whether the whole video
  12164. matches or only parts.
  12165. @item fast
  12166. Calculate only until a matching is found or the video ends. Should be faster in
  12167. some cases.
  12168. @end table
  12169. @item nb_inputs
  12170. Set the number of inputs. The option value must be a non negative integer.
  12171. Default value is 1.
  12172. @item filename
  12173. Set the path to which the output is written. If there is more than one input,
  12174. the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
  12175. integer), that will be replaced with the input number. If no filename is
  12176. specified, no output will be written. This is the default.
  12177. @item format
  12178. Choose the output format.
  12179. Available values are:
  12180. @table @samp
  12181. @item binary
  12182. Use the specified binary representation (default).
  12183. @item xml
  12184. Use the specified xml representation.
  12185. @end table
  12186. @item th_d
  12187. Set threshold to detect one word as similar. The option value must be an integer
  12188. greater than zero. The default value is 9000.
  12189. @item th_dc
  12190. Set threshold to detect all words as similar. The option value must be an integer
  12191. greater than zero. The default value is 60000.
  12192. @item th_xh
  12193. Set threshold to detect frames as similar. The option value must be an integer
  12194. greater than zero. The default value is 116.
  12195. @item th_di
  12196. Set the minimum length of a sequence in frames to recognize it as matching
  12197. sequence. The option value must be a non negative integer value.
  12198. The default value is 0.
  12199. @item th_it
  12200. Set the minimum relation, that matching frames to all frames must have.
  12201. The option value must be a double value between 0 and 1. The default value is 0.5.
  12202. @end table
  12203. @subsection Examples
  12204. @itemize
  12205. @item
  12206. To calculate the signature of an input video and store it in signature.bin:
  12207. @example
  12208. ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
  12209. @end example
  12210. @item
  12211. To detect whether two videos match and store the signatures in XML format in
  12212. signature0.xml and signature1.xml:
  12213. @example
  12214. ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -
  12215. @end example
  12216. @end itemize
  12217. @anchor{smartblur}
  12218. @section smartblur
  12219. Blur the input video without impacting the outlines.
  12220. It accepts the following options:
  12221. @table @option
  12222. @item luma_radius, lr
  12223. Set the luma radius. The option value must be a float number in
  12224. the range [0.1,5.0] that specifies the variance of the gaussian filter
  12225. used to blur the image (slower if larger). Default value is 1.0.
  12226. @item luma_strength, ls
  12227. Set the luma strength. The option value must be a float number
  12228. in the range [-1.0,1.0] that configures the blurring. A value included
  12229. in [0.0,1.0] will blur the image whereas a value included in
  12230. [-1.0,0.0] will sharpen the image. Default value is 1.0.
  12231. @item luma_threshold, lt
  12232. Set the luma threshold used as a coefficient to determine
  12233. whether a pixel should be blurred or not. The option value must be an
  12234. integer in the range [-30,30]. A value of 0 will filter all the image,
  12235. a value included in [0,30] will filter flat areas and a value included
  12236. in [-30,0] will filter edges. Default value is 0.
  12237. @item chroma_radius, cr
  12238. Set the chroma radius. The option value must be a float number in
  12239. the range [0.1,5.0] that specifies the variance of the gaussian filter
  12240. used to blur the image (slower if larger). Default value is @option{luma_radius}.
  12241. @item chroma_strength, cs
  12242. Set the chroma strength. The option value must be a float number
  12243. in the range [-1.0,1.0] that configures the blurring. A value included
  12244. in [0.0,1.0] will blur the image whereas a value included in
  12245. [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
  12246. @item chroma_threshold, ct
  12247. Set the chroma threshold used as a coefficient to determine
  12248. whether a pixel should be blurred or not. The option value must be an
  12249. integer in the range [-30,30]. A value of 0 will filter all the image,
  12250. a value included in [0,30] will filter flat areas and a value included
  12251. in [-30,0] will filter edges. Default value is @option{luma_threshold}.
  12252. @end table
  12253. If a chroma option is not explicitly set, the corresponding luma value
  12254. is set.
  12255. @section ssim
  12256. Obtain the SSIM (Structural SImilarity Metric) between two input videos.
  12257. This filter takes in input two input videos, the first input is
  12258. considered the "main" source and is passed unchanged to the
  12259. output. The second input is used as a "reference" video for computing
  12260. the SSIM.
  12261. Both video inputs must have the same resolution and pixel format for
  12262. this filter to work correctly. Also it assumes that both inputs
  12263. have the same number of frames, which are compared one by one.
  12264. The filter stores the calculated SSIM of each frame.
  12265. The description of the accepted parameters follows.
  12266. @table @option
  12267. @item stats_file, f
  12268. If specified the filter will use the named file to save the SSIM of
  12269. each individual frame. When filename equals "-" the data is sent to
  12270. standard output.
  12271. @end table
  12272. The file printed if @var{stats_file} is selected, contains a sequence of
  12273. key/value pairs of the form @var{key}:@var{value} for each compared
  12274. couple of frames.
  12275. A description of each shown parameter follows:
  12276. @table @option
  12277. @item n
  12278. sequential number of the input frame, starting from 1
  12279. @item Y, U, V, R, G, B
  12280. SSIM of the compared frames for the component specified by the suffix.
  12281. @item All
  12282. SSIM of the compared frames for the whole frame.
  12283. @item dB
  12284. Same as above but in dB representation.
  12285. @end table
  12286. This filter also supports the @ref{framesync} options.
  12287. For example:
  12288. @example
  12289. movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
  12290. [main][ref] ssim="stats_file=stats.log" [out]
  12291. @end example
  12292. On this example the input file being processed is compared with the
  12293. reference file @file{ref_movie.mpg}. The SSIM of each individual frame
  12294. is stored in @file{stats.log}.
  12295. Another example with both psnr and ssim at same time:
  12296. @example
  12297. ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
  12298. @end example
  12299. @section stereo3d
  12300. Convert between different stereoscopic image formats.
  12301. The filters accept the following options:
  12302. @table @option
  12303. @item in
  12304. Set stereoscopic image format of input.
  12305. Available values for input image formats are:
  12306. @table @samp
  12307. @item sbsl
  12308. side by side parallel (left eye left, right eye right)
  12309. @item sbsr
  12310. side by side crosseye (right eye left, left eye right)
  12311. @item sbs2l
  12312. side by side parallel with half width resolution
  12313. (left eye left, right eye right)
  12314. @item sbs2r
  12315. side by side crosseye with half width resolution
  12316. (right eye left, left eye right)
  12317. @item abl
  12318. above-below (left eye above, right eye below)
  12319. @item abr
  12320. above-below (right eye above, left eye below)
  12321. @item ab2l
  12322. above-below with half height resolution
  12323. (left eye above, right eye below)
  12324. @item ab2r
  12325. above-below with half height resolution
  12326. (right eye above, left eye below)
  12327. @item al
  12328. alternating frames (left eye first, right eye second)
  12329. @item ar
  12330. alternating frames (right eye first, left eye second)
  12331. @item irl
  12332. interleaved rows (left eye has top row, right eye starts on next row)
  12333. @item irr
  12334. interleaved rows (right eye has top row, left eye starts on next row)
  12335. @item icl
  12336. interleaved columns, left eye first
  12337. @item icr
  12338. interleaved columns, right eye first
  12339. Default value is @samp{sbsl}.
  12340. @end table
  12341. @item out
  12342. Set stereoscopic image format of output.
  12343. @table @samp
  12344. @item sbsl
  12345. side by side parallel (left eye left, right eye right)
  12346. @item sbsr
  12347. side by side crosseye (right eye left, left eye right)
  12348. @item sbs2l
  12349. side by side parallel with half width resolution
  12350. (left eye left, right eye right)
  12351. @item sbs2r
  12352. side by side crosseye with half width resolution
  12353. (right eye left, left eye right)
  12354. @item abl
  12355. above-below (left eye above, right eye below)
  12356. @item abr
  12357. above-below (right eye above, left eye below)
  12358. @item ab2l
  12359. above-below with half height resolution
  12360. (left eye above, right eye below)
  12361. @item ab2r
  12362. above-below with half height resolution
  12363. (right eye above, left eye below)
  12364. @item al
  12365. alternating frames (left eye first, right eye second)
  12366. @item ar
  12367. alternating frames (right eye first, left eye second)
  12368. @item irl
  12369. interleaved rows (left eye has top row, right eye starts on next row)
  12370. @item irr
  12371. interleaved rows (right eye has top row, left eye starts on next row)
  12372. @item arbg
  12373. anaglyph red/blue gray
  12374. (red filter on left eye, blue filter on right eye)
  12375. @item argg
  12376. anaglyph red/green gray
  12377. (red filter on left eye, green filter on right eye)
  12378. @item arcg
  12379. anaglyph red/cyan gray
  12380. (red filter on left eye, cyan filter on right eye)
  12381. @item arch
  12382. anaglyph red/cyan half colored
  12383. (red filter on left eye, cyan filter on right eye)
  12384. @item arcc
  12385. anaglyph red/cyan color
  12386. (red filter on left eye, cyan filter on right eye)
  12387. @item arcd
  12388. anaglyph red/cyan color optimized with the least squares projection of dubois
  12389. (red filter on left eye, cyan filter on right eye)
  12390. @item agmg
  12391. anaglyph green/magenta gray
  12392. (green filter on left eye, magenta filter on right eye)
  12393. @item agmh
  12394. anaglyph green/magenta half colored
  12395. (green filter on left eye, magenta filter on right eye)
  12396. @item agmc
  12397. anaglyph green/magenta colored
  12398. (green filter on left eye, magenta filter on right eye)
  12399. @item agmd
  12400. anaglyph green/magenta color optimized with the least squares projection of dubois
  12401. (green filter on left eye, magenta filter on right eye)
  12402. @item aybg
  12403. anaglyph yellow/blue gray
  12404. (yellow filter on left eye, blue filter on right eye)
  12405. @item aybh
  12406. anaglyph yellow/blue half colored
  12407. (yellow filter on left eye, blue filter on right eye)
  12408. @item aybc
  12409. anaglyph yellow/blue colored
  12410. (yellow filter on left eye, blue filter on right eye)
  12411. @item aybd
  12412. anaglyph yellow/blue color optimized with the least squares projection of dubois
  12413. (yellow filter on left eye, blue filter on right eye)
  12414. @item ml
  12415. mono output (left eye only)
  12416. @item mr
  12417. mono output (right eye only)
  12418. @item chl
  12419. checkerboard, left eye first
  12420. @item chr
  12421. checkerboard, right eye first
  12422. @item icl
  12423. interleaved columns, left eye first
  12424. @item icr
  12425. interleaved columns, right eye first
  12426. @item hdmi
  12427. HDMI frame pack
  12428. @end table
  12429. Default value is @samp{arcd}.
  12430. @end table
  12431. @subsection Examples
  12432. @itemize
  12433. @item
  12434. Convert input video from side by side parallel to anaglyph yellow/blue dubois:
  12435. @example
  12436. stereo3d=sbsl:aybd
  12437. @end example
  12438. @item
  12439. Convert input video from above below (left eye above, right eye below) to side by side crosseye.
  12440. @example
  12441. stereo3d=abl:sbsr
  12442. @end example
  12443. @end itemize
  12444. @section streamselect, astreamselect
  12445. Select video or audio streams.
  12446. The filter accepts the following options:
  12447. @table @option
  12448. @item inputs
  12449. Set number of inputs. Default is 2.
  12450. @item map
  12451. Set input indexes to remap to outputs.
  12452. @end table
  12453. @subsection Commands
  12454. The @code{streamselect} and @code{astreamselect} filter supports the following
  12455. commands:
  12456. @table @option
  12457. @item map
  12458. Set input indexes to remap to outputs.
  12459. @end table
  12460. @subsection Examples
  12461. @itemize
  12462. @item
  12463. Select first 5 seconds 1st stream and rest of time 2nd stream:
  12464. @example
  12465. sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
  12466. @end example
  12467. @item
  12468. Same as above, but for audio:
  12469. @example
  12470. asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
  12471. @end example
  12472. @end itemize
  12473. @section sobel
  12474. Apply sobel operator to input video stream.
  12475. The filter accepts the following option:
  12476. @table @option
  12477. @item planes
  12478. Set which planes will be processed, unprocessed planes will be copied.
  12479. By default value 0xf, all planes will be processed.
  12480. @item scale
  12481. Set value which will be multiplied with filtered result.
  12482. @item delta
  12483. Set value which will be added to filtered result.
  12484. @end table
  12485. @anchor{spp}
  12486. @section spp
  12487. Apply a simple postprocessing filter that compresses and decompresses the image
  12488. at several (or - in the case of @option{quality} level @code{6} - all) shifts
  12489. and average the results.
  12490. The filter accepts the following options:
  12491. @table @option
  12492. @item quality
  12493. Set quality. This option defines the number of levels for averaging. It accepts
  12494. an integer in the range 0-6. If set to @code{0}, the filter will have no
  12495. effect. A value of @code{6} means the higher quality. For each increment of
  12496. that value the speed drops by a factor of approximately 2. Default value is
  12497. @code{3}.
  12498. @item qp
  12499. Force a constant quantization parameter. If not set, the filter will use the QP
  12500. from the video stream (if available).
  12501. @item mode
  12502. Set thresholding mode. Available modes are:
  12503. @table @samp
  12504. @item hard
  12505. Set hard thresholding (default).
  12506. @item soft
  12507. Set soft thresholding (better de-ringing effect, but likely blurrier).
  12508. @end table
  12509. @item use_bframe_qp
  12510. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  12511. option may cause flicker since the B-Frames have often larger QP. Default is
  12512. @code{0} (not enabled).
  12513. @end table
  12514. @section sr
  12515. Scale the input by applying one of the super-resolution methods based on
  12516. convolutional neural networks. Supported models:
  12517. @itemize
  12518. @item
  12519. Super-Resolution Convolutional Neural Network model (SRCNN).
  12520. See @url{https://arxiv.org/abs/1501.00092}.
  12521. @item
  12522. Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
  12523. See @url{https://arxiv.org/abs/1609.05158}.
  12524. @end itemize
  12525. Training scripts as well as scripts for model generation are provided in
  12526. the repository at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
  12527. The filter accepts the following options:
  12528. @table @option
  12529. @item dnn_backend
  12530. Specify which DNN backend to use for model loading and execution. This option accepts
  12531. the following values:
  12532. @table @samp
  12533. @item native
  12534. Native implementation of DNN loading and execution.
  12535. @item tensorflow
  12536. TensorFlow backend. To enable this backend you
  12537. need to install the TensorFlow for C library (see
  12538. @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
  12539. @code{--enable-libtensorflow}
  12540. @end table
  12541. Default value is @samp{native}.
  12542. @item model
  12543. Set path to model file specifying network architecture and its parameters.
  12544. Note that different backends use different file formats. TensorFlow backend
  12545. can load files for both formats, while native backend can load files for only
  12546. its format.
  12547. @item scale_factor
  12548. Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
  12549. Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
  12550. input upscaled using bicubic upscaling with proper scale factor.
  12551. @end table
  12552. @anchor{subtitles}
  12553. @section subtitles
  12554. Draw subtitles on top of input video using the libass library.
  12555. To enable compilation of this filter you need to configure FFmpeg with
  12556. @code{--enable-libass}. This filter also requires a build with libavcodec and
  12557. libavformat to convert the passed subtitles file to ASS (Advanced Substation
  12558. Alpha) subtitles format.
  12559. The filter accepts the following options:
  12560. @table @option
  12561. @item filename, f
  12562. Set the filename of the subtitle file to read. It must be specified.
  12563. @item original_size
  12564. Specify the size of the original video, the video for which the ASS file
  12565. was composed. For the syntax of this option, check the
  12566. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12567. Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
  12568. correctly scale the fonts if the aspect ratio has been changed.
  12569. @item fontsdir
  12570. Set a directory path containing fonts that can be used by the filter.
  12571. These fonts will be used in addition to whatever the font provider uses.
  12572. @item alpha
  12573. Process alpha channel, by default alpha channel is untouched.
  12574. @item charenc
  12575. Set subtitles input character encoding. @code{subtitles} filter only. Only
  12576. useful if not UTF-8.
  12577. @item stream_index, si
  12578. Set subtitles stream index. @code{subtitles} filter only.
  12579. @item force_style
  12580. Override default style or script info parameters of the subtitles. It accepts a
  12581. string containing ASS style format @code{KEY=VALUE} couples separated by ",".
  12582. @end table
  12583. If the first key is not specified, it is assumed that the first value
  12584. specifies the @option{filename}.
  12585. For example, to render the file @file{sub.srt} on top of the input
  12586. video, use the command:
  12587. @example
  12588. subtitles=sub.srt
  12589. @end example
  12590. which is equivalent to:
  12591. @example
  12592. subtitles=filename=sub.srt
  12593. @end example
  12594. To render the default subtitles stream from file @file{video.mkv}, use:
  12595. @example
  12596. subtitles=video.mkv
  12597. @end example
  12598. To render the second subtitles stream from that file, use:
  12599. @example
  12600. subtitles=video.mkv:si=1
  12601. @end example
  12602. To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
  12603. @code{DejaVu Serif}, use:
  12604. @example
  12605. subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
  12606. @end example
  12607. @section super2xsai
  12608. Scale the input by 2x and smooth using the Super2xSaI (Scale and
  12609. Interpolate) pixel art scaling algorithm.
  12610. Useful for enlarging pixel art images without reducing sharpness.
  12611. @section swaprect
  12612. Swap two rectangular objects in video.
  12613. This filter accepts the following options:
  12614. @table @option
  12615. @item w
  12616. Set object width.
  12617. @item h
  12618. Set object height.
  12619. @item x1
  12620. Set 1st rect x coordinate.
  12621. @item y1
  12622. Set 1st rect y coordinate.
  12623. @item x2
  12624. Set 2nd rect x coordinate.
  12625. @item y2
  12626. Set 2nd rect y coordinate.
  12627. All expressions are evaluated once for each frame.
  12628. @end table
  12629. The all options are expressions containing the following constants:
  12630. @table @option
  12631. @item w
  12632. @item h
  12633. The input width and height.
  12634. @item a
  12635. same as @var{w} / @var{h}
  12636. @item sar
  12637. input sample aspect ratio
  12638. @item dar
  12639. input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
  12640. @item n
  12641. The number of the input frame, starting from 0.
  12642. @item t
  12643. The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
  12644. @item pos
  12645. the position in the file of the input frame, NAN if unknown
  12646. @end table
  12647. @section swapuv
  12648. Swap U & V plane.
  12649. @section telecine
  12650. Apply telecine process to the video.
  12651. This filter accepts the following options:
  12652. @table @option
  12653. @item first_field
  12654. @table @samp
  12655. @item top, t
  12656. top field first
  12657. @item bottom, b
  12658. bottom field first
  12659. The default value is @code{top}.
  12660. @end table
  12661. @item pattern
  12662. A string of numbers representing the pulldown pattern you wish to apply.
  12663. The default value is @code{23}.
  12664. @end table
  12665. @example
  12666. Some typical patterns:
  12667. NTSC output (30i):
  12668. 27.5p: 32222
  12669. 24p: 23 (classic)
  12670. 24p: 2332 (preferred)
  12671. 20p: 33
  12672. 18p: 334
  12673. 16p: 3444
  12674. PAL output (25i):
  12675. 27.5p: 12222
  12676. 24p: 222222222223 ("Euro pulldown")
  12677. 16.67p: 33
  12678. 16p: 33333334
  12679. @end example
  12680. @section threshold
  12681. Apply threshold effect to video stream.
  12682. This filter needs four video streams to perform thresholding.
  12683. First stream is stream we are filtering.
  12684. Second stream is holding threshold values, third stream is holding min values,
  12685. and last, fourth stream is holding max values.
  12686. The filter accepts the following option:
  12687. @table @option
  12688. @item planes
  12689. Set which planes will be processed, unprocessed planes will be copied.
  12690. By default value 0xf, all planes will be processed.
  12691. @end table
  12692. For example if first stream pixel's component value is less then threshold value
  12693. of pixel component from 2nd threshold stream, third stream value will picked,
  12694. otherwise fourth stream pixel component value will be picked.
  12695. Using color source filter one can perform various types of thresholding:
  12696. @subsection Examples
  12697. @itemize
  12698. @item
  12699. Binary threshold, using gray color as threshold:
  12700. @example
  12701. ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
  12702. @end example
  12703. @item
  12704. Inverted binary threshold, using gray color as threshold:
  12705. @example
  12706. ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
  12707. @end example
  12708. @item
  12709. Truncate binary threshold, using gray color as threshold:
  12710. @example
  12711. ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
  12712. @end example
  12713. @item
  12714. Threshold to zero, using gray color as threshold:
  12715. @example
  12716. ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
  12717. @end example
  12718. @item
  12719. Inverted threshold to zero, using gray color as threshold:
  12720. @example
  12721. ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
  12722. @end example
  12723. @end itemize
  12724. @section thumbnail
  12725. Select the most representative frame in a given sequence of consecutive frames.
  12726. The filter accepts the following options:
  12727. @table @option
  12728. @item n
  12729. Set the frames batch size to analyze; in a set of @var{n} frames, the filter
  12730. will pick one of them, and then handle the next batch of @var{n} frames until
  12731. the end. Default is @code{100}.
  12732. @end table
  12733. Since the filter keeps track of the whole frames sequence, a bigger @var{n}
  12734. value will result in a higher memory usage, so a high value is not recommended.
  12735. @subsection Examples
  12736. @itemize
  12737. @item
  12738. Extract one picture each 50 frames:
  12739. @example
  12740. thumbnail=50
  12741. @end example
  12742. @item
  12743. Complete example of a thumbnail creation with @command{ffmpeg}:
  12744. @example
  12745. ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
  12746. @end example
  12747. @end itemize
  12748. @section tile
  12749. Tile several successive frames together.
  12750. The filter accepts the following options:
  12751. @table @option
  12752. @item layout
  12753. Set the grid size (i.e. the number of lines and columns). For the syntax of
  12754. this option, check the
  12755. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12756. @item nb_frames
  12757. Set the maximum number of frames to render in the given area. It must be less
  12758. than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
  12759. the area will be used.
  12760. @item margin
  12761. Set the outer border margin in pixels.
  12762. @item padding
  12763. Set the inner border thickness (i.e. the number of pixels between frames). For
  12764. more advanced padding options (such as having different values for the edges),
  12765. refer to the pad video filter.
  12766. @item color
  12767. Specify the color of the unused area. For the syntax of this option, check the
  12768. @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  12769. The default value of @var{color} is "black".
  12770. @item overlap
  12771. Set the number of frames to overlap when tiling several successive frames together.
  12772. The value must be between @code{0} and @var{nb_frames - 1}.
  12773. @item init_padding
  12774. Set the number of frames to initially be empty before displaying first output frame.
  12775. This controls how soon will one get first output frame.
  12776. The value must be between @code{0} and @var{nb_frames - 1}.
  12777. @end table
  12778. @subsection Examples
  12779. @itemize
  12780. @item
  12781. Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
  12782. @example
  12783. ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
  12784. @end example
  12785. The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
  12786. duplicating each output frame to accommodate the originally detected frame
  12787. rate.
  12788. @item
  12789. Display @code{5} pictures in an area of @code{3x2} frames,
  12790. with @code{7} pixels between them, and @code{2} pixels of initial margin, using
  12791. mixed flat and named options:
  12792. @example
  12793. tile=3x2:nb_frames=5:padding=7:margin=2
  12794. @end example
  12795. @end itemize
  12796. @section tinterlace
  12797. Perform various types of temporal field interlacing.
  12798. Frames are counted starting from 1, so the first input frame is
  12799. considered odd.
  12800. The filter accepts the following options:
  12801. @table @option
  12802. @item mode
  12803. Specify the mode of the interlacing. This option can also be specified
  12804. as a value alone. See below for a list of values for this option.
  12805. Available values are:
  12806. @table @samp
  12807. @item merge, 0
  12808. Move odd frames into the upper field, even into the lower field,
  12809. generating a double height frame at half frame rate.
  12810. @example
  12811. ------> time
  12812. Input:
  12813. Frame 1 Frame 2 Frame 3 Frame 4
  12814. 11111 22222 33333 44444
  12815. 11111 22222 33333 44444
  12816. 11111 22222 33333 44444
  12817. 11111 22222 33333 44444
  12818. Output:
  12819. 11111 33333
  12820. 22222 44444
  12821. 11111 33333
  12822. 22222 44444
  12823. 11111 33333
  12824. 22222 44444
  12825. 11111 33333
  12826. 22222 44444
  12827. @end example
  12828. @item drop_even, 1
  12829. Only output odd frames, even frames are dropped, generating a frame with
  12830. unchanged height at half frame rate.
  12831. @example
  12832. ------> time
  12833. Input:
  12834. Frame 1 Frame 2 Frame 3 Frame 4
  12835. 11111 22222 33333 44444
  12836. 11111 22222 33333 44444
  12837. 11111 22222 33333 44444
  12838. 11111 22222 33333 44444
  12839. Output:
  12840. 11111 33333
  12841. 11111 33333
  12842. 11111 33333
  12843. 11111 33333
  12844. @end example
  12845. @item drop_odd, 2
  12846. Only output even frames, odd frames are dropped, generating a frame with
  12847. unchanged height at half frame rate.
  12848. @example
  12849. ------> time
  12850. Input:
  12851. Frame 1 Frame 2 Frame 3 Frame 4
  12852. 11111 22222 33333 44444
  12853. 11111 22222 33333 44444
  12854. 11111 22222 33333 44444
  12855. 11111 22222 33333 44444
  12856. Output:
  12857. 22222 44444
  12858. 22222 44444
  12859. 22222 44444
  12860. 22222 44444
  12861. @end example
  12862. @item pad, 3
  12863. Expand each frame to full height, but pad alternate lines with black,
  12864. generating a frame with double height at the same input frame rate.
  12865. @example
  12866. ------> time
  12867. Input:
  12868. Frame 1 Frame 2 Frame 3 Frame 4
  12869. 11111 22222 33333 44444
  12870. 11111 22222 33333 44444
  12871. 11111 22222 33333 44444
  12872. 11111 22222 33333 44444
  12873. Output:
  12874. 11111 ..... 33333 .....
  12875. ..... 22222 ..... 44444
  12876. 11111 ..... 33333 .....
  12877. ..... 22222 ..... 44444
  12878. 11111 ..... 33333 .....
  12879. ..... 22222 ..... 44444
  12880. 11111 ..... 33333 .....
  12881. ..... 22222 ..... 44444
  12882. @end example
  12883. @item interleave_top, 4
  12884. Interleave the upper field from odd frames with the lower field from
  12885. even frames, generating a frame with unchanged height at half frame rate.
  12886. @example
  12887. ------> time
  12888. Input:
  12889. Frame 1 Frame 2 Frame 3 Frame 4
  12890. 11111<- 22222 33333<- 44444
  12891. 11111 22222<- 33333 44444<-
  12892. 11111<- 22222 33333<- 44444
  12893. 11111 22222<- 33333 44444<-
  12894. Output:
  12895. 11111 33333
  12896. 22222 44444
  12897. 11111 33333
  12898. 22222 44444
  12899. @end example
  12900. @item interleave_bottom, 5
  12901. Interleave the lower field from odd frames with the upper field from
  12902. even frames, generating a frame with unchanged height at half frame rate.
  12903. @example
  12904. ------> time
  12905. Input:
  12906. Frame 1 Frame 2 Frame 3 Frame 4
  12907. 11111 22222<- 33333 44444<-
  12908. 11111<- 22222 33333<- 44444
  12909. 11111 22222<- 33333 44444<-
  12910. 11111<- 22222 33333<- 44444
  12911. Output:
  12912. 22222 44444
  12913. 11111 33333
  12914. 22222 44444
  12915. 11111 33333
  12916. @end example
  12917. @item interlacex2, 6
  12918. Double frame rate with unchanged height. Frames are inserted each
  12919. containing the second temporal field from the previous input frame and
  12920. the first temporal field from the next input frame. This mode relies on
  12921. the top_field_first flag. Useful for interlaced video displays with no
  12922. field synchronisation.
  12923. @example
  12924. ------> time
  12925. Input:
  12926. Frame 1 Frame 2 Frame 3 Frame 4
  12927. 11111 22222 33333 44444
  12928. 11111 22222 33333 44444
  12929. 11111 22222 33333 44444
  12930. 11111 22222 33333 44444
  12931. Output:
  12932. 11111 22222 22222 33333 33333 44444 44444
  12933. 11111 11111 22222 22222 33333 33333 44444
  12934. 11111 22222 22222 33333 33333 44444 44444
  12935. 11111 11111 22222 22222 33333 33333 44444
  12936. @end example
  12937. @item mergex2, 7
  12938. Move odd frames into the upper field, even into the lower field,
  12939. generating a double height frame at same frame rate.
  12940. @example
  12941. ------> time
  12942. Input:
  12943. Frame 1 Frame 2 Frame 3 Frame 4
  12944. 11111 22222 33333 44444
  12945. 11111 22222 33333 44444
  12946. 11111 22222 33333 44444
  12947. 11111 22222 33333 44444
  12948. Output:
  12949. 11111 33333 33333 55555
  12950. 22222 22222 44444 44444
  12951. 11111 33333 33333 55555
  12952. 22222 22222 44444 44444
  12953. 11111 33333 33333 55555
  12954. 22222 22222 44444 44444
  12955. 11111 33333 33333 55555
  12956. 22222 22222 44444 44444
  12957. @end example
  12958. @end table
  12959. Numeric values are deprecated but are accepted for backward
  12960. compatibility reasons.
  12961. Default mode is @code{merge}.
  12962. @item flags
  12963. Specify flags influencing the filter process.
  12964. Available value for @var{flags} is:
  12965. @table @option
  12966. @item low_pass_filter, vlfp
  12967. Enable linear vertical low-pass filtering in the filter.
  12968. Vertical low-pass filtering is required when creating an interlaced
  12969. destination from a progressive source which contains high-frequency
  12970. vertical detail. Filtering will reduce interlace 'twitter' and Moire
  12971. patterning.
  12972. @item complex_filter, cvlfp
  12973. Enable complex vertical low-pass filtering.
  12974. This will slightly less reduce interlace 'twitter' and Moire
  12975. patterning but better retain detail and subjective sharpness impression.
  12976. @end table
  12977. Vertical low-pass filtering can only be enabled for @option{mode}
  12978. @var{interleave_top} and @var{interleave_bottom}.
  12979. @end table
  12980. @section tmix
  12981. Mix successive video frames.
  12982. A description of the accepted options follows.
  12983. @table @option
  12984. @item frames
  12985. The number of successive frames to mix. If unspecified, it defaults to 3.
  12986. @item weights
  12987. Specify weight of each input video frame.
  12988. Each weight is separated by space. If number of weights is smaller than
  12989. number of @var{frames} last specified weight will be used for all remaining
  12990. unset weights.
  12991. @item scale
  12992. Specify scale, if it is set it will be multiplied with sum
  12993. of each weight multiplied with pixel values to give final destination
  12994. pixel value. By default @var{scale} is auto scaled to sum of weights.
  12995. @end table
  12996. @subsection Examples
  12997. @itemize
  12998. @item
  12999. Average 7 successive frames:
  13000. @example
  13001. tmix=frames=7:weights="1 1 1 1 1 1 1"
  13002. @end example
  13003. @item
  13004. Apply simple temporal convolution:
  13005. @example
  13006. tmix=frames=3:weights="-1 3 -1"
  13007. @end example
  13008. @item
  13009. Similar as above but only showing temporal differences:
  13010. @example
  13011. tmix=frames=3:weights="-1 2 -1":scale=1
  13012. @end example
  13013. @end itemize
  13014. @anchor{tonemap}
  13015. @section tonemap
  13016. Tone map colors from different dynamic ranges.
  13017. This filter expects data in single precision floating point, as it needs to
  13018. operate on (and can output) out-of-range values. Another filter, such as
  13019. @ref{zscale}, is needed to convert the resulting frame to a usable format.
  13020. The tonemapping algorithms implemented only work on linear light, so input
  13021. data should be linearized beforehand (and possibly correctly tagged).
  13022. @example
  13023. ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
  13024. @end example
  13025. @subsection Options
  13026. The filter accepts the following options.
  13027. @table @option
  13028. @item tonemap
  13029. Set the tone map algorithm to use.
  13030. Possible values are:
  13031. @table @var
  13032. @item none
  13033. Do not apply any tone map, only desaturate overbright pixels.
  13034. @item clip
  13035. Hard-clip any out-of-range values. Use it for perfect color accuracy for
  13036. in-range values, while distorting out-of-range values.
  13037. @item linear
  13038. Stretch the entire reference gamut to a linear multiple of the display.
  13039. @item gamma
  13040. Fit a logarithmic transfer between the tone curves.
  13041. @item reinhard
  13042. Preserve overall image brightness with a simple curve, using nonlinear
  13043. contrast, which results in flattening details and degrading color accuracy.
  13044. @item hable
  13045. Preserve both dark and bright details better than @var{reinhard}, at the cost
  13046. of slightly darkening everything. Use it when detail preservation is more
  13047. important than color and brightness accuracy.
  13048. @item mobius
  13049. Smoothly map out-of-range values, while retaining contrast and colors for
  13050. in-range material as much as possible. Use it when color accuracy is more
  13051. important than detail preservation.
  13052. @end table
  13053. Default is none.
  13054. @item param
  13055. Tune the tone mapping algorithm.
  13056. This affects the following algorithms:
  13057. @table @var
  13058. @item none
  13059. Ignored.
  13060. @item linear
  13061. Specifies the scale factor to use while stretching.
  13062. Default to 1.0.
  13063. @item gamma
  13064. Specifies the exponent of the function.
  13065. Default to 1.8.
  13066. @item clip
  13067. Specify an extra linear coefficient to multiply into the signal before clipping.
  13068. Default to 1.0.
  13069. @item reinhard
  13070. Specify the local contrast coefficient at the display peak.
  13071. Default to 0.5, which means that in-gamut values will be about half as bright
  13072. as when clipping.
  13073. @item hable
  13074. Ignored.
  13075. @item mobius
  13076. Specify the transition point from linear to mobius transform. Every value
  13077. below this point is guaranteed to be mapped 1:1. The higher the value, the
  13078. more accurate the result will be, at the cost of losing bright details.
  13079. Default to 0.3, which due to the steep initial slope still preserves in-range
  13080. colors fairly accurately.
  13081. @end table
  13082. @item desat
  13083. Apply desaturation for highlights that exceed this level of brightness. The
  13084. higher the parameter, the more color information will be preserved. This
  13085. setting helps prevent unnaturally blown-out colors for super-highlights, by
  13086. (smoothly) turning into white instead. This makes images feel more natural,
  13087. at the cost of reducing information about out-of-range colors.
  13088. The default of 2.0 is somewhat conservative and will mostly just apply to
  13089. skies or directly sunlit surfaces. A setting of 0.0 disables this option.
  13090. This option works only if the input frame has a supported color tag.
  13091. @item peak
  13092. Override signal/nominal/reference peak with this value. Useful when the
  13093. embedded peak information in display metadata is not reliable or when tone
  13094. mapping from a lower range to a higher range.
  13095. @end table
  13096. @section tpad
  13097. Temporarily pad video frames.
  13098. The filter accepts the following options:
  13099. @table @option
  13100. @item start
  13101. Specify number of delay frames before input video stream.
  13102. @item stop
  13103. Specify number of padding frames after input video stream.
  13104. Set to -1 to pad indefinitely.
  13105. @item start_mode
  13106. Set kind of frames added to beginning of stream.
  13107. Can be either @var{add} or @var{clone}.
  13108. With @var{add} frames of solid-color are added.
  13109. With @var{clone} frames are clones of first frame.
  13110. @item stop_mode
  13111. Set kind of frames added to end of stream.
  13112. Can be either @var{add} or @var{clone}.
  13113. With @var{add} frames of solid-color are added.
  13114. With @var{clone} frames are clones of last frame.
  13115. @item start_duration, stop_duration
  13116. Specify the duration of the start/stop delay. See
  13117. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  13118. for the accepted syntax.
  13119. These options override @var{start} and @var{stop}.
  13120. @item color
  13121. Specify the color of the padded area. For the syntax of this option,
  13122. check the @ref{color syntax,,"Color" section in the ffmpeg-utils
  13123. manual,ffmpeg-utils}.
  13124. The default value of @var{color} is "black".
  13125. @end table
  13126. @anchor{transpose}
  13127. @section transpose
  13128. Transpose rows with columns in the input video and optionally flip it.
  13129. It accepts the following parameters:
  13130. @table @option
  13131. @item dir
  13132. Specify the transposition direction.
  13133. Can assume the following values:
  13134. @table @samp
  13135. @item 0, 4, cclock_flip
  13136. Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
  13137. @example
  13138. L.R L.l
  13139. . . -> . .
  13140. l.r R.r
  13141. @end example
  13142. @item 1, 5, clock
  13143. Rotate by 90 degrees clockwise, that is:
  13144. @example
  13145. L.R l.L
  13146. . . -> . .
  13147. l.r r.R
  13148. @end example
  13149. @item 2, 6, cclock
  13150. Rotate by 90 degrees counterclockwise, that is:
  13151. @example
  13152. L.R R.r
  13153. . . -> . .
  13154. l.r L.l
  13155. @end example
  13156. @item 3, 7, clock_flip
  13157. Rotate by 90 degrees clockwise and vertically flip, that is:
  13158. @example
  13159. L.R r.R
  13160. . . -> . .
  13161. l.r l.L
  13162. @end example
  13163. @end table
  13164. For values between 4-7, the transposition is only done if the input
  13165. video geometry is portrait and not landscape. These values are
  13166. deprecated, the @code{passthrough} option should be used instead.
  13167. Numerical values are deprecated, and should be dropped in favor of
  13168. symbolic constants.
  13169. @item passthrough
  13170. Do not apply the transposition if the input geometry matches the one
  13171. specified by the specified value. It accepts the following values:
  13172. @table @samp
  13173. @item none
  13174. Always apply transposition.
  13175. @item portrait
  13176. Preserve portrait geometry (when @var{height} >= @var{width}).
  13177. @item landscape
  13178. Preserve landscape geometry (when @var{width} >= @var{height}).
  13179. @end table
  13180. Default value is @code{none}.
  13181. @end table
  13182. For example to rotate by 90 degrees clockwise and preserve portrait
  13183. layout:
  13184. @example
  13185. transpose=dir=1:passthrough=portrait
  13186. @end example
  13187. The command above can also be specified as:
  13188. @example
  13189. transpose=1:portrait
  13190. @end example
  13191. @section transpose_npp
  13192. Transpose rows with columns in the input video and optionally flip it.
  13193. For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
  13194. It accepts the following parameters:
  13195. @table @option
  13196. @item dir
  13197. Specify the transposition direction.
  13198. Can assume the following values:
  13199. @table @samp
  13200. @item cclock_flip
  13201. Rotate by 90 degrees counterclockwise and vertically flip. (default)
  13202. @item clock
  13203. Rotate by 90 degrees clockwise.
  13204. @item cclock
  13205. Rotate by 90 degrees counterclockwise.
  13206. @item clock_flip
  13207. Rotate by 90 degrees clockwise and vertically flip.
  13208. @end table
  13209. @item passthrough
  13210. Do not apply the transposition if the input geometry matches the one
  13211. specified by the specified value. It accepts the following values:
  13212. @table @samp
  13213. @item none
  13214. Always apply transposition. (default)
  13215. @item portrait
  13216. Preserve portrait geometry (when @var{height} >= @var{width}).
  13217. @item landscape
  13218. Preserve landscape geometry (when @var{width} >= @var{height}).
  13219. @end table
  13220. @end table
  13221. @section trim
  13222. Trim the input so that the output contains one continuous subpart of the input.
  13223. It accepts the following parameters:
  13224. @table @option
  13225. @item start
  13226. Specify the time of the start of the kept section, i.e. the frame with the
  13227. timestamp @var{start} will be the first frame in the output.
  13228. @item end
  13229. Specify the time of the first frame that will be dropped, i.e. the frame
  13230. immediately preceding the one with the timestamp @var{end} will be the last
  13231. frame in the output.
  13232. @item start_pts
  13233. This is the same as @var{start}, except this option sets the start timestamp
  13234. in timebase units instead of seconds.
  13235. @item end_pts
  13236. This is the same as @var{end}, except this option sets the end timestamp
  13237. in timebase units instead of seconds.
  13238. @item duration
  13239. The maximum duration of the output in seconds.
  13240. @item start_frame
  13241. The number of the first frame that should be passed to the output.
  13242. @item end_frame
  13243. The number of the first frame that should be dropped.
  13244. @end table
  13245. @option{start}, @option{end}, and @option{duration} are expressed as time
  13246. duration specifications; see
  13247. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  13248. for the accepted syntax.
  13249. Note that the first two sets of the start/end options and the @option{duration}
  13250. option look at the frame timestamp, while the _frame variants simply count the
  13251. frames that pass through the filter. Also note that this filter does not modify
  13252. the timestamps. If you wish for the output timestamps to start at zero, insert a
  13253. setpts filter after the trim filter.
  13254. If multiple start or end options are set, this filter tries to be greedy and
  13255. keep all the frames that match at least one of the specified constraints. To keep
  13256. only the part that matches all the constraints at once, chain multiple trim
  13257. filters.
  13258. The defaults are such that all the input is kept. So it is possible to set e.g.
  13259. just the end values to keep everything before the specified time.
  13260. Examples:
  13261. @itemize
  13262. @item
  13263. Drop everything except the second minute of input:
  13264. @example
  13265. ffmpeg -i INPUT -vf trim=60:120
  13266. @end example
  13267. @item
  13268. Keep only the first second:
  13269. @example
  13270. ffmpeg -i INPUT -vf trim=duration=1
  13271. @end example
  13272. @end itemize
  13273. @section unpremultiply
  13274. Apply alpha unpremultiply effect to input video stream using first plane
  13275. of second stream as alpha.
  13276. Both streams must have same dimensions and same pixel format.
  13277. The filter accepts the following option:
  13278. @table @option
  13279. @item planes
  13280. Set which planes will be processed, unprocessed planes will be copied.
  13281. By default value 0xf, all planes will be processed.
  13282. If the format has 1 or 2 components, then luma is bit 0.
  13283. If the format has 3 or 4 components:
  13284. for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
  13285. for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
  13286. If present, the alpha channel is always the last bit.
  13287. @item inplace
  13288. Do not require 2nd input for processing, instead use alpha plane from input stream.
  13289. @end table
  13290. @anchor{unsharp}
  13291. @section unsharp
  13292. Sharpen or blur the input video.
  13293. It accepts the following parameters:
  13294. @table @option
  13295. @item luma_msize_x, lx
  13296. Set the luma matrix horizontal size. It must be an odd integer between
  13297. 3 and 23. The default value is 5.
  13298. @item luma_msize_y, ly
  13299. Set the luma matrix vertical size. It must be an odd integer between 3
  13300. and 23. The default value is 5.
  13301. @item luma_amount, la
  13302. Set the luma effect strength. It must be a floating point number, reasonable
  13303. values lay between -1.5 and 1.5.
  13304. Negative values will blur the input video, while positive values will
  13305. sharpen it, a value of zero will disable the effect.
  13306. Default value is 1.0.
  13307. @item chroma_msize_x, cx
  13308. Set the chroma matrix horizontal size. It must be an odd integer
  13309. between 3 and 23. The default value is 5.
  13310. @item chroma_msize_y, cy
  13311. Set the chroma matrix vertical size. It must be an odd integer
  13312. between 3 and 23. The default value is 5.
  13313. @item chroma_amount, ca
  13314. Set the chroma effect strength. It must be a floating point number, reasonable
  13315. values lay between -1.5 and 1.5.
  13316. Negative values will blur the input video, while positive values will
  13317. sharpen it, a value of zero will disable the effect.
  13318. Default value is 0.0.
  13319. @end table
  13320. All parameters are optional and default to the equivalent of the
  13321. string '5:5:1.0:5:5:0.0'.
  13322. @subsection Examples
  13323. @itemize
  13324. @item
  13325. Apply strong luma sharpen effect:
  13326. @example
  13327. unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
  13328. @end example
  13329. @item
  13330. Apply a strong blur of both luma and chroma parameters:
  13331. @example
  13332. unsharp=7:7:-2:7:7:-2
  13333. @end example
  13334. @end itemize
  13335. @section uspp
  13336. Apply ultra slow/simple postprocessing filter that compresses and decompresses
  13337. the image at several (or - in the case of @option{quality} level @code{8} - all)
  13338. shifts and average the results.
  13339. The way this differs from the behavior of spp is that uspp actually encodes &
  13340. decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
  13341. DCT similar to MJPEG.
  13342. The filter accepts the following options:
  13343. @table @option
  13344. @item quality
  13345. Set quality. This option defines the number of levels for averaging. It accepts
  13346. an integer in the range 0-8. If set to @code{0}, the filter will have no
  13347. effect. A value of @code{8} means the higher quality. For each increment of
  13348. that value the speed drops by a factor of approximately 2. Default value is
  13349. @code{3}.
  13350. @item qp
  13351. Force a constant quantization parameter. If not set, the filter will use the QP
  13352. from the video stream (if available).
  13353. @end table
  13354. @section vaguedenoiser
  13355. Apply a wavelet based denoiser.
  13356. It transforms each frame from the video input into the wavelet domain,
  13357. using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
  13358. the obtained coefficients. It does an inverse wavelet transform after.
  13359. Due to wavelet properties, it should give a nice smoothed result, and
  13360. reduced noise, without blurring picture features.
  13361. This filter accepts the following options:
  13362. @table @option
  13363. @item threshold
  13364. The filtering strength. The higher, the more filtered the video will be.
  13365. Hard thresholding can use a higher threshold than soft thresholding
  13366. before the video looks overfiltered. Default value is 2.
  13367. @item method
  13368. The filtering method the filter will use.
  13369. It accepts the following values:
  13370. @table @samp
  13371. @item hard
  13372. All values under the threshold will be zeroed.
  13373. @item soft
  13374. All values under the threshold will be zeroed. All values above will be
  13375. reduced by the threshold.
  13376. @item garrote
  13377. Scales or nullifies coefficients - intermediary between (more) soft and
  13378. (less) hard thresholding.
  13379. @end table
  13380. Default is garrote.
  13381. @item nsteps
  13382. Number of times, the wavelet will decompose the picture. Picture can't
  13383. be decomposed beyond a particular point (typically, 8 for a 640x480
  13384. frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
  13385. @item percent
  13386. Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
  13387. @item planes
  13388. A list of the planes to process. By default all planes are processed.
  13389. @end table
  13390. @section vectorscope
  13391. Display 2 color component values in the two dimensional graph (which is called
  13392. a vectorscope).
  13393. This filter accepts the following options:
  13394. @table @option
  13395. @item mode, m
  13396. Set vectorscope mode.
  13397. It accepts the following values:
  13398. @table @samp
  13399. @item gray
  13400. Gray values are displayed on graph, higher brightness means more pixels have
  13401. same component color value on location in graph. This is the default mode.
  13402. @item color
  13403. Gray values are displayed on graph. Surrounding pixels values which are not
  13404. present in video frame are drawn in gradient of 2 color components which are
  13405. set by option @code{x} and @code{y}. The 3rd color component is static.
  13406. @item color2
  13407. Actual color components values present in video frame are displayed on graph.
  13408. @item color3
  13409. Similar as color2 but higher frequency of same values @code{x} and @code{y}
  13410. on graph increases value of another color component, which is luminance by
  13411. default values of @code{x} and @code{y}.
  13412. @item color4
  13413. Actual colors present in video frame are displayed on graph. If two different
  13414. colors map to same position on graph then color with higher value of component
  13415. not present in graph is picked.
  13416. @item color5
  13417. Gray values are displayed on graph. Similar to @code{color} but with 3rd color
  13418. component picked from radial gradient.
  13419. @end table
  13420. @item x
  13421. Set which color component will be represented on X-axis. Default is @code{1}.
  13422. @item y
  13423. Set which color component will be represented on Y-axis. Default is @code{2}.
  13424. @item intensity, i
  13425. Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
  13426. of color component which represents frequency of (X, Y) location in graph.
  13427. @item envelope, e
  13428. @table @samp
  13429. @item none
  13430. No envelope, this is default.
  13431. @item instant
  13432. Instant envelope, even darkest single pixel will be clearly highlighted.
  13433. @item peak
  13434. Hold maximum and minimum values presented in graph over time. This way you
  13435. can still spot out of range values without constantly looking at vectorscope.
  13436. @item peak+instant
  13437. Peak and instant envelope combined together.
  13438. @end table
  13439. @item graticule, g
  13440. Set what kind of graticule to draw.
  13441. @table @samp
  13442. @item none
  13443. @item green
  13444. @item color
  13445. @end table
  13446. @item opacity, o
  13447. Set graticule opacity.
  13448. @item flags, f
  13449. Set graticule flags.
  13450. @table @samp
  13451. @item white
  13452. Draw graticule for white point.
  13453. @item black
  13454. Draw graticule for black point.
  13455. @item name
  13456. Draw color points short names.
  13457. @end table
  13458. @item bgopacity, b
  13459. Set background opacity.
  13460. @item lthreshold, l
  13461. Set low threshold for color component not represented on X or Y axis.
  13462. Values lower than this value will be ignored. Default is 0.
  13463. Note this value is multiplied with actual max possible value one pixel component
  13464. can have. So for 8-bit input and low threshold value of 0.1 actual threshold
  13465. is 0.1 * 255 = 25.
  13466. @item hthreshold, h
  13467. Set high threshold for color component not represented on X or Y axis.
  13468. Values higher than this value will be ignored. Default is 1.
  13469. Note this value is multiplied with actual max possible value one pixel component
  13470. can have. So for 8-bit input and high threshold value of 0.9 actual threshold
  13471. is 0.9 * 255 = 230.
  13472. @item colorspace, c
  13473. Set what kind of colorspace to use when drawing graticule.
  13474. @table @samp
  13475. @item auto
  13476. @item 601
  13477. @item 709
  13478. @end table
  13479. Default is auto.
  13480. @end table
  13481. @anchor{vidstabdetect}
  13482. @section vidstabdetect
  13483. Analyze video stabilization/deshaking. Perform pass 1 of 2, see
  13484. @ref{vidstabtransform} for pass 2.
  13485. This filter generates a file with relative translation and rotation
  13486. transform information about subsequent frames, which is then used by
  13487. the @ref{vidstabtransform} filter.
  13488. To enable compilation of this filter you need to configure FFmpeg with
  13489. @code{--enable-libvidstab}.
  13490. This filter accepts the following options:
  13491. @table @option
  13492. @item result
  13493. Set the path to the file used to write the transforms information.
  13494. Default value is @file{transforms.trf}.
  13495. @item shakiness
  13496. Set how shaky the video is and how quick the camera is. It accepts an
  13497. integer in the range 1-10, a value of 1 means little shakiness, a
  13498. value of 10 means strong shakiness. Default value is 5.
  13499. @item accuracy
  13500. Set the accuracy of the detection process. It must be a value in the
  13501. range 1-15. A value of 1 means low accuracy, a value of 15 means high
  13502. accuracy. Default value is 15.
  13503. @item stepsize
  13504. Set stepsize of the search process. The region around minimum is
  13505. scanned with 1 pixel resolution. Default value is 6.
  13506. @item mincontrast
  13507. Set minimum contrast. Below this value a local measurement field is
  13508. discarded. Must be a floating point value in the range 0-1. Default
  13509. value is 0.3.
  13510. @item tripod
  13511. Set reference frame number for tripod mode.
  13512. If enabled, the motion of the frames is compared to a reference frame
  13513. in the filtered stream, identified by the specified number. The idea
  13514. is to compensate all movements in a more-or-less static scene and keep
  13515. the camera view absolutely still.
  13516. If set to 0, it is disabled. The frames are counted starting from 1.
  13517. @item show
  13518. Show fields and transforms in the resulting frames. It accepts an
  13519. integer in the range 0-2. Default value is 0, which disables any
  13520. visualization.
  13521. @end table
  13522. @subsection Examples
  13523. @itemize
  13524. @item
  13525. Use default values:
  13526. @example
  13527. vidstabdetect
  13528. @end example
  13529. @item
  13530. Analyze strongly shaky movie and put the results in file
  13531. @file{mytransforms.trf}:
  13532. @example
  13533. vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
  13534. @end example
  13535. @item
  13536. Visualize the result of internal transformations in the resulting
  13537. video:
  13538. @example
  13539. vidstabdetect=show=1
  13540. @end example
  13541. @item
  13542. Analyze a video with medium shakiness using @command{ffmpeg}:
  13543. @example
  13544. ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
  13545. @end example
  13546. @end itemize
  13547. @anchor{vidstabtransform}
  13548. @section vidstabtransform
  13549. Video stabilization/deshaking: pass 2 of 2,
  13550. see @ref{vidstabdetect} for pass 1.
  13551. Read a file with transform information for each frame and
  13552. apply/compensate them. Together with the @ref{vidstabdetect}
  13553. filter this can be used to deshake videos. See also
  13554. @url{http://public.hronopik.de/vid.stab}. It is important to also use
  13555. the @ref{unsharp} filter, see below.
  13556. To enable compilation of this filter you need to configure FFmpeg with
  13557. @code{--enable-libvidstab}.
  13558. @subsection Options
  13559. @table @option
  13560. @item input
  13561. Set path to the file used to read the transforms. Default value is
  13562. @file{transforms.trf}.
  13563. @item smoothing
  13564. Set the number of frames (value*2 + 1) used for lowpass filtering the
  13565. camera movements. Default value is 10.
  13566. For example a number of 10 means that 21 frames are used (10 in the
  13567. past and 10 in the future) to smoothen the motion in the video. A
  13568. larger value leads to a smoother video, but limits the acceleration of
  13569. the camera (pan/tilt movements). 0 is a special case where a static
  13570. camera is simulated.
  13571. @item optalgo
  13572. Set the camera path optimization algorithm.
  13573. Accepted values are:
  13574. @table @samp
  13575. @item gauss
  13576. gaussian kernel low-pass filter on camera motion (default)
  13577. @item avg
  13578. averaging on transformations
  13579. @end table
  13580. @item maxshift
  13581. Set maximal number of pixels to translate frames. Default value is -1,
  13582. meaning no limit.
  13583. @item maxangle
  13584. Set maximal angle in radians (degree*PI/180) to rotate frames. Default
  13585. value is -1, meaning no limit.
  13586. @item crop
  13587. Specify how to deal with borders that may be visible due to movement
  13588. compensation.
  13589. Available values are:
  13590. @table @samp
  13591. @item keep
  13592. keep image information from previous frame (default)
  13593. @item black
  13594. fill the border black
  13595. @end table
  13596. @item invert
  13597. Invert transforms if set to 1. Default value is 0.
  13598. @item relative
  13599. Consider transforms as relative to previous frame if set to 1,
  13600. absolute if set to 0. Default value is 0.
  13601. @item zoom
  13602. Set percentage to zoom. A positive value will result in a zoom-in
  13603. effect, a negative value in a zoom-out effect. Default value is 0 (no
  13604. zoom).
  13605. @item optzoom
  13606. Set optimal zooming to avoid borders.
  13607. Accepted values are:
  13608. @table @samp
  13609. @item 0
  13610. disabled
  13611. @item 1
  13612. optimal static zoom value is determined (only very strong movements
  13613. will lead to visible borders) (default)
  13614. @item 2
  13615. optimal adaptive zoom value is determined (no borders will be
  13616. visible), see @option{zoomspeed}
  13617. @end table
  13618. Note that the value given at zoom is added to the one calculated here.
  13619. @item zoomspeed
  13620. Set percent to zoom maximally each frame (enabled when
  13621. @option{optzoom} is set to 2). Range is from 0 to 5, default value is
  13622. 0.25.
  13623. @item interpol
  13624. Specify type of interpolation.
  13625. Available values are:
  13626. @table @samp
  13627. @item no
  13628. no interpolation
  13629. @item linear
  13630. linear only horizontal
  13631. @item bilinear
  13632. linear in both directions (default)
  13633. @item bicubic
  13634. cubic in both directions (slow)
  13635. @end table
  13636. @item tripod
  13637. Enable virtual tripod mode if set to 1, which is equivalent to
  13638. @code{relative=0:smoothing=0}. Default value is 0.
  13639. Use also @code{tripod} option of @ref{vidstabdetect}.
  13640. @item debug
  13641. Increase log verbosity if set to 1. Also the detected global motions
  13642. are written to the temporary file @file{global_motions.trf}. Default
  13643. value is 0.
  13644. @end table
  13645. @subsection Examples
  13646. @itemize
  13647. @item
  13648. Use @command{ffmpeg} for a typical stabilization with default values:
  13649. @example
  13650. ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
  13651. @end example
  13652. Note the use of the @ref{unsharp} filter which is always recommended.
  13653. @item
  13654. Zoom in a bit more and load transform data from a given file:
  13655. @example
  13656. vidstabtransform=zoom=5:input="mytransforms.trf"
  13657. @end example
  13658. @item
  13659. Smoothen the video even more:
  13660. @example
  13661. vidstabtransform=smoothing=30
  13662. @end example
  13663. @end itemize
  13664. @section vflip
  13665. Flip the input video vertically.
  13666. For example, to vertically flip a video with @command{ffmpeg}:
  13667. @example
  13668. ffmpeg -i in.avi -vf "vflip" out.avi
  13669. @end example
  13670. @section vfrdet
  13671. Detect variable frame rate video.
  13672. This filter tries to detect if the input is variable or constant frame rate.
  13673. At end it will output number of frames detected as having variable delta pts,
  13674. and ones with constant delta pts.
  13675. If there was frames with variable delta, than it will also show min and max delta
  13676. encountered.
  13677. @section vibrance
  13678. Boost or alter saturation.
  13679. The filter accepts the following options:
  13680. @table @option
  13681. @item intensity
  13682. Set strength of boost if positive value or strength of alter if negative value.
  13683. Default is 0. Allowed range is from -2 to 2.
  13684. @item rbal
  13685. Set the red balance. Default is 1. Allowed range is from -10 to 10.
  13686. @item gbal
  13687. Set the green balance. Default is 1. Allowed range is from -10 to 10.
  13688. @item bbal
  13689. Set the blue balance. Default is 1. Allowed range is from -10 to 10.
  13690. @item rlum
  13691. Set the red luma coefficient.
  13692. @item glum
  13693. Set the green luma coefficient.
  13694. @item blum
  13695. Set the blue luma coefficient.
  13696. @end table
  13697. @anchor{vignette}
  13698. @section vignette
  13699. Make or reverse a natural vignetting effect.
  13700. The filter accepts the following options:
  13701. @table @option
  13702. @item angle, a
  13703. Set lens angle expression as a number of radians.
  13704. The value is clipped in the @code{[0,PI/2]} range.
  13705. Default value: @code{"PI/5"}
  13706. @item x0
  13707. @item y0
  13708. Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
  13709. by default.
  13710. @item mode
  13711. Set forward/backward mode.
  13712. Available modes are:
  13713. @table @samp
  13714. @item forward
  13715. The larger the distance from the central point, the darker the image becomes.
  13716. @item backward
  13717. The larger the distance from the central point, the brighter the image becomes.
  13718. This can be used to reverse a vignette effect, though there is no automatic
  13719. detection to extract the lens @option{angle} and other settings (yet). It can
  13720. also be used to create a burning effect.
  13721. @end table
  13722. Default value is @samp{forward}.
  13723. @item eval
  13724. Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
  13725. It accepts the following values:
  13726. @table @samp
  13727. @item init
  13728. Evaluate expressions only once during the filter initialization.
  13729. @item frame
  13730. Evaluate expressions for each incoming frame. This is way slower than the
  13731. @samp{init} mode since it requires all the scalers to be re-computed, but it
  13732. allows advanced dynamic expressions.
  13733. @end table
  13734. Default value is @samp{init}.
  13735. @item dither
  13736. Set dithering to reduce the circular banding effects. Default is @code{1}
  13737. (enabled).
  13738. @item aspect
  13739. Set vignette aspect. This setting allows one to adjust the shape of the vignette.
  13740. Setting this value to the SAR of the input will make a rectangular vignetting
  13741. following the dimensions of the video.
  13742. Default is @code{1/1}.
  13743. @end table
  13744. @subsection Expressions
  13745. The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
  13746. following parameters.
  13747. @table @option
  13748. @item w
  13749. @item h
  13750. input width and height
  13751. @item n
  13752. the number of input frame, starting from 0
  13753. @item pts
  13754. the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
  13755. @var{TB} units, NAN if undefined
  13756. @item r
  13757. frame rate of the input video, NAN if the input frame rate is unknown
  13758. @item t
  13759. the PTS (Presentation TimeStamp) of the filtered video frame,
  13760. expressed in seconds, NAN if undefined
  13761. @item tb
  13762. time base of the input video
  13763. @end table
  13764. @subsection Examples
  13765. @itemize
  13766. @item
  13767. Apply simple strong vignetting effect:
  13768. @example
  13769. vignette=PI/4
  13770. @end example
  13771. @item
  13772. Make a flickering vignetting:
  13773. @example
  13774. vignette='PI/4+random(1)*PI/50':eval=frame
  13775. @end example
  13776. @end itemize
  13777. @section vmafmotion
  13778. Obtain the average vmaf motion score of a video.
  13779. It is one of the component filters of VMAF.
  13780. The obtained average motion score is printed through the logging system.
  13781. In the below example the input file @file{ref.mpg} is being processed and score
  13782. is computed.
  13783. @example
  13784. ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
  13785. @end example
  13786. @section vstack
  13787. Stack input videos vertically.
  13788. All streams must be of same pixel format and of same width.
  13789. Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
  13790. to create same output.
  13791. The filter accept the following option:
  13792. @table @option
  13793. @item inputs
  13794. Set number of input streams. Default is 2.
  13795. @item shortest
  13796. If set to 1, force the output to terminate when the shortest input
  13797. terminates. Default value is 0.
  13798. @end table
  13799. @section w3fdif
  13800. Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
  13801. Deinterlacing Filter").
  13802. Based on the process described by Martin Weston for BBC R&D, and
  13803. implemented based on the de-interlace algorithm written by Jim
  13804. Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
  13805. uses filter coefficients calculated by BBC R&D.
  13806. There are two sets of filter coefficients, so called "simple":
  13807. and "complex". Which set of filter coefficients is used can
  13808. be set by passing an optional parameter:
  13809. @table @option
  13810. @item filter
  13811. Set the interlacing filter coefficients. Accepts one of the following values:
  13812. @table @samp
  13813. @item simple
  13814. Simple filter coefficient set.
  13815. @item complex
  13816. More-complex filter coefficient set.
  13817. @end table
  13818. Default value is @samp{complex}.
  13819. @item deint
  13820. Specify which frames to deinterlace. Accept one of the following values:
  13821. @table @samp
  13822. @item all
  13823. Deinterlace all frames,
  13824. @item interlaced
  13825. Only deinterlace frames marked as interlaced.
  13826. @end table
  13827. Default value is @samp{all}.
  13828. @end table
  13829. @section waveform
  13830. Video waveform monitor.
  13831. The waveform monitor plots color component intensity. By default luminance
  13832. only. Each column of the waveform corresponds to a column of pixels in the
  13833. source video.
  13834. It accepts the following options:
  13835. @table @option
  13836. @item mode, m
  13837. Can be either @code{row}, or @code{column}. Default is @code{column}.
  13838. In row mode, the graph on the left side represents color component value 0 and
  13839. the right side represents value = 255. In column mode, the top side represents
  13840. color component value = 0 and bottom side represents value = 255.
  13841. @item intensity, i
  13842. Set intensity. Smaller values are useful to find out how many values of the same
  13843. luminance are distributed across input rows/columns.
  13844. Default value is @code{0.04}. Allowed range is [0, 1].
  13845. @item mirror, r
  13846. Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
  13847. In mirrored mode, higher values will be represented on the left
  13848. side for @code{row} mode and at the top for @code{column} mode. Default is
  13849. @code{1} (mirrored).
  13850. @item display, d
  13851. Set display mode.
  13852. It accepts the following values:
  13853. @table @samp
  13854. @item overlay
  13855. Presents information identical to that in the @code{parade}, except
  13856. that the graphs representing color components are superimposed directly
  13857. over one another.
  13858. This display mode makes it easier to spot relative differences or similarities
  13859. in overlapping areas of the color components that are supposed to be identical,
  13860. such as neutral whites, grays, or blacks.
  13861. @item stack
  13862. Display separate graph for the color components side by side in
  13863. @code{row} mode or one below the other in @code{column} mode.
  13864. @item parade
  13865. Display separate graph for the color components side by side in
  13866. @code{column} mode or one below the other in @code{row} mode.
  13867. Using this display mode makes it easy to spot color casts in the highlights
  13868. and shadows of an image, by comparing the contours of the top and the bottom
  13869. graphs of each waveform. Since whites, grays, and blacks are characterized
  13870. by exactly equal amounts of red, green, and blue, neutral areas of the picture
  13871. should display three waveforms of roughly equal width/height. If not, the
  13872. correction is easy to perform by making level adjustments the three waveforms.
  13873. @end table
  13874. Default is @code{stack}.
  13875. @item components, c
  13876. Set which color components to display. Default is 1, which means only luminance
  13877. or red color component if input is in RGB colorspace. If is set for example to
  13878. 7 it will display all 3 (if) available color components.
  13879. @item envelope, e
  13880. @table @samp
  13881. @item none
  13882. No envelope, this is default.
  13883. @item instant
  13884. Instant envelope, minimum and maximum values presented in graph will be easily
  13885. visible even with small @code{step} value.
  13886. @item peak
  13887. Hold minimum and maximum values presented in graph across time. This way you
  13888. can still spot out of range values without constantly looking at waveforms.
  13889. @item peak+instant
  13890. Peak and instant envelope combined together.
  13891. @end table
  13892. @item filter, f
  13893. @table @samp
  13894. @item lowpass
  13895. No filtering, this is default.
  13896. @item flat
  13897. Luma and chroma combined together.
  13898. @item aflat
  13899. Similar as above, but shows difference between blue and red chroma.
  13900. @item xflat
  13901. Similar as above, but use different colors.
  13902. @item chroma
  13903. Displays only chroma.
  13904. @item color
  13905. Displays actual color value on waveform.
  13906. @item acolor
  13907. Similar as above, but with luma showing frequency of chroma values.
  13908. @end table
  13909. @item graticule, g
  13910. Set which graticule to display.
  13911. @table @samp
  13912. @item none
  13913. Do not display graticule.
  13914. @item green
  13915. Display green graticule showing legal broadcast ranges.
  13916. @item orange
  13917. Display orange graticule showing legal broadcast ranges.
  13918. @end table
  13919. @item opacity, o
  13920. Set graticule opacity.
  13921. @item flags, fl
  13922. Set graticule flags.
  13923. @table @samp
  13924. @item numbers
  13925. Draw numbers above lines. By default enabled.
  13926. @item dots
  13927. Draw dots instead of lines.
  13928. @end table
  13929. @item scale, s
  13930. Set scale used for displaying graticule.
  13931. @table @samp
  13932. @item digital
  13933. @item millivolts
  13934. @item ire
  13935. @end table
  13936. Default is digital.
  13937. @item bgopacity, b
  13938. Set background opacity.
  13939. @end table
  13940. @section weave, doubleweave
  13941. The @code{weave} takes a field-based video input and join
  13942. each two sequential fields into single frame, producing a new double
  13943. height clip with half the frame rate and half the frame count.
  13944. The @code{doubleweave} works same as @code{weave} but without
  13945. halving frame rate and frame count.
  13946. It accepts the following option:
  13947. @table @option
  13948. @item first_field
  13949. Set first field. Available values are:
  13950. @table @samp
  13951. @item top, t
  13952. Set the frame as top-field-first.
  13953. @item bottom, b
  13954. Set the frame as bottom-field-first.
  13955. @end table
  13956. @end table
  13957. @subsection Examples
  13958. @itemize
  13959. @item
  13960. Interlace video using @ref{select} and @ref{separatefields} filter:
  13961. @example
  13962. separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
  13963. @end example
  13964. @end itemize
  13965. @section xbr
  13966. Apply the xBR high-quality magnification filter which is designed for pixel
  13967. art. It follows a set of edge-detection rules, see
  13968. @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
  13969. It accepts the following option:
  13970. @table @option
  13971. @item n
  13972. Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
  13973. @code{3xBR} and @code{4} for @code{4xBR}.
  13974. Default is @code{3}.
  13975. @end table
  13976. @section xstack
  13977. Stack video inputs into custom layout.
  13978. All streams must be of same pixel format.
  13979. The filter accept the following option:
  13980. @table @option
  13981. @item inputs
  13982. Set number of input streams. Default is 2.
  13983. @item layout
  13984. Specify layout of inputs.
  13985. This option requires the desired layout configuration to be explicitly set by the user.
  13986. This sets position of each video input in output. Each input
  13987. is separated by '|'.
  13988. The first number represents the column, and the second number represents the row.
  13989. Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
  13990. where X is video input from which to take width or height.
  13991. Multiple values can be used when separated by '+'. In such
  13992. case values are summed together.
  13993. @item shortest
  13994. If set to 1, force the output to terminate when the shortest input
  13995. terminates. Default value is 0.
  13996. @end table
  13997. @subsection Examples
  13998. @itemize
  13999. @item
  14000. Display 4 inputs into 2x2 grid,
  14001. note that if inputs are of different sizes unused gaps might appear,
  14002. as not all of output video is used.
  14003. @example
  14004. xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
  14005. @end example
  14006. @item
  14007. Display 4 inputs into 1x4 grid,
  14008. note that if inputs are of different sizes unused gaps might appear,
  14009. as not all of output video is used.
  14010. @example
  14011. xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
  14012. @end example
  14013. @item
  14014. Display 9 inputs into 3x3 grid,
  14015. note that if inputs are of different sizes unused gaps might appear,
  14016. as not all of output video is used.
  14017. @example
  14018. xstack=inputs=9:layout=w3_0|w3_h0+h2|w3_h0|0_h4|0_0|w3+w1_0|0_h1+h2|w3+w1_h0|w3+w1_h1+h2
  14019. @end example
  14020. @end itemize
  14021. @anchor{yadif}
  14022. @section yadif
  14023. Deinterlace the input video ("yadif" means "yet another deinterlacing
  14024. filter").
  14025. It accepts the following parameters:
  14026. @table @option
  14027. @item mode
  14028. The interlacing mode to adopt. It accepts one of the following values:
  14029. @table @option
  14030. @item 0, send_frame
  14031. Output one frame for each frame.
  14032. @item 1, send_field
  14033. Output one frame for each field.
  14034. @item 2, send_frame_nospatial
  14035. Like @code{send_frame}, but it skips the spatial interlacing check.
  14036. @item 3, send_field_nospatial
  14037. Like @code{send_field}, but it skips the spatial interlacing check.
  14038. @end table
  14039. The default value is @code{send_frame}.
  14040. @item parity
  14041. The picture field parity assumed for the input interlaced video. It accepts one
  14042. of the following values:
  14043. @table @option
  14044. @item 0, tff
  14045. Assume the top field is first.
  14046. @item 1, bff
  14047. Assume the bottom field is first.
  14048. @item -1, auto
  14049. Enable automatic detection of field parity.
  14050. @end table
  14051. The default value is @code{auto}.
  14052. If the interlacing is unknown or the decoder does not export this information,
  14053. top field first will be assumed.
  14054. @item deint
  14055. Specify which frames to deinterlace. Accept one of the following
  14056. values:
  14057. @table @option
  14058. @item 0, all
  14059. Deinterlace all frames.
  14060. @item 1, interlaced
  14061. Only deinterlace frames marked as interlaced.
  14062. @end table
  14063. The default value is @code{all}.
  14064. @end table
  14065. @section yadif_cuda
  14066. Deinterlace the input video using the @ref{yadif} algorithm, but implemented
  14067. in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
  14068. and/or nvenc.
  14069. It accepts the following parameters:
  14070. @table @option
  14071. @item mode
  14072. The interlacing mode to adopt. It accepts one of the following values:
  14073. @table @option
  14074. @item 0, send_frame
  14075. Output one frame for each frame.
  14076. @item 1, send_field
  14077. Output one frame for each field.
  14078. @item 2, send_frame_nospatial
  14079. Like @code{send_frame}, but it skips the spatial interlacing check.
  14080. @item 3, send_field_nospatial
  14081. Like @code{send_field}, but it skips the spatial interlacing check.
  14082. @end table
  14083. The default value is @code{send_frame}.
  14084. @item parity
  14085. The picture field parity assumed for the input interlaced video. It accepts one
  14086. of the following values:
  14087. @table @option
  14088. @item 0, tff
  14089. Assume the top field is first.
  14090. @item 1, bff
  14091. Assume the bottom field is first.
  14092. @item -1, auto
  14093. Enable automatic detection of field parity.
  14094. @end table
  14095. The default value is @code{auto}.
  14096. If the interlacing is unknown or the decoder does not export this information,
  14097. top field first will be assumed.
  14098. @item deint
  14099. Specify which frames to deinterlace. Accept one of the following
  14100. values:
  14101. @table @option
  14102. @item 0, all
  14103. Deinterlace all frames.
  14104. @item 1, interlaced
  14105. Only deinterlace frames marked as interlaced.
  14106. @end table
  14107. The default value is @code{all}.
  14108. @end table
  14109. @section zoompan
  14110. Apply Zoom & Pan effect.
  14111. This filter accepts the following options:
  14112. @table @option
  14113. @item zoom, z
  14114. Set the zoom expression. Range is 1-10. Default is 1.
  14115. @item x
  14116. @item y
  14117. Set the x and y expression. Default is 0.
  14118. @item d
  14119. Set the duration expression in number of frames.
  14120. This sets for how many number of frames effect will last for
  14121. single input image.
  14122. @item s
  14123. Set the output image size, default is 'hd720'.
  14124. @item fps
  14125. Set the output frame rate, default is '25'.
  14126. @end table
  14127. Each expression can contain the following constants:
  14128. @table @option
  14129. @item in_w, iw
  14130. Input width.
  14131. @item in_h, ih
  14132. Input height.
  14133. @item out_w, ow
  14134. Output width.
  14135. @item out_h, oh
  14136. Output height.
  14137. @item in
  14138. Input frame count.
  14139. @item on
  14140. Output frame count.
  14141. @item x
  14142. @item y
  14143. Last calculated 'x' and 'y' position from 'x' and 'y' expression
  14144. for current input frame.
  14145. @item px
  14146. @item py
  14147. 'x' and 'y' of last output frame of previous input frame or 0 when there was
  14148. not yet such frame (first input frame).
  14149. @item zoom
  14150. Last calculated zoom from 'z' expression for current input frame.
  14151. @item pzoom
  14152. Last calculated zoom of last output frame of previous input frame.
  14153. @item duration
  14154. Number of output frames for current input frame. Calculated from 'd' expression
  14155. for each input frame.
  14156. @item pduration
  14157. number of output frames created for previous input frame
  14158. @item a
  14159. Rational number: input width / input height
  14160. @item sar
  14161. sample aspect ratio
  14162. @item dar
  14163. display aspect ratio
  14164. @end table
  14165. @subsection Examples
  14166. @itemize
  14167. @item
  14168. Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
  14169. @example
  14170. 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
  14171. @end example
  14172. @item
  14173. Zoom-in up to 1.5 and pan always at center of picture:
  14174. @example
  14175. zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
  14176. @end example
  14177. @item
  14178. Same as above but without pausing:
  14179. @example
  14180. zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
  14181. @end example
  14182. @end itemize
  14183. @anchor{zscale}
  14184. @section zscale
  14185. Scale (resize) the input video, using the z.lib library:
  14186. @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
  14187. filter, you need to configure FFmpeg with @code{--enable-libzimg}.
  14188. The zscale filter forces the output display aspect ratio to be the same
  14189. as the input, by changing the output sample aspect ratio.
  14190. If the input image format is different from the format requested by
  14191. the next filter, the zscale filter will convert the input to the
  14192. requested format.
  14193. @subsection Options
  14194. The filter accepts the following options.
  14195. @table @option
  14196. @item width, w
  14197. @item height, h
  14198. Set the output video dimension expression. Default value is the input
  14199. dimension.
  14200. If the @var{width} or @var{w} value is 0, the input width is used for
  14201. the output. If the @var{height} or @var{h} value is 0, the input height
  14202. is used for the output.
  14203. If one and only one of the values is -n with n >= 1, the zscale filter
  14204. will use a value that maintains the aspect ratio of the input image,
  14205. calculated from the other specified dimension. After that it will,
  14206. however, make sure that the calculated dimension is divisible by n and
  14207. adjust the value if necessary.
  14208. If both values are -n with n >= 1, the behavior will be identical to
  14209. both values being set to 0 as previously detailed.
  14210. See below for the list of accepted constants for use in the dimension
  14211. expression.
  14212. @item size, s
  14213. Set the video size. For the syntax of this option, check the
  14214. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  14215. @item dither, d
  14216. Set the dither type.
  14217. Possible values are:
  14218. @table @var
  14219. @item none
  14220. @item ordered
  14221. @item random
  14222. @item error_diffusion
  14223. @end table
  14224. Default is none.
  14225. @item filter, f
  14226. Set the resize filter type.
  14227. Possible values are:
  14228. @table @var
  14229. @item point
  14230. @item bilinear
  14231. @item bicubic
  14232. @item spline16
  14233. @item spline36
  14234. @item lanczos
  14235. @end table
  14236. Default is bilinear.
  14237. @item range, r
  14238. Set the color range.
  14239. Possible values are:
  14240. @table @var
  14241. @item input
  14242. @item limited
  14243. @item full
  14244. @end table
  14245. Default is same as input.
  14246. @item primaries, p
  14247. Set the color primaries.
  14248. Possible values are:
  14249. @table @var
  14250. @item input
  14251. @item 709
  14252. @item unspecified
  14253. @item 170m
  14254. @item 240m
  14255. @item 2020
  14256. @end table
  14257. Default is same as input.
  14258. @item transfer, t
  14259. Set the transfer characteristics.
  14260. Possible values are:
  14261. @table @var
  14262. @item input
  14263. @item 709
  14264. @item unspecified
  14265. @item 601
  14266. @item linear
  14267. @item 2020_10
  14268. @item 2020_12
  14269. @item smpte2084
  14270. @item iec61966-2-1
  14271. @item arib-std-b67
  14272. @end table
  14273. Default is same as input.
  14274. @item matrix, m
  14275. Set the colorspace matrix.
  14276. Possible value are:
  14277. @table @var
  14278. @item input
  14279. @item 709
  14280. @item unspecified
  14281. @item 470bg
  14282. @item 170m
  14283. @item 2020_ncl
  14284. @item 2020_cl
  14285. @end table
  14286. Default is same as input.
  14287. @item rangein, rin
  14288. Set the input color range.
  14289. Possible values are:
  14290. @table @var
  14291. @item input
  14292. @item limited
  14293. @item full
  14294. @end table
  14295. Default is same as input.
  14296. @item primariesin, pin
  14297. Set the input color primaries.
  14298. Possible values are:
  14299. @table @var
  14300. @item input
  14301. @item 709
  14302. @item unspecified
  14303. @item 170m
  14304. @item 240m
  14305. @item 2020
  14306. @end table
  14307. Default is same as input.
  14308. @item transferin, tin
  14309. Set the input transfer characteristics.
  14310. Possible values are:
  14311. @table @var
  14312. @item input
  14313. @item 709
  14314. @item unspecified
  14315. @item 601
  14316. @item linear
  14317. @item 2020_10
  14318. @item 2020_12
  14319. @end table
  14320. Default is same as input.
  14321. @item matrixin, min
  14322. Set the input colorspace matrix.
  14323. Possible value are:
  14324. @table @var
  14325. @item input
  14326. @item 709
  14327. @item unspecified
  14328. @item 470bg
  14329. @item 170m
  14330. @item 2020_ncl
  14331. @item 2020_cl
  14332. @end table
  14333. @item chromal, c
  14334. Set the output chroma location.
  14335. Possible values are:
  14336. @table @var
  14337. @item input
  14338. @item left
  14339. @item center
  14340. @item topleft
  14341. @item top
  14342. @item bottomleft
  14343. @item bottom
  14344. @end table
  14345. @item chromalin, cin
  14346. Set the input chroma location.
  14347. Possible values are:
  14348. @table @var
  14349. @item input
  14350. @item left
  14351. @item center
  14352. @item topleft
  14353. @item top
  14354. @item bottomleft
  14355. @item bottom
  14356. @end table
  14357. @item npl
  14358. Set the nominal peak luminance.
  14359. @end table
  14360. The values of the @option{w} and @option{h} options are expressions
  14361. containing the following constants:
  14362. @table @var
  14363. @item in_w
  14364. @item in_h
  14365. The input width and height
  14366. @item iw
  14367. @item ih
  14368. These are the same as @var{in_w} and @var{in_h}.
  14369. @item out_w
  14370. @item out_h
  14371. The output (scaled) width and height
  14372. @item ow
  14373. @item oh
  14374. These are the same as @var{out_w} and @var{out_h}
  14375. @item a
  14376. The same as @var{iw} / @var{ih}
  14377. @item sar
  14378. input sample aspect ratio
  14379. @item dar
  14380. The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
  14381. @item hsub
  14382. @item vsub
  14383. horizontal and vertical input chroma subsample values. For example for the
  14384. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  14385. @item ohsub
  14386. @item ovsub
  14387. horizontal and vertical output chroma subsample values. For example for the
  14388. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  14389. @end table
  14390. @table @option
  14391. @end table
  14392. @c man end VIDEO FILTERS
  14393. @chapter OpenCL Video Filters
  14394. @c man begin OPENCL VIDEO FILTERS
  14395. Below is a description of the currently available OpenCL video filters.
  14396. To enable compilation of these filters you need to configure FFmpeg with
  14397. @code{--enable-opencl}.
  14398. Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
  14399. @table @option
  14400. @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
  14401. Initialise a new hardware device of type @var{opencl} called @var{name}, using the
  14402. given device parameters.
  14403. @item -filter_hw_device @var{name}
  14404. Pass the hardware device called @var{name} to all filters in any filter graph.
  14405. @end table
  14406. For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
  14407. @itemize
  14408. @item
  14409. Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
  14410. @example
  14411. -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
  14412. @end example
  14413. @end itemize
  14414. Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(@ref{hwupload}) to hardware surfaces connected to the appropriate device before being used and then downloaded(@ref{hwdownload}) back to normal memory. Note that @ref{hwupload} will upload to a surface with the same layout as the software frame, so it may be necessary to add a @ref{format} filter immediately before to get the input into the right format and @ref{hwdownload} does not support all formats on the output - it may be necessary to insert an additional @ref{format} filter immediately following in the graph to get the output in a supported format.
  14415. @section avgblur_opencl
  14416. Apply average blur filter.
  14417. The filter accepts the following options:
  14418. @table @option
  14419. @item sizeX
  14420. Set horizontal radius size.
  14421. Range is @code{[1, 1024]} and default value is @code{1}.
  14422. @item planes
  14423. Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
  14424. @item sizeY
  14425. Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
  14426. @end table
  14427. @subsection Example
  14428. @itemize
  14429. @item
  14430. Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations.
  14431. @example
  14432. -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
  14433. @end example
  14434. @end itemize
  14435. @section boxblur_opencl
  14436. Apply a boxblur algorithm to the input video.
  14437. It accepts the following parameters:
  14438. @table @option
  14439. @item luma_radius, lr
  14440. @item luma_power, lp
  14441. @item chroma_radius, cr
  14442. @item chroma_power, cp
  14443. @item alpha_radius, ar
  14444. @item alpha_power, ap
  14445. @end table
  14446. A description of the accepted options follows.
  14447. @table @option
  14448. @item luma_radius, lr
  14449. @item chroma_radius, cr
  14450. @item alpha_radius, ar
  14451. Set an expression for the box radius in pixels used for blurring the
  14452. corresponding input plane.
  14453. The radius value must be a non-negative number, and must not be
  14454. greater than the value of the expression @code{min(w,h)/2} for the
  14455. luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
  14456. planes.
  14457. Default value for @option{luma_radius} is "2". If not specified,
  14458. @option{chroma_radius} and @option{alpha_radius} default to the
  14459. corresponding value set for @option{luma_radius}.
  14460. The expressions can contain the following constants:
  14461. @table @option
  14462. @item w
  14463. @item h
  14464. The input width and height in pixels.
  14465. @item cw
  14466. @item ch
  14467. The input chroma image width and height in pixels.
  14468. @item hsub
  14469. @item vsub
  14470. The horizontal and vertical chroma subsample values. For example, for the
  14471. pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
  14472. @end table
  14473. @item luma_power, lp
  14474. @item chroma_power, cp
  14475. @item alpha_power, ap
  14476. Specify how many times the boxblur filter is applied to the
  14477. corresponding plane.
  14478. Default value for @option{luma_power} is 2. If not specified,
  14479. @option{chroma_power} and @option{alpha_power} default to the
  14480. corresponding value set for @option{luma_power}.
  14481. A value of 0 will disable the effect.
  14482. @end table
  14483. @subsection Examples
  14484. Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses @var{luma_radius}, @var{chroma_radius}, @var{alpha_radius} for each plane respectively. The filter will apply @var{luma_power}, @var{chroma_power}, @var{alpha_power} times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations.
  14485. @itemize
  14486. @item
  14487. Apply a boxblur filter with the luma, chroma, and alpha radius
  14488. set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image.
  14489. @example
  14490. -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
  14491. -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
  14492. @end example
  14493. @item
  14494. Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7.
  14495. For the luma plane, a 2x2 box radius will be run once.
  14496. For the chroma plane, a 4x4 box radius will be run 5 times.
  14497. For the alpha plane, a 3x3 box radius will be run 7 times.
  14498. @example
  14499. -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
  14500. @end example
  14501. @end itemize
  14502. @section convolution_opencl
  14503. Apply convolution of 3x3, 5x5, 7x7 matrix.
  14504. The filter accepts the following options:
  14505. @table @option
  14506. @item 0m
  14507. @item 1m
  14508. @item 2m
  14509. @item 3m
  14510. Set matrix for each plane.
  14511. Matrix is sequence of 9, 25 or 49 signed numbers.
  14512. Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
  14513. @item 0rdiv
  14514. @item 1rdiv
  14515. @item 2rdiv
  14516. @item 3rdiv
  14517. Set multiplier for calculated value for each plane.
  14518. If unset or 0, it will be sum of all matrix elements.
  14519. The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
  14520. @item 0bias
  14521. @item 1bias
  14522. @item 2bias
  14523. @item 3bias
  14524. Set bias for each plane. This value is added to the result of the multiplication.
  14525. Useful for making the overall image brighter or darker.
  14526. The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
  14527. @end table
  14528. @subsection Examples
  14529. @itemize
  14530. @item
  14531. Apply sharpen:
  14532. @example
  14533. -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
  14534. @end example
  14535. @item
  14536. Apply blur:
  14537. @example
  14538. -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
  14539. @end example
  14540. @item
  14541. Apply edge enhance:
  14542. @example
  14543. -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
  14544. @end example
  14545. @item
  14546. Apply edge detect:
  14547. @example
  14548. -i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT
  14549. @end example
  14550. @item
  14551. Apply laplacian edge detector which includes diagonals:
  14552. @example
  14553. -i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT
  14554. @end example
  14555. @item
  14556. Apply emboss:
  14557. @example
  14558. -i INPUT -vf "hwupload, convolution_opencl=-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, hwdownload" OUTPUT
  14559. @end example
  14560. @end itemize
  14561. @section dilation_opencl
  14562. Apply dilation effect to the video.
  14563. This filter replaces the pixel by the local(3x3) maximum.
  14564. It accepts the following options:
  14565. @table @option
  14566. @item threshold0
  14567. @item threshold1
  14568. @item threshold2
  14569. @item threshold3
  14570. Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
  14571. If @code{0}, plane will remain unchanged.
  14572. @item coordinates
  14573. Flag which specifies the pixel to refer to.
  14574. Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
  14575. Flags to local 3x3 coordinates region centered on @code{x}:
  14576. 1 2 3
  14577. 4 x 5
  14578. 6 7 8
  14579. @end table
  14580. @subsection Example
  14581. @itemize
  14582. @item
  14583. Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane.
  14584. @example
  14585. -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
  14586. @end example
  14587. @end itemize
  14588. @section erosion_opencl
  14589. Apply erosion effect to the video.
  14590. This filter replaces the pixel by the local(3x3) minimum.
  14591. It accepts the following options:
  14592. @table @option
  14593. @item threshold0
  14594. @item threshold1
  14595. @item threshold2
  14596. @item threshold3
  14597. Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
  14598. If @code{0}, plane will remain unchanged.
  14599. @item coordinates
  14600. Flag which specifies the pixel to refer to.
  14601. Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
  14602. Flags to local 3x3 coordinates region centered on @code{x}:
  14603. 1 2 3
  14604. 4 x 5
  14605. 6 7 8
  14606. @end table
  14607. @subsection Example
  14608. @itemize
  14609. @item
  14610. Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane.
  14611. @example
  14612. -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
  14613. @end example
  14614. @end itemize
  14615. @section colorkey_opencl
  14616. RGB colorspace color keying.
  14617. The filter accepts the following options:
  14618. @table @option
  14619. @item color
  14620. The color which will be replaced with transparency.
  14621. @item similarity
  14622. Similarity percentage with the key color.
  14623. 0.01 matches only the exact key color, while 1.0 matches everything.
  14624. @item blend
  14625. Blend percentage.
  14626. 0.0 makes pixels either fully transparent, or not transparent at all.
  14627. Higher values result in semi-transparent pixels, with a higher transparency
  14628. the more similar the pixels color is to the key color.
  14629. @end table
  14630. @subsection Examples
  14631. @itemize
  14632. @item
  14633. Make every semi-green pixel in the input transparent with some slight blending:
  14634. @example
  14635. -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
  14636. @end example
  14637. @end itemize
  14638. @section overlay_opencl
  14639. Overlay one video on top of another.
  14640. It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
  14641. This filter requires same memory layout for all the inputs. So, format conversion may be needed.
  14642. The filter accepts the following options:
  14643. @table @option
  14644. @item x
  14645. Set the x coordinate of the overlaid video on the main video.
  14646. Default value is @code{0}.
  14647. @item y
  14648. Set the x coordinate of the overlaid video on the main video.
  14649. Default value is @code{0}.
  14650. @end table
  14651. @subsection Examples
  14652. @itemize
  14653. @item
  14654. Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
  14655. @example
  14656. -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
  14657. @end example
  14658. @item
  14659. The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
  14660. @example
  14661. -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
  14662. @end example
  14663. @end itemize
  14664. @section prewitt_opencl
  14665. Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
  14666. The filter accepts the following option:
  14667. @table @option
  14668. @item planes
  14669. Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
  14670. @item scale
  14671. Set value which will be multiplied with filtered result.
  14672. Range is @code{[0.0, 65535]} and default value is @code{1.0}.
  14673. @item delta
  14674. Set value which will be added to filtered result.
  14675. Range is @code{[-65535, 65535]} and default value is @code{0.0}.
  14676. @end table
  14677. @subsection Example
  14678. @itemize
  14679. @item
  14680. Apply the Prewitt operator with scale set to 2 and delta set to 10.
  14681. @example
  14682. -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
  14683. @end example
  14684. @end itemize
  14685. @section roberts_opencl
  14686. Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
  14687. The filter accepts the following option:
  14688. @table @option
  14689. @item planes
  14690. Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
  14691. @item scale
  14692. Set value which will be multiplied with filtered result.
  14693. Range is @code{[0.0, 65535]} and default value is @code{1.0}.
  14694. @item delta
  14695. Set value which will be added to filtered result.
  14696. Range is @code{[-65535, 65535]} and default value is @code{0.0}.
  14697. @end table
  14698. @subsection Example
  14699. @itemize
  14700. @item
  14701. Apply the Roberts cross operator with scale set to 2 and delta set to 10
  14702. @example
  14703. -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
  14704. @end example
  14705. @end itemize
  14706. @section sobel_opencl
  14707. Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
  14708. The filter accepts the following option:
  14709. @table @option
  14710. @item planes
  14711. Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
  14712. @item scale
  14713. Set value which will be multiplied with filtered result.
  14714. Range is @code{[0.0, 65535]} and default value is @code{1.0}.
  14715. @item delta
  14716. Set value which will be added to filtered result.
  14717. Range is @code{[-65535, 65535]} and default value is @code{0.0}.
  14718. @end table
  14719. @subsection Example
  14720. @itemize
  14721. @item
  14722. Apply sobel operator with scale set to 2 and delta set to 10
  14723. @example
  14724. -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
  14725. @end example
  14726. @end itemize
  14727. @section tonemap_opencl
  14728. Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
  14729. It accepts the following parameters:
  14730. @table @option
  14731. @item tonemap
  14732. Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
  14733. @item param
  14734. Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
  14735. @item desat
  14736. Apply desaturation for highlights that exceed this level of brightness. The
  14737. higher the parameter, the more color information will be preserved. This
  14738. setting helps prevent unnaturally blown-out colors for super-highlights, by
  14739. (smoothly) turning into white instead. This makes images feel more natural,
  14740. at the cost of reducing information about out-of-range colors.
  14741. The default value is 0.5, and the algorithm here is a little different from
  14742. the cpu version tonemap currently. A setting of 0.0 disables this option.
  14743. @item threshold
  14744. The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
  14745. is used to detect whether the scene has changed or not. If the distance between
  14746. the current frame average brightness and the current running average exceeds
  14747. a threshold value, we would re-calculate scene average and peak brightness.
  14748. The default value is 0.2.
  14749. @item format
  14750. Specify the output pixel format.
  14751. Currently supported formats are:
  14752. @table @var
  14753. @item p010
  14754. @item nv12
  14755. @end table
  14756. @item range, r
  14757. Set the output color range.
  14758. Possible values are:
  14759. @table @var
  14760. @item tv/mpeg
  14761. @item pc/jpeg
  14762. @end table
  14763. Default is same as input.
  14764. @item primaries, p
  14765. Set the output color primaries.
  14766. Possible values are:
  14767. @table @var
  14768. @item bt709
  14769. @item bt2020
  14770. @end table
  14771. Default is same as input.
  14772. @item transfer, t
  14773. Set the output transfer characteristics.
  14774. Possible values are:
  14775. @table @var
  14776. @item bt709
  14777. @item bt2020
  14778. @end table
  14779. Default is bt709.
  14780. @item matrix, m
  14781. Set the output colorspace matrix.
  14782. Possible value are:
  14783. @table @var
  14784. @item bt709
  14785. @item bt2020
  14786. @end table
  14787. Default is same as input.
  14788. @end table
  14789. @subsection Example
  14790. @itemize
  14791. @item
  14792. Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
  14793. @example
  14794. -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
  14795. @end example
  14796. @end itemize
  14797. @section unsharp_opencl
  14798. Sharpen or blur the input video.
  14799. It accepts the following parameters:
  14800. @table @option
  14801. @item luma_msize_x, lx
  14802. Set the luma matrix horizontal size.
  14803. Range is @code{[1, 23]} and default value is @code{5}.
  14804. @item luma_msize_y, ly
  14805. Set the luma matrix vertical size.
  14806. Range is @code{[1, 23]} and default value is @code{5}.
  14807. @item luma_amount, la
  14808. Set the luma effect strength.
  14809. Range is @code{[-10, 10]} and default value is @code{1.0}.
  14810. Negative values will blur the input video, while positive values will
  14811. sharpen it, a value of zero will disable the effect.
  14812. @item chroma_msize_x, cx
  14813. Set the chroma matrix horizontal size.
  14814. Range is @code{[1, 23]} and default value is @code{5}.
  14815. @item chroma_msize_y, cy
  14816. Set the chroma matrix vertical size.
  14817. Range is @code{[1, 23]} and default value is @code{5}.
  14818. @item chroma_amount, ca
  14819. Set the chroma effect strength.
  14820. Range is @code{[-10, 10]} and default value is @code{0.0}.
  14821. Negative values will blur the input video, while positive values will
  14822. sharpen it, a value of zero will disable the effect.
  14823. @end table
  14824. All parameters are optional and default to the equivalent of the
  14825. string '5:5:1.0:5:5:0.0'.
  14826. @subsection Examples
  14827. @itemize
  14828. @item
  14829. Apply strong luma sharpen effect:
  14830. @example
  14831. -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
  14832. @end example
  14833. @item
  14834. Apply a strong blur of both luma and chroma parameters:
  14835. @example
  14836. -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
  14837. @end example
  14838. @end itemize
  14839. @c man end OPENCL VIDEO FILTERS
  14840. @chapter Video Sources
  14841. @c man begin VIDEO SOURCES
  14842. Below is a description of the currently available video sources.
  14843. @section buffer
  14844. Buffer video frames, and make them available to the filter chain.
  14845. This source is mainly intended for a programmatic use, in particular
  14846. through the interface defined in @file{libavfilter/vsrc_buffer.h}.
  14847. It accepts the following parameters:
  14848. @table @option
  14849. @item video_size
  14850. Specify the size (width and height) of the buffered video frames. For the
  14851. syntax of this option, check the
  14852. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  14853. @item width
  14854. The input video width.
  14855. @item height
  14856. The input video height.
  14857. @item pix_fmt
  14858. A string representing the pixel format of the buffered video frames.
  14859. It may be a number corresponding to a pixel format, or a pixel format
  14860. name.
  14861. @item time_base
  14862. Specify the timebase assumed by the timestamps of the buffered frames.
  14863. @item frame_rate
  14864. Specify the frame rate expected for the video stream.
  14865. @item pixel_aspect, sar
  14866. The sample (pixel) aspect ratio of the input video.
  14867. @item sws_param
  14868. Specify the optional parameters to be used for the scale filter which
  14869. is automatically inserted when an input change is detected in the
  14870. input size or format.
  14871. @item hw_frames_ctx
  14872. When using a hardware pixel format, this should be a reference to an
  14873. AVHWFramesContext describing input frames.
  14874. @end table
  14875. For example:
  14876. @example
  14877. buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
  14878. @end example
  14879. will instruct the source to accept video frames with size 320x240 and
  14880. with format "yuv410p", assuming 1/24 as the timestamps timebase and
  14881. square pixels (1:1 sample aspect ratio).
  14882. Since the pixel format with name "yuv410p" corresponds to the number 6
  14883. (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
  14884. this example corresponds to:
  14885. @example
  14886. buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
  14887. @end example
  14888. Alternatively, the options can be specified as a flat string, but this
  14889. syntax is deprecated:
  14890. @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}]
  14891. @section cellauto
  14892. Create a pattern generated by an elementary cellular automaton.
  14893. The initial state of the cellular automaton can be defined through the
  14894. @option{filename} and @option{pattern} options. If such options are
  14895. not specified an initial state is created randomly.
  14896. At each new frame a new row in the video is filled with the result of
  14897. the cellular automaton next generation. The behavior when the whole
  14898. frame is filled is defined by the @option{scroll} option.
  14899. This source accepts the following options:
  14900. @table @option
  14901. @item filename, f
  14902. Read the initial cellular automaton state, i.e. the starting row, from
  14903. the specified file.
  14904. In the file, each non-whitespace character is considered an alive
  14905. cell, a newline will terminate the row, and further characters in the
  14906. file will be ignored.
  14907. @item pattern, p
  14908. Read the initial cellular automaton state, i.e. the starting row, from
  14909. the specified string.
  14910. Each non-whitespace character in the string is considered an alive
  14911. cell, a newline will terminate the row, and further characters in the
  14912. string will be ignored.
  14913. @item rate, r
  14914. Set the video rate, that is the number of frames generated per second.
  14915. Default is 25.
  14916. @item random_fill_ratio, ratio
  14917. Set the random fill ratio for the initial cellular automaton row. It
  14918. is a floating point number value ranging from 0 to 1, defaults to
  14919. 1/PHI.
  14920. This option is ignored when a file or a pattern is specified.
  14921. @item random_seed, seed
  14922. Set the seed for filling randomly the initial row, must be an integer
  14923. included between 0 and UINT32_MAX. If not specified, or if explicitly
  14924. set to -1, the filter will try to use a good random seed on a best
  14925. effort basis.
  14926. @item rule
  14927. Set the cellular automaton rule, it is a number ranging from 0 to 255.
  14928. Default value is 110.
  14929. @item size, s
  14930. Set the size of the output video. For the syntax of this option, check the
  14931. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  14932. If @option{filename} or @option{pattern} is specified, the size is set
  14933. by default to the width of the specified initial state row, and the
  14934. height is set to @var{width} * PHI.
  14935. If @option{size} is set, it must contain the width of the specified
  14936. pattern string, and the specified pattern will be centered in the
  14937. larger row.
  14938. If a filename or a pattern string is not specified, the size value
  14939. defaults to "320x518" (used for a randomly generated initial state).
  14940. @item scroll
  14941. If set to 1, scroll the output upward when all the rows in the output
  14942. have been already filled. If set to 0, the new generated row will be
  14943. written over the top row just after the bottom row is filled.
  14944. Defaults to 1.
  14945. @item start_full, full
  14946. If set to 1, completely fill the output with generated rows before
  14947. outputting the first frame.
  14948. This is the default behavior, for disabling set the value to 0.
  14949. @item stitch
  14950. If set to 1, stitch the left and right row edges together.
  14951. This is the default behavior, for disabling set the value to 0.
  14952. @end table
  14953. @subsection Examples
  14954. @itemize
  14955. @item
  14956. Read the initial state from @file{pattern}, and specify an output of
  14957. size 200x400.
  14958. @example
  14959. cellauto=f=pattern:s=200x400
  14960. @end example
  14961. @item
  14962. Generate a random initial row with a width of 200 cells, with a fill
  14963. ratio of 2/3:
  14964. @example
  14965. cellauto=ratio=2/3:s=200x200
  14966. @end example
  14967. @item
  14968. Create a pattern generated by rule 18 starting by a single alive cell
  14969. centered on an initial row with width 100:
  14970. @example
  14971. cellauto=p=@@:s=100x400:full=0:rule=18
  14972. @end example
  14973. @item
  14974. Specify a more elaborated initial pattern:
  14975. @example
  14976. cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
  14977. @end example
  14978. @end itemize
  14979. @anchor{coreimagesrc}
  14980. @section coreimagesrc
  14981. Video source generated on GPU using Apple's CoreImage API on OSX.
  14982. This video source is a specialized version of the @ref{coreimage} video filter.
  14983. Use a core image generator at the beginning of the applied filterchain to
  14984. generate the content.
  14985. The coreimagesrc video source accepts the following options:
  14986. @table @option
  14987. @item list_generators
  14988. List all available generators along with all their respective options as well as
  14989. possible minimum and maximum values along with the default values.
  14990. @example
  14991. list_generators=true
  14992. @end example
  14993. @item size, s
  14994. Specify the size of the sourced video. For the syntax of this option, check the
  14995. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  14996. The default value is @code{320x240}.
  14997. @item rate, r
  14998. Specify the frame rate of the sourced video, as the number of frames
  14999. generated per second. It has to be a string in the format
  15000. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  15001. number or a valid video frame rate abbreviation. The default value is
  15002. "25".
  15003. @item sar
  15004. Set the sample aspect ratio of the sourced video.
  15005. @item duration, d
  15006. Set the duration of the sourced video. See
  15007. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  15008. for the accepted syntax.
  15009. If not specified, or the expressed duration is negative, the video is
  15010. supposed to be generated forever.
  15011. @end table
  15012. Additionally, all options of the @ref{coreimage} video filter are accepted.
  15013. A complete filterchain can be used for further processing of the
  15014. generated input without CPU-HOST transfer. See @ref{coreimage} documentation
  15015. and examples for details.
  15016. @subsection Examples
  15017. @itemize
  15018. @item
  15019. Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
  15020. given as complete and escaped command-line for Apple's standard bash shell:
  15021. @example
  15022. ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
  15023. @end example
  15024. This example is equivalent to the QRCode example of @ref{coreimage} without the
  15025. need for a nullsrc video source.
  15026. @end itemize
  15027. @section mandelbrot
  15028. Generate a Mandelbrot set fractal, and progressively zoom towards the
  15029. point specified with @var{start_x} and @var{start_y}.
  15030. This source accepts the following options:
  15031. @table @option
  15032. @item end_pts
  15033. Set the terminal pts value. Default value is 400.
  15034. @item end_scale
  15035. Set the terminal scale value.
  15036. Must be a floating point value. Default value is 0.3.
  15037. @item inner
  15038. Set the inner coloring mode, that is the algorithm used to draw the
  15039. Mandelbrot fractal internal region.
  15040. It shall assume one of the following values:
  15041. @table @option
  15042. @item black
  15043. Set black mode.
  15044. @item convergence
  15045. Show time until convergence.
  15046. @item mincol
  15047. Set color based on point closest to the origin of the iterations.
  15048. @item period
  15049. Set period mode.
  15050. @end table
  15051. Default value is @var{mincol}.
  15052. @item bailout
  15053. Set the bailout value. Default value is 10.0.
  15054. @item maxiter
  15055. Set the maximum of iterations performed by the rendering
  15056. algorithm. Default value is 7189.
  15057. @item outer
  15058. Set outer coloring mode.
  15059. It shall assume one of following values:
  15060. @table @option
  15061. @item iteration_count
  15062. Set iteration count mode.
  15063. @item normalized_iteration_count
  15064. set normalized iteration count mode.
  15065. @end table
  15066. Default value is @var{normalized_iteration_count}.
  15067. @item rate, r
  15068. Set frame rate, expressed as number of frames per second. Default
  15069. value is "25".
  15070. @item size, s
  15071. Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
  15072. size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
  15073. @item start_scale
  15074. Set the initial scale value. Default value is 3.0.
  15075. @item start_x
  15076. Set the initial x position. Must be a floating point value between
  15077. -100 and 100. Default value is -0.743643887037158704752191506114774.
  15078. @item start_y
  15079. Set the initial y position. Must be a floating point value between
  15080. -100 and 100. Default value is -0.131825904205311970493132056385139.
  15081. @end table
  15082. @section mptestsrc
  15083. Generate various test patterns, as generated by the MPlayer test filter.
  15084. The size of the generated video is fixed, and is 256x256.
  15085. This source is useful in particular for testing encoding features.
  15086. This source accepts the following options:
  15087. @table @option
  15088. @item rate, r
  15089. Specify the frame rate of the sourced video, as the number of frames
  15090. generated per second. It has to be a string in the format
  15091. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  15092. number or a valid video frame rate abbreviation. The default value is
  15093. "25".
  15094. @item duration, d
  15095. Set the duration of the sourced video. See
  15096. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  15097. for the accepted syntax.
  15098. If not specified, or the expressed duration is negative, the video is
  15099. supposed to be generated forever.
  15100. @item test, t
  15101. Set the number or the name of the test to perform. Supported tests are:
  15102. @table @option
  15103. @item dc_luma
  15104. @item dc_chroma
  15105. @item freq_luma
  15106. @item freq_chroma
  15107. @item amp_luma
  15108. @item amp_chroma
  15109. @item cbp
  15110. @item mv
  15111. @item ring1
  15112. @item ring2
  15113. @item all
  15114. @end table
  15115. Default value is "all", which will cycle through the list of all tests.
  15116. @end table
  15117. Some examples:
  15118. @example
  15119. mptestsrc=t=dc_luma
  15120. @end example
  15121. will generate a "dc_luma" test pattern.
  15122. @section frei0r_src
  15123. Provide a frei0r source.
  15124. To enable compilation of this filter you need to install the frei0r
  15125. header and configure FFmpeg with @code{--enable-frei0r}.
  15126. This source accepts the following parameters:
  15127. @table @option
  15128. @item size
  15129. The size of the video to generate. For the syntax of this option, check the
  15130. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15131. @item framerate
  15132. The framerate of the generated video. It may be a string of the form
  15133. @var{num}/@var{den} or a frame rate abbreviation.
  15134. @item filter_name
  15135. The name to the frei0r source to load. For more information regarding frei0r and
  15136. how to set the parameters, read the @ref{frei0r} section in the video filters
  15137. documentation.
  15138. @item filter_params
  15139. A '|'-separated list of parameters to pass to the frei0r source.
  15140. @end table
  15141. For example, to generate a frei0r partik0l source with size 200x200
  15142. and frame rate 10 which is overlaid on the overlay filter main input:
  15143. @example
  15144. frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
  15145. @end example
  15146. @section life
  15147. Generate a life pattern.
  15148. This source is based on a generalization of John Conway's life game.
  15149. The sourced input represents a life grid, each pixel represents a cell
  15150. which can be in one of two possible states, alive or dead. Every cell
  15151. interacts with its eight neighbours, which are the cells that are
  15152. horizontally, vertically, or diagonally adjacent.
  15153. At each interaction the grid evolves according to the adopted rule,
  15154. which specifies the number of neighbor alive cells which will make a
  15155. cell stay alive or born. The @option{rule} option allows one to specify
  15156. the rule to adopt.
  15157. This source accepts the following options:
  15158. @table @option
  15159. @item filename, f
  15160. Set the file from which to read the initial grid state. In the file,
  15161. each non-whitespace character is considered an alive cell, and newline
  15162. is used to delimit the end of each row.
  15163. If this option is not specified, the initial grid is generated
  15164. randomly.
  15165. @item rate, r
  15166. Set the video rate, that is the number of frames generated per second.
  15167. Default is 25.
  15168. @item random_fill_ratio, ratio
  15169. Set the random fill ratio for the initial random grid. It is a
  15170. floating point number value ranging from 0 to 1, defaults to 1/PHI.
  15171. It is ignored when a file is specified.
  15172. @item random_seed, seed
  15173. Set the seed for filling the initial random grid, must be an integer
  15174. included between 0 and UINT32_MAX. If not specified, or if explicitly
  15175. set to -1, the filter will try to use a good random seed on a best
  15176. effort basis.
  15177. @item rule
  15178. Set the life rule.
  15179. A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
  15180. where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
  15181. @var{NS} specifies the number of alive neighbor cells which make a
  15182. live cell stay alive, and @var{NB} the number of alive neighbor cells
  15183. which make a dead cell to become alive (i.e. to "born").
  15184. "s" and "b" can be used in place of "S" and "B", respectively.
  15185. Alternatively a rule can be specified by an 18-bits integer. The 9
  15186. high order bits are used to encode the next cell state if it is alive
  15187. for each number of neighbor alive cells, the low order bits specify
  15188. the rule for "borning" new cells. Higher order bits encode for an
  15189. higher number of neighbor cells.
  15190. For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
  15191. rule of 12 and a born rule of 9, which corresponds to "S23/B03".
  15192. Default value is "S23/B3", which is the original Conway's game of life
  15193. rule, and will keep a cell alive if it has 2 or 3 neighbor alive
  15194. cells, and will born a new cell if there are three alive cells around
  15195. a dead cell.
  15196. @item size, s
  15197. Set the size of the output video. For the syntax of this option, check the
  15198. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15199. If @option{filename} is specified, the size is set by default to the
  15200. same size of the input file. If @option{size} is set, it must contain
  15201. the size specified in the input file, and the initial grid defined in
  15202. that file is centered in the larger resulting area.
  15203. If a filename is not specified, the size value defaults to "320x240"
  15204. (used for a randomly generated initial grid).
  15205. @item stitch
  15206. If set to 1, stitch the left and right grid edges together, and the
  15207. top and bottom edges also. Defaults to 1.
  15208. @item mold
  15209. Set cell mold speed. If set, a dead cell will go from @option{death_color} to
  15210. @option{mold_color} with a step of @option{mold}. @option{mold} can have a
  15211. value from 0 to 255.
  15212. @item life_color
  15213. Set the color of living (or new born) cells.
  15214. @item death_color
  15215. Set the color of dead cells. If @option{mold} is set, this is the first color
  15216. used to represent a dead cell.
  15217. @item mold_color
  15218. Set mold color, for definitely dead and moldy cells.
  15219. For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
  15220. ffmpeg-utils manual,ffmpeg-utils}.
  15221. @end table
  15222. @subsection Examples
  15223. @itemize
  15224. @item
  15225. Read a grid from @file{pattern}, and center it on a grid of size
  15226. 300x300 pixels:
  15227. @example
  15228. life=f=pattern:s=300x300
  15229. @end example
  15230. @item
  15231. Generate a random grid of size 200x200, with a fill ratio of 2/3:
  15232. @example
  15233. life=ratio=2/3:s=200x200
  15234. @end example
  15235. @item
  15236. Specify a custom rule for evolving a randomly generated grid:
  15237. @example
  15238. life=rule=S14/B34
  15239. @end example
  15240. @item
  15241. Full example with slow death effect (mold) using @command{ffplay}:
  15242. @example
  15243. ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
  15244. @end example
  15245. @end itemize
  15246. @anchor{allrgb}
  15247. @anchor{allyuv}
  15248. @anchor{color}
  15249. @anchor{haldclutsrc}
  15250. @anchor{nullsrc}
  15251. @anchor{pal75bars}
  15252. @anchor{pal100bars}
  15253. @anchor{rgbtestsrc}
  15254. @anchor{smptebars}
  15255. @anchor{smptehdbars}
  15256. @anchor{testsrc}
  15257. @anchor{testsrc2}
  15258. @anchor{yuvtestsrc}
  15259. @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
  15260. The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
  15261. The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
  15262. The @code{color} source provides an uniformly colored input.
  15263. The @code{haldclutsrc} source provides an identity Hald CLUT. See also
  15264. @ref{haldclut} filter.
  15265. The @code{nullsrc} source returns unprocessed video frames. It is
  15266. mainly useful to be employed in analysis / debugging tools, or as the
  15267. source for filters which ignore the input data.
  15268. The @code{pal75bars} source generates a color bars pattern, based on
  15269. EBU PAL recommendations with 75% color levels.
  15270. The @code{pal100bars} source generates a color bars pattern, based on
  15271. EBU PAL recommendations with 100% color levels.
  15272. The @code{rgbtestsrc} source generates an RGB test pattern useful for
  15273. detecting RGB vs BGR issues. You should see a red, green and blue
  15274. stripe from top to bottom.
  15275. The @code{smptebars} source generates a color bars pattern, based on
  15276. the SMPTE Engineering Guideline EG 1-1990.
  15277. The @code{smptehdbars} source generates a color bars pattern, based on
  15278. the SMPTE RP 219-2002.
  15279. The @code{testsrc} source generates a test video pattern, showing a
  15280. color pattern, a scrolling gradient and a timestamp. This is mainly
  15281. intended for testing purposes.
  15282. The @code{testsrc2} source is similar to testsrc, but supports more
  15283. pixel formats instead of just @code{rgb24}. This allows using it as an
  15284. input for other tests without requiring a format conversion.
  15285. The @code{yuvtestsrc} source generates an YUV test pattern. You should
  15286. see a y, cb and cr stripe from top to bottom.
  15287. The sources accept the following parameters:
  15288. @table @option
  15289. @item level
  15290. Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
  15291. source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
  15292. pixels to be used as identity matrix for 3D lookup tables. Each component is
  15293. coded on a @code{1/(N*N)} scale.
  15294. @item color, c
  15295. Specify the color of the source, only available in the @code{color}
  15296. source. For the syntax of this option, check the
  15297. @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15298. @item size, s
  15299. Specify the size of the sourced video. For the syntax of this option, check the
  15300. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15301. The default value is @code{320x240}.
  15302. This option is not available with the @code{allrgb}, @code{allyuv}, and
  15303. @code{haldclutsrc} filters.
  15304. @item rate, r
  15305. Specify the frame rate of the sourced video, as the number of frames
  15306. generated per second. It has to be a string in the format
  15307. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  15308. number or a valid video frame rate abbreviation. The default value is
  15309. "25".
  15310. @item duration, d
  15311. Set the duration of the sourced video. See
  15312. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  15313. for the accepted syntax.
  15314. If not specified, or the expressed duration is negative, the video is
  15315. supposed to be generated forever.
  15316. @item sar
  15317. Set the sample aspect ratio of the sourced video.
  15318. @item alpha
  15319. Specify the alpha (opacity) of the background, only available in the
  15320. @code{testsrc2} source. The value must be between 0 (fully transparent) and
  15321. 255 (fully opaque, the default).
  15322. @item decimals, n
  15323. Set the number of decimals to show in the timestamp, only available in the
  15324. @code{testsrc} source.
  15325. The displayed timestamp value will correspond to the original
  15326. timestamp value multiplied by the power of 10 of the specified
  15327. value. Default value is 0.
  15328. @end table
  15329. @subsection Examples
  15330. @itemize
  15331. @item
  15332. Generate a video with a duration of 5.3 seconds, with size
  15333. 176x144 and a frame rate of 10 frames per second:
  15334. @example
  15335. testsrc=duration=5.3:size=qcif:rate=10
  15336. @end example
  15337. @item
  15338. The following graph description will generate a red source
  15339. with an opacity of 0.2, with size "qcif" and a frame rate of 10
  15340. frames per second:
  15341. @example
  15342. color=c=red@@0.2:s=qcif:r=10
  15343. @end example
  15344. @item
  15345. If the input content is to be ignored, @code{nullsrc} can be used. The
  15346. following command generates noise in the luminance plane by employing
  15347. the @code{geq} filter:
  15348. @example
  15349. nullsrc=s=256x256, geq=random(1)*255:128:128
  15350. @end example
  15351. @end itemize
  15352. @subsection Commands
  15353. The @code{color} source supports the following commands:
  15354. @table @option
  15355. @item c, color
  15356. Set the color of the created image. Accepts the same syntax of the
  15357. corresponding @option{color} option.
  15358. @end table
  15359. @section openclsrc
  15360. Generate video using an OpenCL program.
  15361. @table @option
  15362. @item source
  15363. OpenCL program source file.
  15364. @item kernel
  15365. Kernel name in program.
  15366. @item size, s
  15367. Size of frames to generate. This must be set.
  15368. @item format
  15369. Pixel format to use for the generated frames. This must be set.
  15370. @item rate, r
  15371. Number of frames generated every second. Default value is '25'.
  15372. @end table
  15373. For details of how the program loading works, see the @ref{program_opencl}
  15374. filter.
  15375. Example programs:
  15376. @itemize
  15377. @item
  15378. Generate a colour ramp by setting pixel values from the position of the pixel
  15379. in the output image. (Note that this will work with all pixel formats, but
  15380. the generated output will not be the same.)
  15381. @verbatim
  15382. __kernel void ramp(__write_only image2d_t dst,
  15383. unsigned int index)
  15384. {
  15385. int2 loc = (int2)(get_global_id(0), get_global_id(1));
  15386. float4 val;
  15387. val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
  15388. write_imagef(dst, loc, val);
  15389. }
  15390. @end verbatim
  15391. @item
  15392. Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
  15393. @verbatim
  15394. __kernel void sierpinski_carpet(__write_only image2d_t dst,
  15395. unsigned int index)
  15396. {
  15397. int2 loc = (int2)(get_global_id(0), get_global_id(1));
  15398. float4 value = 0.0f;
  15399. int x = loc.x + index;
  15400. int y = loc.y + index;
  15401. while (x > 0 || y > 0) {
  15402. if (x % 3 == 1 && y % 3 == 1) {
  15403. value = 1.0f;
  15404. break;
  15405. }
  15406. x /= 3;
  15407. y /= 3;
  15408. }
  15409. write_imagef(dst, loc, value);
  15410. }
  15411. @end verbatim
  15412. @end itemize
  15413. @c man end VIDEO SOURCES
  15414. @chapter Video Sinks
  15415. @c man begin VIDEO SINKS
  15416. Below is a description of the currently available video sinks.
  15417. @section buffersink
  15418. Buffer video frames, and make them available to the end of the filter
  15419. graph.
  15420. This sink is mainly intended for programmatic use, in particular
  15421. through the interface defined in @file{libavfilter/buffersink.h}
  15422. or the options system.
  15423. It accepts a pointer to an AVBufferSinkContext structure, which
  15424. defines the incoming buffers' formats, to be passed as the opaque
  15425. parameter to @code{avfilter_init_filter} for initialization.
  15426. @section nullsink
  15427. Null video sink: do absolutely nothing with the input video. It is
  15428. mainly useful as a template and for use in analysis / debugging
  15429. tools.
  15430. @c man end VIDEO SINKS
  15431. @chapter Multimedia Filters
  15432. @c man begin MULTIMEDIA FILTERS
  15433. Below is a description of the currently available multimedia filters.
  15434. @section abitscope
  15435. Convert input audio to a video output, displaying the audio bit scope.
  15436. The filter accepts the following options:
  15437. @table @option
  15438. @item rate, r
  15439. Set frame rate, expressed as number of frames per second. Default
  15440. value is "25".
  15441. @item size, s
  15442. Specify the video size for the output. For the syntax of this option, check the
  15443. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15444. Default value is @code{1024x256}.
  15445. @item colors
  15446. Specify list of colors separated by space or by '|' which will be used to
  15447. draw channels. Unrecognized or missing colors will be replaced
  15448. by white color.
  15449. @end table
  15450. @section ahistogram
  15451. Convert input audio to a video output, displaying the volume histogram.
  15452. The filter accepts the following options:
  15453. @table @option
  15454. @item dmode
  15455. Specify how histogram is calculated.
  15456. It accepts the following values:
  15457. @table @samp
  15458. @item single
  15459. Use single histogram for all channels.
  15460. @item separate
  15461. Use separate histogram for each channel.
  15462. @end table
  15463. Default is @code{single}.
  15464. @item rate, r
  15465. Set frame rate, expressed as number of frames per second. Default
  15466. value is "25".
  15467. @item size, s
  15468. Specify the video size for the output. For the syntax of this option, check the
  15469. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15470. Default value is @code{hd720}.
  15471. @item scale
  15472. Set display scale.
  15473. It accepts the following values:
  15474. @table @samp
  15475. @item log
  15476. logarithmic
  15477. @item sqrt
  15478. square root
  15479. @item cbrt
  15480. cubic root
  15481. @item lin
  15482. linear
  15483. @item rlog
  15484. reverse logarithmic
  15485. @end table
  15486. Default is @code{log}.
  15487. @item ascale
  15488. Set amplitude scale.
  15489. It accepts the following values:
  15490. @table @samp
  15491. @item log
  15492. logarithmic
  15493. @item lin
  15494. linear
  15495. @end table
  15496. Default is @code{log}.
  15497. @item acount
  15498. Set how much frames to accumulate in histogram.
  15499. Default is 1. Setting this to -1 accumulates all frames.
  15500. @item rheight
  15501. Set histogram ratio of window height.
  15502. @item slide
  15503. Set sonogram sliding.
  15504. It accepts the following values:
  15505. @table @samp
  15506. @item replace
  15507. replace old rows with new ones.
  15508. @item scroll
  15509. scroll from top to bottom.
  15510. @end table
  15511. Default is @code{replace}.
  15512. @end table
  15513. @section aphasemeter
  15514. Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
  15515. representing mean phase of current audio frame. A video output can also be produced and is
  15516. enabled by default. The audio is passed through as first output.
  15517. Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
  15518. range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
  15519. and @code{1} means channels are in phase.
  15520. The filter accepts the following options, all related to its video output:
  15521. @table @option
  15522. @item rate, r
  15523. Set the output frame rate. Default value is @code{25}.
  15524. @item size, s
  15525. Set the video size for the output. For the syntax of this option, check the
  15526. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15527. Default value is @code{800x400}.
  15528. @item rc
  15529. @item gc
  15530. @item bc
  15531. Specify the red, green, blue contrast. Default values are @code{2},
  15532. @code{7} and @code{1}.
  15533. Allowed range is @code{[0, 255]}.
  15534. @item mpc
  15535. Set color which will be used for drawing median phase. If color is
  15536. @code{none} which is default, no median phase value will be drawn.
  15537. @item video
  15538. Enable video output. Default is enabled.
  15539. @end table
  15540. @section avectorscope
  15541. Convert input audio to a video output, representing the audio vector
  15542. scope.
  15543. The filter is used to measure the difference between channels of stereo
  15544. audio stream. A monoaural signal, consisting of identical left and right
  15545. signal, results in straight vertical line. Any stereo separation is visible
  15546. as a deviation from this line, creating a Lissajous figure.
  15547. If the straight (or deviation from it) but horizontal line appears this
  15548. indicates that the left and right channels are out of phase.
  15549. The filter accepts the following options:
  15550. @table @option
  15551. @item mode, m
  15552. Set the vectorscope mode.
  15553. Available values are:
  15554. @table @samp
  15555. @item lissajous
  15556. Lissajous rotated by 45 degrees.
  15557. @item lissajous_xy
  15558. Same as above but not rotated.
  15559. @item polar
  15560. Shape resembling half of circle.
  15561. @end table
  15562. Default value is @samp{lissajous}.
  15563. @item size, s
  15564. Set the video size for the output. For the syntax of this option, check the
  15565. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15566. Default value is @code{400x400}.
  15567. @item rate, r
  15568. Set the output frame rate. Default value is @code{25}.
  15569. @item rc
  15570. @item gc
  15571. @item bc
  15572. @item ac
  15573. Specify the red, green, blue and alpha contrast. Default values are @code{40},
  15574. @code{160}, @code{80} and @code{255}.
  15575. Allowed range is @code{[0, 255]}.
  15576. @item rf
  15577. @item gf
  15578. @item bf
  15579. @item af
  15580. Specify the red, green, blue and alpha fade. Default values are @code{15},
  15581. @code{10}, @code{5} and @code{5}.
  15582. Allowed range is @code{[0, 255]}.
  15583. @item zoom
  15584. Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
  15585. Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
  15586. @item draw
  15587. Set the vectorscope drawing mode.
  15588. Available values are:
  15589. @table @samp
  15590. @item dot
  15591. Draw dot for each sample.
  15592. @item line
  15593. Draw line between previous and current sample.
  15594. @end table
  15595. Default value is @samp{dot}.
  15596. @item scale
  15597. Specify amplitude scale of audio samples.
  15598. Available values are:
  15599. @table @samp
  15600. @item lin
  15601. Linear.
  15602. @item sqrt
  15603. Square root.
  15604. @item cbrt
  15605. Cubic root.
  15606. @item log
  15607. Logarithmic.
  15608. @end table
  15609. @item swap
  15610. Swap left channel axis with right channel axis.
  15611. @item mirror
  15612. Mirror axis.
  15613. @table @samp
  15614. @item none
  15615. No mirror.
  15616. @item x
  15617. Mirror only x axis.
  15618. @item y
  15619. Mirror only y axis.
  15620. @item xy
  15621. Mirror both axis.
  15622. @end table
  15623. @end table
  15624. @subsection Examples
  15625. @itemize
  15626. @item
  15627. Complete example using @command{ffplay}:
  15628. @example
  15629. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  15630. [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
  15631. @end example
  15632. @end itemize
  15633. @section bench, abench
  15634. Benchmark part of a filtergraph.
  15635. The filter accepts the following options:
  15636. @table @option
  15637. @item action
  15638. Start or stop a timer.
  15639. Available values are:
  15640. @table @samp
  15641. @item start
  15642. Get the current time, set it as frame metadata (using the key
  15643. @code{lavfi.bench.start_time}), and forward the frame to the next filter.
  15644. @item stop
  15645. Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
  15646. the input frame metadata to get the time difference. Time difference, average,
  15647. maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
  15648. @code{min}) are then printed. The timestamps are expressed in seconds.
  15649. @end table
  15650. @end table
  15651. @subsection Examples
  15652. @itemize
  15653. @item
  15654. Benchmark @ref{selectivecolor} filter:
  15655. @example
  15656. bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
  15657. @end example
  15658. @end itemize
  15659. @section concat
  15660. Concatenate audio and video streams, joining them together one after the
  15661. other.
  15662. The filter works on segments of synchronized video and audio streams. All
  15663. segments must have the same number of streams of each type, and that will
  15664. also be the number of streams at output.
  15665. The filter accepts the following options:
  15666. @table @option
  15667. @item n
  15668. Set the number of segments. Default is 2.
  15669. @item v
  15670. Set the number of output video streams, that is also the number of video
  15671. streams in each segment. Default is 1.
  15672. @item a
  15673. Set the number of output audio streams, that is also the number of audio
  15674. streams in each segment. Default is 0.
  15675. @item unsafe
  15676. Activate unsafe mode: do not fail if segments have a different format.
  15677. @end table
  15678. The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
  15679. @var{a} audio outputs.
  15680. There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
  15681. segment, in the same order as the outputs, then the inputs for the second
  15682. segment, etc.
  15683. Related streams do not always have exactly the same duration, for various
  15684. reasons including codec frame size or sloppy authoring. For that reason,
  15685. related synchronized streams (e.g. a video and its audio track) should be
  15686. concatenated at once. The concat filter will use the duration of the longest
  15687. stream in each segment (except the last one), and if necessary pad shorter
  15688. audio streams with silence.
  15689. For this filter to work correctly, all segments must start at timestamp 0.
  15690. All corresponding streams must have the same parameters in all segments; the
  15691. filtering system will automatically select a common pixel format for video
  15692. streams, and a common sample format, sample rate and channel layout for
  15693. audio streams, but other settings, such as resolution, must be converted
  15694. explicitly by the user.
  15695. Different frame rates are acceptable but will result in variable frame rate
  15696. at output; be sure to configure the output file to handle it.
  15697. @subsection Examples
  15698. @itemize
  15699. @item
  15700. Concatenate an opening, an episode and an ending, all in bilingual version
  15701. (video in stream 0, audio in streams 1 and 2):
  15702. @example
  15703. ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
  15704. '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
  15705. concat=n=3:v=1:a=2 [v] [a1] [a2]' \
  15706. -map '[v]' -map '[a1]' -map '[a2]' output.mkv
  15707. @end example
  15708. @item
  15709. Concatenate two parts, handling audio and video separately, using the
  15710. (a)movie sources, and adjusting the resolution:
  15711. @example
  15712. movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
  15713. movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
  15714. [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
  15715. @end example
  15716. Note that a desync will happen at the stitch if the audio and video streams
  15717. do not have exactly the same duration in the first file.
  15718. @end itemize
  15719. @subsection Commands
  15720. This filter supports the following commands:
  15721. @table @option
  15722. @item next
  15723. Close the current segment and step to the next one
  15724. @end table
  15725. @section drawgraph, adrawgraph
  15726. Draw a graph using input video or audio metadata.
  15727. It accepts the following parameters:
  15728. @table @option
  15729. @item m1
  15730. Set 1st frame metadata key from which metadata values will be used to draw a graph.
  15731. @item fg1
  15732. Set 1st foreground color expression.
  15733. @item m2
  15734. Set 2nd frame metadata key from which metadata values will be used to draw a graph.
  15735. @item fg2
  15736. Set 2nd foreground color expression.
  15737. @item m3
  15738. Set 3rd frame metadata key from which metadata values will be used to draw a graph.
  15739. @item fg3
  15740. Set 3rd foreground color expression.
  15741. @item m4
  15742. Set 4th frame metadata key from which metadata values will be used to draw a graph.
  15743. @item fg4
  15744. Set 4th foreground color expression.
  15745. @item min
  15746. Set minimal value of metadata value.
  15747. @item max
  15748. Set maximal value of metadata value.
  15749. @item bg
  15750. Set graph background color. Default is white.
  15751. @item mode
  15752. Set graph mode.
  15753. Available values for mode is:
  15754. @table @samp
  15755. @item bar
  15756. @item dot
  15757. @item line
  15758. @end table
  15759. Default is @code{line}.
  15760. @item slide
  15761. Set slide mode.
  15762. Available values for slide is:
  15763. @table @samp
  15764. @item frame
  15765. Draw new frame when right border is reached.
  15766. @item replace
  15767. Replace old columns with new ones.
  15768. @item scroll
  15769. Scroll from right to left.
  15770. @item rscroll
  15771. Scroll from left to right.
  15772. @item picture
  15773. Draw single picture.
  15774. @end table
  15775. Default is @code{frame}.
  15776. @item size
  15777. Set size of graph video. For the syntax of this option, check the
  15778. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15779. The default value is @code{900x256}.
  15780. The foreground color expressions can use the following variables:
  15781. @table @option
  15782. @item MIN
  15783. Minimal value of metadata value.
  15784. @item MAX
  15785. Maximal value of metadata value.
  15786. @item VAL
  15787. Current metadata key value.
  15788. @end table
  15789. The color is defined as 0xAABBGGRR.
  15790. @end table
  15791. Example using metadata from @ref{signalstats} filter:
  15792. @example
  15793. signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
  15794. @end example
  15795. Example using metadata from @ref{ebur128} filter:
  15796. @example
  15797. ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
  15798. @end example
  15799. @anchor{ebur128}
  15800. @section ebur128
  15801. EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
  15802. level. By default, it logs a message at a frequency of 10Hz with the
  15803. Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
  15804. Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
  15805. The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
  15806. sample format is double-precision floating point. The input stream will be converted to
  15807. this specification, if needed. Users may need to insert aformat and/or aresample filters
  15808. after this filter to obtain the original parameters.
  15809. The filter also has a video output (see the @var{video} option) with a real
  15810. time graph to observe the loudness evolution. The graphic contains the logged
  15811. message mentioned above, so it is not printed anymore when this option is set,
  15812. unless the verbose logging is set. The main graphing area contains the
  15813. short-term loudness (3 seconds of analysis), and the gauge on the right is for
  15814. the momentary loudness (400 milliseconds), but can optionally be configured
  15815. to instead display short-term loudness (see @var{gauge}).
  15816. The green area marks a +/- 1LU target range around the target loudness
  15817. (-23LUFS by default, unless modified through @var{target}).
  15818. More information about the Loudness Recommendation EBU R128 on
  15819. @url{http://tech.ebu.ch/loudness}.
  15820. The filter accepts the following options:
  15821. @table @option
  15822. @item video
  15823. Activate the video output. The audio stream is passed unchanged whether this
  15824. option is set or no. The video stream will be the first output stream if
  15825. activated. Default is @code{0}.
  15826. @item size
  15827. Set the video size. This option is for video only. For the syntax of this
  15828. option, check the
  15829. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  15830. Default and minimum resolution is @code{640x480}.
  15831. @item meter
  15832. Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
  15833. @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
  15834. other integer value between this range is allowed.
  15835. @item metadata
  15836. Set metadata injection. If set to @code{1}, the audio input will be segmented
  15837. into 100ms output frames, each of them containing various loudness information
  15838. in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
  15839. Default is @code{0}.
  15840. @item framelog
  15841. Force the frame logging level.
  15842. Available values are:
  15843. @table @samp
  15844. @item info
  15845. information logging level
  15846. @item verbose
  15847. verbose logging level
  15848. @end table
  15849. By default, the logging level is set to @var{info}. If the @option{video} or
  15850. the @option{metadata} options are set, it switches to @var{verbose}.
  15851. @item peak
  15852. Set peak mode(s).
  15853. Available modes can be cumulated (the option is a @code{flag} type). Possible
  15854. values are:
  15855. @table @samp
  15856. @item none
  15857. Disable any peak mode (default).
  15858. @item sample
  15859. Enable sample-peak mode.
  15860. Simple peak mode looking for the higher sample value. It logs a message
  15861. for sample-peak (identified by @code{SPK}).
  15862. @item true
  15863. Enable true-peak mode.
  15864. If enabled, the peak lookup is done on an over-sampled version of the input
  15865. stream for better peak accuracy. It logs a message for true-peak.
  15866. (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
  15867. This mode requires a build with @code{libswresample}.
  15868. @end table
  15869. @item dualmono
  15870. Treat mono input files as "dual mono". If a mono file is intended for playback
  15871. on a stereo system, its EBU R128 measurement will be perceptually incorrect.
  15872. If set to @code{true}, this option will compensate for this effect.
  15873. Multi-channel input files are not affected by this option.
  15874. @item panlaw
  15875. Set a specific pan law to be used for the measurement of dual mono files.
  15876. This parameter is optional, and has a default value of -3.01dB.
  15877. @item target
  15878. Set a specific target level (in LUFS) used as relative zero in the visualization.
  15879. This parameter is optional and has a default value of -23LUFS as specified
  15880. by EBU R128. However, material published online may prefer a level of -16LUFS
  15881. (e.g. for use with podcasts or video platforms).
  15882. @item gauge
  15883. Set the value displayed by the gauge. Valid values are @code{momentary} and s
  15884. @code{shortterm}. By default the momentary value will be used, but in certain
  15885. scenarios it may be more useful to observe the short term value instead (e.g.
  15886. live mixing).
  15887. @item scale
  15888. Sets the display scale for the loudness. Valid parameters are @code{absolute}
  15889. (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
  15890. video output, not the summary or continuous log output.
  15891. @end table
  15892. @subsection Examples
  15893. @itemize
  15894. @item
  15895. Real-time graph using @command{ffplay}, with a EBU scale meter +18:
  15896. @example
  15897. ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
  15898. @end example
  15899. @item
  15900. Run an analysis with @command{ffmpeg}:
  15901. @example
  15902. ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
  15903. @end example
  15904. @end itemize
  15905. @section interleave, ainterleave
  15906. Temporally interleave frames from several inputs.
  15907. @code{interleave} works with video inputs, @code{ainterleave} with audio.
  15908. These filters read frames from several inputs and send the oldest
  15909. queued frame to the output.
  15910. Input streams must have well defined, monotonically increasing frame
  15911. timestamp values.
  15912. In order to submit one frame to output, these filters need to enqueue
  15913. at least one frame for each input, so they cannot work in case one
  15914. input is not yet terminated and will not receive incoming frames.
  15915. For example consider the case when one input is a @code{select} filter
  15916. which always drops input frames. The @code{interleave} filter will keep
  15917. reading from that input, but it will never be able to send new frames
  15918. to output until the input sends an end-of-stream signal.
  15919. Also, depending on inputs synchronization, the filters will drop
  15920. frames in case one input receives more frames than the other ones, and
  15921. the queue is already filled.
  15922. These filters accept the following options:
  15923. @table @option
  15924. @item nb_inputs, n
  15925. Set the number of different inputs, it is 2 by default.
  15926. @end table
  15927. @subsection Examples
  15928. @itemize
  15929. @item
  15930. Interleave frames belonging to different streams using @command{ffmpeg}:
  15931. @example
  15932. ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
  15933. @end example
  15934. @item
  15935. Add flickering blur effect:
  15936. @example
  15937. select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
  15938. @end example
  15939. @end itemize
  15940. @section metadata, ametadata
  15941. Manipulate frame metadata.
  15942. This filter accepts the following options:
  15943. @table @option
  15944. @item mode
  15945. Set mode of operation of the filter.
  15946. Can be one of the following:
  15947. @table @samp
  15948. @item select
  15949. If both @code{value} and @code{key} is set, select frames
  15950. which have such metadata. If only @code{key} is set, select
  15951. every frame that has such key in metadata.
  15952. @item add
  15953. Add new metadata @code{key} and @code{value}. If key is already available
  15954. do nothing.
  15955. @item modify
  15956. Modify value of already present key.
  15957. @item delete
  15958. If @code{value} is set, delete only keys that have such value.
  15959. Otherwise, delete key. If @code{key} is not set, delete all metadata values in
  15960. the frame.
  15961. @item print
  15962. Print key and its value if metadata was found. If @code{key} is not set print all
  15963. metadata values available in frame.
  15964. @end table
  15965. @item key
  15966. Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
  15967. @item value
  15968. Set metadata value which will be used. This option is mandatory for
  15969. @code{modify} and @code{add} mode.
  15970. @item function
  15971. Which function to use when comparing metadata value and @code{value}.
  15972. Can be one of following:
  15973. @table @samp
  15974. @item same_str
  15975. Values are interpreted as strings, returns true if metadata value is same as @code{value}.
  15976. @item starts_with
  15977. Values are interpreted as strings, returns true if metadata value starts with
  15978. the @code{value} option string.
  15979. @item less
  15980. Values are interpreted as floats, returns true if metadata value is less than @code{value}.
  15981. @item equal
  15982. Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
  15983. @item greater
  15984. Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
  15985. @item expr
  15986. Values are interpreted as floats, returns true if expression from option @code{expr}
  15987. evaluates to true.
  15988. @end table
  15989. @item expr
  15990. Set expression which is used when @code{function} is set to @code{expr}.
  15991. The expression is evaluated through the eval API and can contain the following
  15992. constants:
  15993. @table @option
  15994. @item VALUE1
  15995. Float representation of @code{value} from metadata key.
  15996. @item VALUE2
  15997. Float representation of @code{value} as supplied by user in @code{value} option.
  15998. @end table
  15999. @item file
  16000. If specified in @code{print} mode, output is written to the named file. Instead of
  16001. plain filename any writable url can be specified. Filename ``-'' is a shorthand
  16002. for standard output. If @code{file} option is not set, output is written to the log
  16003. with AV_LOG_INFO loglevel.
  16004. @end table
  16005. @subsection Examples
  16006. @itemize
  16007. @item
  16008. Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
  16009. between 0 and 1.
  16010. @example
  16011. signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
  16012. @end example
  16013. @item
  16014. Print silencedetect output to file @file{metadata.txt}.
  16015. @example
  16016. silencedetect,ametadata=mode=print:file=metadata.txt
  16017. @end example
  16018. @item
  16019. Direct all metadata to a pipe with file descriptor 4.
  16020. @example
  16021. metadata=mode=print:file='pipe\:4'
  16022. @end example
  16023. @end itemize
  16024. @section perms, aperms
  16025. Set read/write permissions for the output frames.
  16026. These filters are mainly aimed at developers to test direct path in the
  16027. following filter in the filtergraph.
  16028. The filters accept the following options:
  16029. @table @option
  16030. @item mode
  16031. Select the permissions mode.
  16032. It accepts the following values:
  16033. @table @samp
  16034. @item none
  16035. Do nothing. This is the default.
  16036. @item ro
  16037. Set all the output frames read-only.
  16038. @item rw
  16039. Set all the output frames directly writable.
  16040. @item toggle
  16041. Make the frame read-only if writable, and writable if read-only.
  16042. @item random
  16043. Set each output frame read-only or writable randomly.
  16044. @end table
  16045. @item seed
  16046. Set the seed for the @var{random} mode, must be an integer included between
  16047. @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
  16048. @code{-1}, the filter will try to use a good random seed on a best effort
  16049. basis.
  16050. @end table
  16051. Note: in case of auto-inserted filter between the permission filter and the
  16052. following one, the permission might not be received as expected in that
  16053. following filter. Inserting a @ref{format} or @ref{aformat} filter before the
  16054. perms/aperms filter can avoid this problem.
  16055. @section realtime, arealtime
  16056. Slow down filtering to match real time approximately.
  16057. These filters will pause the filtering for a variable amount of time to
  16058. match the output rate with the input timestamps.
  16059. They are similar to the @option{re} option to @code{ffmpeg}.
  16060. They accept the following options:
  16061. @table @option
  16062. @item limit
  16063. Time limit for the pauses. Any pause longer than that will be considered
  16064. a timestamp discontinuity and reset the timer. Default is 2 seconds.
  16065. @end table
  16066. @anchor{select}
  16067. @section select, aselect
  16068. Select frames to pass in output.
  16069. This filter accepts the following options:
  16070. @table @option
  16071. @item expr, e
  16072. Set expression, which is evaluated for each input frame.
  16073. If the expression is evaluated to zero, the frame is discarded.
  16074. If the evaluation result is negative or NaN, the frame is sent to the
  16075. first output; otherwise it is sent to the output with index
  16076. @code{ceil(val)-1}, assuming that the input index starts from 0.
  16077. For example a value of @code{1.2} corresponds to the output with index
  16078. @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
  16079. @item outputs, n
  16080. Set the number of outputs. The output to which to send the selected
  16081. frame is based on the result of the evaluation. Default value is 1.
  16082. @end table
  16083. The expression can contain the following constants:
  16084. @table @option
  16085. @item n
  16086. The (sequential) number of the filtered frame, starting from 0.
  16087. @item selected_n
  16088. The (sequential) number of the selected frame, starting from 0.
  16089. @item prev_selected_n
  16090. The sequential number of the last selected frame. It's NAN if undefined.
  16091. @item TB
  16092. The timebase of the input timestamps.
  16093. @item pts
  16094. The PTS (Presentation TimeStamp) of the filtered video frame,
  16095. expressed in @var{TB} units. It's NAN if undefined.
  16096. @item t
  16097. The PTS of the filtered video frame,
  16098. expressed in seconds. It's NAN if undefined.
  16099. @item prev_pts
  16100. The PTS of the previously filtered video frame. It's NAN if undefined.
  16101. @item prev_selected_pts
  16102. The PTS of the last previously filtered video frame. It's NAN if undefined.
  16103. @item prev_selected_t
  16104. The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
  16105. @item start_pts
  16106. The PTS of the first video frame in the video. It's NAN if undefined.
  16107. @item start_t
  16108. The time of the first video frame in the video. It's NAN if undefined.
  16109. @item pict_type @emph{(video only)}
  16110. The type of the filtered frame. It can assume one of the following
  16111. values:
  16112. @table @option
  16113. @item I
  16114. @item P
  16115. @item B
  16116. @item S
  16117. @item SI
  16118. @item SP
  16119. @item BI
  16120. @end table
  16121. @item interlace_type @emph{(video only)}
  16122. The frame interlace type. It can assume one of the following values:
  16123. @table @option
  16124. @item PROGRESSIVE
  16125. The frame is progressive (not interlaced).
  16126. @item TOPFIRST
  16127. The frame is top-field-first.
  16128. @item BOTTOMFIRST
  16129. The frame is bottom-field-first.
  16130. @end table
  16131. @item consumed_sample_n @emph{(audio only)}
  16132. the number of selected samples before the current frame
  16133. @item samples_n @emph{(audio only)}
  16134. the number of samples in the current frame
  16135. @item sample_rate @emph{(audio only)}
  16136. the input sample rate
  16137. @item key
  16138. This is 1 if the filtered frame is a key-frame, 0 otherwise.
  16139. @item pos
  16140. the position in the file of the filtered frame, -1 if the information
  16141. is not available (e.g. for synthetic video)
  16142. @item scene @emph{(video only)}
  16143. value between 0 and 1 to indicate a new scene; a low value reflects a low
  16144. probability for the current frame to introduce a new scene, while a higher
  16145. value means the current frame is more likely to be one (see the example below)
  16146. @item concatdec_select
  16147. The concat demuxer can select only part of a concat input file by setting an
  16148. inpoint and an outpoint, but the output packets may not be entirely contained
  16149. in the selected interval. By using this variable, it is possible to skip frames
  16150. generated by the concat demuxer which are not exactly contained in the selected
  16151. interval.
  16152. This works by comparing the frame pts against the @var{lavf.concat.start_time}
  16153. and the @var{lavf.concat.duration} packet metadata values which are also
  16154. present in the decoded frames.
  16155. The @var{concatdec_select} variable is -1 if the frame pts is at least
  16156. start_time and either the duration metadata is missing or the frame pts is less
  16157. than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
  16158. missing.
  16159. That basically means that an input frame is selected if its pts is within the
  16160. interval set by the concat demuxer.
  16161. @end table
  16162. The default value of the select expression is "1".
  16163. @subsection Examples
  16164. @itemize
  16165. @item
  16166. Select all frames in input:
  16167. @example
  16168. select
  16169. @end example
  16170. The example above is the same as:
  16171. @example
  16172. select=1
  16173. @end example
  16174. @item
  16175. Skip all frames:
  16176. @example
  16177. select=0
  16178. @end example
  16179. @item
  16180. Select only I-frames:
  16181. @example
  16182. select='eq(pict_type\,I)'
  16183. @end example
  16184. @item
  16185. Select one frame every 100:
  16186. @example
  16187. select='not(mod(n\,100))'
  16188. @end example
  16189. @item
  16190. Select only frames contained in the 10-20 time interval:
  16191. @example
  16192. select=between(t\,10\,20)
  16193. @end example
  16194. @item
  16195. Select only I-frames contained in the 10-20 time interval:
  16196. @example
  16197. select=between(t\,10\,20)*eq(pict_type\,I)
  16198. @end example
  16199. @item
  16200. Select frames with a minimum distance of 10 seconds:
  16201. @example
  16202. select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
  16203. @end example
  16204. @item
  16205. Use aselect to select only audio frames with samples number > 100:
  16206. @example
  16207. aselect='gt(samples_n\,100)'
  16208. @end example
  16209. @item
  16210. Create a mosaic of the first scenes:
  16211. @example
  16212. ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
  16213. @end example
  16214. Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
  16215. choice.
  16216. @item
  16217. Send even and odd frames to separate outputs, and compose them:
  16218. @example
  16219. select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
  16220. @end example
  16221. @item
  16222. Select useful frames from an ffconcat file which is using inpoints and
  16223. outpoints but where the source files are not intra frame only.
  16224. @example
  16225. ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
  16226. @end example
  16227. @end itemize
  16228. @section sendcmd, asendcmd
  16229. Send commands to filters in the filtergraph.
  16230. These filters read commands to be sent to other filters in the
  16231. filtergraph.
  16232. @code{sendcmd} must be inserted between two video filters,
  16233. @code{asendcmd} must be inserted between two audio filters, but apart
  16234. from that they act the same way.
  16235. The specification of commands can be provided in the filter arguments
  16236. with the @var{commands} option, or in a file specified by the
  16237. @var{filename} option.
  16238. These filters accept the following options:
  16239. @table @option
  16240. @item commands, c
  16241. Set the commands to be read and sent to the other filters.
  16242. @item filename, f
  16243. Set the filename of the commands to be read and sent to the other
  16244. filters.
  16245. @end table
  16246. @subsection Commands syntax
  16247. A commands description consists of a sequence of interval
  16248. specifications, comprising a list of commands to be executed when a
  16249. particular event related to that interval occurs. The occurring event
  16250. is typically the current frame time entering or leaving a given time
  16251. interval.
  16252. An interval is specified by the following syntax:
  16253. @example
  16254. @var{START}[-@var{END}] @var{COMMANDS};
  16255. @end example
  16256. The time interval is specified by the @var{START} and @var{END} times.
  16257. @var{END} is optional and defaults to the maximum time.
  16258. The current frame time is considered within the specified interval if
  16259. it is included in the interval [@var{START}, @var{END}), that is when
  16260. the time is greater or equal to @var{START} and is lesser than
  16261. @var{END}.
  16262. @var{COMMANDS} consists of a sequence of one or more command
  16263. specifications, separated by ",", relating to that interval. The
  16264. syntax of a command specification is given by:
  16265. @example
  16266. [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
  16267. @end example
  16268. @var{FLAGS} is optional and specifies the type of events relating to
  16269. the time interval which enable sending the specified command, and must
  16270. be a non-null sequence of identifier flags separated by "+" or "|" and
  16271. enclosed between "[" and "]".
  16272. The following flags are recognized:
  16273. @table @option
  16274. @item enter
  16275. The command is sent when the current frame timestamp enters the
  16276. specified interval. In other words, the command is sent when the
  16277. previous frame timestamp was not in the given interval, and the
  16278. current is.
  16279. @item leave
  16280. The command is sent when the current frame timestamp leaves the
  16281. specified interval. In other words, the command is sent when the
  16282. previous frame timestamp was in the given interval, and the
  16283. current is not.
  16284. @end table
  16285. If @var{FLAGS} is not specified, a default value of @code{[enter]} is
  16286. assumed.
  16287. @var{TARGET} specifies the target of the command, usually the name of
  16288. the filter class or a specific filter instance name.
  16289. @var{COMMAND} specifies the name of the command for the target filter.
  16290. @var{ARG} is optional and specifies the optional list of argument for
  16291. the given @var{COMMAND}.
  16292. Between one interval specification and another, whitespaces, or
  16293. sequences of characters starting with @code{#} until the end of line,
  16294. are ignored and can be used to annotate comments.
  16295. A simplified BNF description of the commands specification syntax
  16296. follows:
  16297. @example
  16298. @var{COMMAND_FLAG} ::= "enter" | "leave"
  16299. @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
  16300. @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
  16301. @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
  16302. @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
  16303. @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
  16304. @end example
  16305. @subsection Examples
  16306. @itemize
  16307. @item
  16308. Specify audio tempo change at second 4:
  16309. @example
  16310. asendcmd=c='4.0 atempo tempo 1.5',atempo
  16311. @end example
  16312. @item
  16313. Target a specific filter instance:
  16314. @example
  16315. asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
  16316. @end example
  16317. @item
  16318. Specify a list of drawtext and hue commands in a file.
  16319. @example
  16320. # show text in the interval 5-10
  16321. 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
  16322. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
  16323. # desaturate the image in the interval 15-20
  16324. 15.0-20.0 [enter] hue s 0,
  16325. [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
  16326. [leave] hue s 1,
  16327. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
  16328. # apply an exponential saturation fade-out effect, starting from time 25
  16329. 25 [enter] hue s exp(25-t)
  16330. @end example
  16331. A filtergraph allowing to read and process the above command list
  16332. stored in a file @file{test.cmd}, can be specified with:
  16333. @example
  16334. sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
  16335. @end example
  16336. @end itemize
  16337. @anchor{setpts}
  16338. @section setpts, asetpts
  16339. Change the PTS (presentation timestamp) of the input frames.
  16340. @code{setpts} works on video frames, @code{asetpts} on audio frames.
  16341. This filter accepts the following options:
  16342. @table @option
  16343. @item expr
  16344. The expression which is evaluated for each frame to construct its timestamp.
  16345. @end table
  16346. The expression is evaluated through the eval API and can contain the following
  16347. constants:
  16348. @table @option
  16349. @item FRAME_RATE, FR
  16350. frame rate, only defined for constant frame-rate video
  16351. @item PTS
  16352. The presentation timestamp in input
  16353. @item N
  16354. The count of the input frame for video or the number of consumed samples,
  16355. not including the current frame for audio, starting from 0.
  16356. @item NB_CONSUMED_SAMPLES
  16357. The number of consumed samples, not including the current frame (only
  16358. audio)
  16359. @item NB_SAMPLES, S
  16360. The number of samples in the current frame (only audio)
  16361. @item SAMPLE_RATE, SR
  16362. The audio sample rate.
  16363. @item STARTPTS
  16364. The PTS of the first frame.
  16365. @item STARTT
  16366. the time in seconds of the first frame
  16367. @item INTERLACED
  16368. State whether the current frame is interlaced.
  16369. @item T
  16370. the time in seconds of the current frame
  16371. @item POS
  16372. original position in the file of the frame, or undefined if undefined
  16373. for the current frame
  16374. @item PREV_INPTS
  16375. The previous input PTS.
  16376. @item PREV_INT
  16377. previous input time in seconds
  16378. @item PREV_OUTPTS
  16379. The previous output PTS.
  16380. @item PREV_OUTT
  16381. previous output time in seconds
  16382. @item RTCTIME
  16383. The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
  16384. instead.
  16385. @item RTCSTART
  16386. The wallclock (RTC) time at the start of the movie in microseconds.
  16387. @item TB
  16388. The timebase of the input timestamps.
  16389. @end table
  16390. @subsection Examples
  16391. @itemize
  16392. @item
  16393. Start counting PTS from zero
  16394. @example
  16395. setpts=PTS-STARTPTS
  16396. @end example
  16397. @item
  16398. Apply fast motion effect:
  16399. @example
  16400. setpts=0.5*PTS
  16401. @end example
  16402. @item
  16403. Apply slow motion effect:
  16404. @example
  16405. setpts=2.0*PTS
  16406. @end example
  16407. @item
  16408. Set fixed rate of 25 frames per second:
  16409. @example
  16410. setpts=N/(25*TB)
  16411. @end example
  16412. @item
  16413. Set fixed rate 25 fps with some jitter:
  16414. @example
  16415. setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
  16416. @end example
  16417. @item
  16418. Apply an offset of 10 seconds to the input PTS:
  16419. @example
  16420. setpts=PTS+10/TB
  16421. @end example
  16422. @item
  16423. Generate timestamps from a "live source" and rebase onto the current timebase:
  16424. @example
  16425. setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
  16426. @end example
  16427. @item
  16428. Generate timestamps by counting samples:
  16429. @example
  16430. asetpts=N/SR/TB
  16431. @end example
  16432. @end itemize
  16433. @section setrange
  16434. Force color range for the output video frame.
  16435. The @code{setrange} filter marks the color range property for the
  16436. output frames. It does not change the input frame, but only sets the
  16437. corresponding property, which affects how the frame is treated by
  16438. following filters.
  16439. The filter accepts the following options:
  16440. @table @option
  16441. @item range
  16442. Available values are:
  16443. @table @samp
  16444. @item auto
  16445. Keep the same color range property.
  16446. @item unspecified, unknown
  16447. Set the color range as unspecified.
  16448. @item limited, tv, mpeg
  16449. Set the color range as limited.
  16450. @item full, pc, jpeg
  16451. Set the color range as full.
  16452. @end table
  16453. @end table
  16454. @section settb, asettb
  16455. Set the timebase to use for the output frames timestamps.
  16456. It is mainly useful for testing timebase configuration.
  16457. It accepts the following parameters:
  16458. @table @option
  16459. @item expr, tb
  16460. The expression which is evaluated into the output timebase.
  16461. @end table
  16462. The value for @option{tb} is an arithmetic expression representing a
  16463. rational. The expression can contain the constants "AVTB" (the default
  16464. timebase), "intb" (the input timebase) and "sr" (the sample rate,
  16465. audio only). Default value is "intb".
  16466. @subsection Examples
  16467. @itemize
  16468. @item
  16469. Set the timebase to 1/25:
  16470. @example
  16471. settb=expr=1/25
  16472. @end example
  16473. @item
  16474. Set the timebase to 1/10:
  16475. @example
  16476. settb=expr=0.1
  16477. @end example
  16478. @item
  16479. Set the timebase to 1001/1000:
  16480. @example
  16481. settb=1+0.001
  16482. @end example
  16483. @item
  16484. Set the timebase to 2*intb:
  16485. @example
  16486. settb=2*intb
  16487. @end example
  16488. @item
  16489. Set the default timebase value:
  16490. @example
  16491. settb=AVTB
  16492. @end example
  16493. @end itemize
  16494. @section showcqt
  16495. Convert input audio to a video output representing frequency spectrum
  16496. logarithmically using Brown-Puckette constant Q transform algorithm with
  16497. direct frequency domain coefficient calculation (but the transform itself
  16498. is not really constant Q, instead the Q factor is actually variable/clamped),
  16499. with musical tone scale, from E0 to D#10.
  16500. The filter accepts the following options:
  16501. @table @option
  16502. @item size, s
  16503. Specify the video size for the output. It must be even. For the syntax of this option,
  16504. check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  16505. Default value is @code{1920x1080}.
  16506. @item fps, rate, r
  16507. Set the output frame rate. Default value is @code{25}.
  16508. @item bar_h
  16509. Set the bargraph height. It must be even. Default value is @code{-1} which
  16510. computes the bargraph height automatically.
  16511. @item axis_h
  16512. Set the axis height. It must be even. Default value is @code{-1} which computes
  16513. the axis height automatically.
  16514. @item sono_h
  16515. Set the sonogram height. It must be even. Default value is @code{-1} which
  16516. computes the sonogram height automatically.
  16517. @item fullhd
  16518. Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
  16519. instead. Default value is @code{1}.
  16520. @item sono_v, volume
  16521. Specify the sonogram volume expression. It can contain variables:
  16522. @table @option
  16523. @item bar_v
  16524. the @var{bar_v} evaluated expression
  16525. @item frequency, freq, f
  16526. the frequency where it is evaluated
  16527. @item timeclamp, tc
  16528. the value of @var{timeclamp} option
  16529. @end table
  16530. and functions:
  16531. @table @option
  16532. @item a_weighting(f)
  16533. A-weighting of equal loudness
  16534. @item b_weighting(f)
  16535. B-weighting of equal loudness
  16536. @item c_weighting(f)
  16537. C-weighting of equal loudness.
  16538. @end table
  16539. Default value is @code{16}.
  16540. @item bar_v, volume2
  16541. Specify the bargraph volume expression. It can contain variables:
  16542. @table @option
  16543. @item sono_v
  16544. the @var{sono_v} evaluated expression
  16545. @item frequency, freq, f
  16546. the frequency where it is evaluated
  16547. @item timeclamp, tc
  16548. the value of @var{timeclamp} option
  16549. @end table
  16550. and functions:
  16551. @table @option
  16552. @item a_weighting(f)
  16553. A-weighting of equal loudness
  16554. @item b_weighting(f)
  16555. B-weighting of equal loudness
  16556. @item c_weighting(f)
  16557. C-weighting of equal loudness.
  16558. @end table
  16559. Default value is @code{sono_v}.
  16560. @item sono_g, gamma
  16561. Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
  16562. higher gamma makes the spectrum having more range. Default value is @code{3}.
  16563. Acceptable range is @code{[1, 7]}.
  16564. @item bar_g, gamma2
  16565. Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
  16566. @code{[1, 7]}.
  16567. @item bar_t
  16568. Specify the bargraph transparency level. Lower value makes the bargraph sharper.
  16569. Default value is @code{1}. Acceptable range is @code{[0, 1]}.
  16570. @item timeclamp, tc
  16571. Specify the transform timeclamp. At low frequency, there is trade-off between
  16572. accuracy in time domain and frequency domain. If timeclamp is lower,
  16573. event in time domain is represented more accurately (such as fast bass drum),
  16574. otherwise event in frequency domain is represented more accurately
  16575. (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
  16576. @item attack
  16577. Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
  16578. limits future samples by applying asymmetric windowing in time domain, useful
  16579. when low latency is required. Accepted range is @code{[0, 1]}.
  16580. @item basefreq
  16581. Specify the transform base frequency. Default value is @code{20.01523126408007475},
  16582. which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
  16583. @item endfreq
  16584. Specify the transform end frequency. Default value is @code{20495.59681441799654},
  16585. which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
  16586. @item coeffclamp
  16587. This option is deprecated and ignored.
  16588. @item tlength
  16589. Specify the transform length in time domain. Use this option to control accuracy
  16590. trade-off between time domain and frequency domain at every frequency sample.
  16591. It can contain variables:
  16592. @table @option
  16593. @item frequency, freq, f
  16594. the frequency where it is evaluated
  16595. @item timeclamp, tc
  16596. the value of @var{timeclamp} option.
  16597. @end table
  16598. Default value is @code{384*tc/(384+tc*f)}.
  16599. @item count
  16600. Specify the transform count for every video frame. Default value is @code{6}.
  16601. Acceptable range is @code{[1, 30]}.
  16602. @item fcount
  16603. Specify the transform count for every single pixel. Default value is @code{0},
  16604. which makes it computed automatically. Acceptable range is @code{[0, 10]}.
  16605. @item fontfile
  16606. Specify font file for use with freetype to draw the axis. If not specified,
  16607. use embedded font. Note that drawing with font file or embedded font is not
  16608. implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
  16609. option instead.
  16610. @item font
  16611. Specify fontconfig pattern. This has lower priority than @var{fontfile}.
  16612. The : in the pattern may be replaced by | to avoid unnecessary escaping.
  16613. @item fontcolor
  16614. Specify font color expression. This is arithmetic expression that should return
  16615. integer value 0xRRGGBB. It can contain variables:
  16616. @table @option
  16617. @item frequency, freq, f
  16618. the frequency where it is evaluated
  16619. @item timeclamp, tc
  16620. the value of @var{timeclamp} option
  16621. @end table
  16622. and functions:
  16623. @table @option
  16624. @item midi(f)
  16625. midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
  16626. @item r(x), g(x), b(x)
  16627. red, green, and blue value of intensity x.
  16628. @end table
  16629. Default value is @code{st(0, (midi(f)-59.5)/12);
  16630. st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
  16631. r(1-ld(1)) + b(ld(1))}.
  16632. @item axisfile
  16633. Specify image file to draw the axis. This option override @var{fontfile} and
  16634. @var{fontcolor} option.
  16635. @item axis, text
  16636. Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
  16637. the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
  16638. Default value is @code{1}.
  16639. @item csp
  16640. Set colorspace. The accepted values are:
  16641. @table @samp
  16642. @item unspecified
  16643. Unspecified (default)
  16644. @item bt709
  16645. BT.709
  16646. @item fcc
  16647. FCC
  16648. @item bt470bg
  16649. BT.470BG or BT.601-6 625
  16650. @item smpte170m
  16651. SMPTE-170M or BT.601-6 525
  16652. @item smpte240m
  16653. SMPTE-240M
  16654. @item bt2020ncl
  16655. BT.2020 with non-constant luminance
  16656. @end table
  16657. @item cscheme
  16658. Set spectrogram color scheme. This is list of floating point values with format
  16659. @code{left_r|left_g|left_b|right_r|right_g|right_b}.
  16660. The default is @code{1|0.5|0|0|0.5|1}.
  16661. @end table
  16662. @subsection Examples
  16663. @itemize
  16664. @item
  16665. Playing audio while showing the spectrum:
  16666. @example
  16667. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
  16668. @end example
  16669. @item
  16670. Same as above, but with frame rate 30 fps:
  16671. @example
  16672. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
  16673. @end example
  16674. @item
  16675. Playing at 1280x720:
  16676. @example
  16677. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
  16678. @end example
  16679. @item
  16680. Disable sonogram display:
  16681. @example
  16682. sono_h=0
  16683. @end example
  16684. @item
  16685. A1 and its harmonics: A1, A2, (near)E3, A3:
  16686. @example
  16687. 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),
  16688. asplit[a][out1]; [a] showcqt [out0]'
  16689. @end example
  16690. @item
  16691. Same as above, but with more accuracy in frequency domain:
  16692. @example
  16693. 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),
  16694. asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
  16695. @end example
  16696. @item
  16697. Custom volume:
  16698. @example
  16699. bar_v=10:sono_v=bar_v*a_weighting(f)
  16700. @end example
  16701. @item
  16702. Custom gamma, now spectrum is linear to the amplitude.
  16703. @example
  16704. bar_g=2:sono_g=2
  16705. @end example
  16706. @item
  16707. Custom tlength equation:
  16708. @example
  16709. 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)))'
  16710. @end example
  16711. @item
  16712. Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
  16713. @example
  16714. fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
  16715. @end example
  16716. @item
  16717. Custom font using fontconfig:
  16718. @example
  16719. font='Courier New,Monospace,mono|bold'
  16720. @end example
  16721. @item
  16722. Custom frequency range with custom axis using image file:
  16723. @example
  16724. axisfile=myaxis.png:basefreq=40:endfreq=10000
  16725. @end example
  16726. @end itemize
  16727. @section showfreqs
  16728. Convert input audio to video output representing the audio power spectrum.
  16729. Audio amplitude is on Y-axis while frequency is on X-axis.
  16730. The filter accepts the following options:
  16731. @table @option
  16732. @item size, s
  16733. Specify size of video. For the syntax of this option, check the
  16734. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  16735. Default is @code{1024x512}.
  16736. @item mode
  16737. Set display mode.
  16738. This set how each frequency bin will be represented.
  16739. It accepts the following values:
  16740. @table @samp
  16741. @item line
  16742. @item bar
  16743. @item dot
  16744. @end table
  16745. Default is @code{bar}.
  16746. @item ascale
  16747. Set amplitude scale.
  16748. It accepts the following values:
  16749. @table @samp
  16750. @item lin
  16751. Linear scale.
  16752. @item sqrt
  16753. Square root scale.
  16754. @item cbrt
  16755. Cubic root scale.
  16756. @item log
  16757. Logarithmic scale.
  16758. @end table
  16759. Default is @code{log}.
  16760. @item fscale
  16761. Set frequency scale.
  16762. It accepts the following values:
  16763. @table @samp
  16764. @item lin
  16765. Linear scale.
  16766. @item log
  16767. Logarithmic scale.
  16768. @item rlog
  16769. Reverse logarithmic scale.
  16770. @end table
  16771. Default is @code{lin}.
  16772. @item win_size
  16773. Set window size.
  16774. It accepts the following values:
  16775. @table @samp
  16776. @item w16
  16777. @item w32
  16778. @item w64
  16779. @item w128
  16780. @item w256
  16781. @item w512
  16782. @item w1024
  16783. @item w2048
  16784. @item w4096
  16785. @item w8192
  16786. @item w16384
  16787. @item w32768
  16788. @item w65536
  16789. @end table
  16790. Default is @code{w2048}
  16791. @item win_func
  16792. Set windowing function.
  16793. It accepts the following values:
  16794. @table @samp
  16795. @item rect
  16796. @item bartlett
  16797. @item hanning
  16798. @item hamming
  16799. @item blackman
  16800. @item welch
  16801. @item flattop
  16802. @item bharris
  16803. @item bnuttall
  16804. @item bhann
  16805. @item sine
  16806. @item nuttall
  16807. @item lanczos
  16808. @item gauss
  16809. @item tukey
  16810. @item dolph
  16811. @item cauchy
  16812. @item parzen
  16813. @item poisson
  16814. @item bohman
  16815. @end table
  16816. Default is @code{hanning}.
  16817. @item overlap
  16818. Set window overlap. In range @code{[0, 1]}. Default is @code{1},
  16819. which means optimal overlap for selected window function will be picked.
  16820. @item averaging
  16821. Set time averaging. Setting this to 0 will display current maximal peaks.
  16822. Default is @code{1}, which means time averaging is disabled.
  16823. @item colors
  16824. Specify list of colors separated by space or by '|' which will be used to
  16825. draw channel frequencies. Unrecognized or missing colors will be replaced
  16826. by white color.
  16827. @item cmode
  16828. Set channel display mode.
  16829. It accepts the following values:
  16830. @table @samp
  16831. @item combined
  16832. @item separate
  16833. @end table
  16834. Default is @code{combined}.
  16835. @item minamp
  16836. Set minimum amplitude used in @code{log} amplitude scaler.
  16837. @end table
  16838. @anchor{showspectrum}
  16839. @section showspectrum
  16840. Convert input audio to a video output, representing the audio frequency
  16841. spectrum.
  16842. The filter accepts the following options:
  16843. @table @option
  16844. @item size, s
  16845. Specify the video size for the output. For the syntax of this option, check the
  16846. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  16847. Default value is @code{640x512}.
  16848. @item slide
  16849. Specify how the spectrum should slide along the window.
  16850. It accepts the following values:
  16851. @table @samp
  16852. @item replace
  16853. the samples start again on the left when they reach the right
  16854. @item scroll
  16855. the samples scroll from right to left
  16856. @item fullframe
  16857. frames are only produced when the samples reach the right
  16858. @item rscroll
  16859. the samples scroll from left to right
  16860. @end table
  16861. Default value is @code{replace}.
  16862. @item mode
  16863. Specify display mode.
  16864. It accepts the following values:
  16865. @table @samp
  16866. @item combined
  16867. all channels are displayed in the same row
  16868. @item separate
  16869. all channels are displayed in separate rows
  16870. @end table
  16871. Default value is @samp{combined}.
  16872. @item color
  16873. Specify display color mode.
  16874. It accepts the following values:
  16875. @table @samp
  16876. @item channel
  16877. each channel is displayed in a separate color
  16878. @item intensity
  16879. each channel is displayed using the same color scheme
  16880. @item rainbow
  16881. each channel is displayed using the rainbow color scheme
  16882. @item moreland
  16883. each channel is displayed using the moreland color scheme
  16884. @item nebulae
  16885. each channel is displayed using the nebulae color scheme
  16886. @item fire
  16887. each channel is displayed using the fire color scheme
  16888. @item fiery
  16889. each channel is displayed using the fiery color scheme
  16890. @item fruit
  16891. each channel is displayed using the fruit color scheme
  16892. @item cool
  16893. each channel is displayed using the cool color scheme
  16894. @item magma
  16895. each channel is displayed using the magma color scheme
  16896. @item green
  16897. each channel is displayed using the green color scheme
  16898. @item viridis
  16899. each channel is displayed using the viridis color scheme
  16900. @item plasma
  16901. each channel is displayed using the plasma color scheme
  16902. @item cividis
  16903. each channel is displayed using the cividis color scheme
  16904. @item terrain
  16905. each channel is displayed using the terrain color scheme
  16906. @end table
  16907. Default value is @samp{channel}.
  16908. @item scale
  16909. Specify scale used for calculating intensity color values.
  16910. It accepts the following values:
  16911. @table @samp
  16912. @item lin
  16913. linear
  16914. @item sqrt
  16915. square root, default
  16916. @item cbrt
  16917. cubic root
  16918. @item log
  16919. logarithmic
  16920. @item 4thrt
  16921. 4th root
  16922. @item 5thrt
  16923. 5th root
  16924. @end table
  16925. Default value is @samp{sqrt}.
  16926. @item saturation
  16927. Set saturation modifier for displayed colors. Negative values provide
  16928. alternative color scheme. @code{0} is no saturation at all.
  16929. Saturation must be in [-10.0, 10.0] range.
  16930. Default value is @code{1}.
  16931. @item win_func
  16932. Set window function.
  16933. It accepts the following values:
  16934. @table @samp
  16935. @item rect
  16936. @item bartlett
  16937. @item hann
  16938. @item hanning
  16939. @item hamming
  16940. @item blackman
  16941. @item welch
  16942. @item flattop
  16943. @item bharris
  16944. @item bnuttall
  16945. @item bhann
  16946. @item sine
  16947. @item nuttall
  16948. @item lanczos
  16949. @item gauss
  16950. @item tukey
  16951. @item dolph
  16952. @item cauchy
  16953. @item parzen
  16954. @item poisson
  16955. @item bohman
  16956. @end table
  16957. Default value is @code{hann}.
  16958. @item orientation
  16959. Set orientation of time vs frequency axis. Can be @code{vertical} or
  16960. @code{horizontal}. Default is @code{vertical}.
  16961. @item overlap
  16962. Set ratio of overlap window. Default value is @code{0}.
  16963. When value is @code{1} overlap is set to recommended size for specific
  16964. window function currently used.
  16965. @item gain
  16966. Set scale gain for calculating intensity color values.
  16967. Default value is @code{1}.
  16968. @item data
  16969. Set which data to display. Can be @code{magnitude}, default or @code{phase}.
  16970. @item rotation
  16971. Set color rotation, must be in [-1.0, 1.0] range.
  16972. Default value is @code{0}.
  16973. @item start
  16974. Set start frequency from which to display spectrogram. Default is @code{0}.
  16975. @item stop
  16976. Set stop frequency to which to display spectrogram. Default is @code{0}.
  16977. @item fps
  16978. Set upper frame rate limit. Default is @code{auto}, unlimited.
  16979. @item legend
  16980. Draw time and frequency axes and legends. Default is disabled.
  16981. @end table
  16982. The usage is very similar to the showwaves filter; see the examples in that
  16983. section.
  16984. @subsection Examples
  16985. @itemize
  16986. @item
  16987. Large window with logarithmic color scaling:
  16988. @example
  16989. showspectrum=s=1280x480:scale=log
  16990. @end example
  16991. @item
  16992. Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
  16993. @example
  16994. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  16995. [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
  16996. @end example
  16997. @end itemize
  16998. @section showspectrumpic
  16999. Convert input audio to a single video frame, representing the audio frequency
  17000. spectrum.
  17001. The filter accepts the following options:
  17002. @table @option
  17003. @item size, s
  17004. Specify the video size for the output. For the syntax of this option, check the
  17005. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  17006. Default value is @code{4096x2048}.
  17007. @item mode
  17008. Specify display mode.
  17009. It accepts the following values:
  17010. @table @samp
  17011. @item combined
  17012. all channels are displayed in the same row
  17013. @item separate
  17014. all channels are displayed in separate rows
  17015. @end table
  17016. Default value is @samp{combined}.
  17017. @item color
  17018. Specify display color mode.
  17019. It accepts the following values:
  17020. @table @samp
  17021. @item channel
  17022. each channel is displayed in a separate color
  17023. @item intensity
  17024. each channel is displayed using the same color scheme
  17025. @item rainbow
  17026. each channel is displayed using the rainbow color scheme
  17027. @item moreland
  17028. each channel is displayed using the moreland color scheme
  17029. @item nebulae
  17030. each channel is displayed using the nebulae color scheme
  17031. @item fire
  17032. each channel is displayed using the fire color scheme
  17033. @item fiery
  17034. each channel is displayed using the fiery color scheme
  17035. @item fruit
  17036. each channel is displayed using the fruit color scheme
  17037. @item cool
  17038. each channel is displayed using the cool color scheme
  17039. @item magma
  17040. each channel is displayed using the magma color scheme
  17041. @item green
  17042. each channel is displayed using the green color scheme
  17043. @item viridis
  17044. each channel is displayed using the viridis color scheme
  17045. @item plasma
  17046. each channel is displayed using the plasma color scheme
  17047. @item cividis
  17048. each channel is displayed using the cividis color scheme
  17049. @item terrain
  17050. each channel is displayed using the terrain color scheme
  17051. @end table
  17052. Default value is @samp{intensity}.
  17053. @item scale
  17054. Specify scale used for calculating intensity color values.
  17055. It accepts the following values:
  17056. @table @samp
  17057. @item lin
  17058. linear
  17059. @item sqrt
  17060. square root, default
  17061. @item cbrt
  17062. cubic root
  17063. @item log
  17064. logarithmic
  17065. @item 4thrt
  17066. 4th root
  17067. @item 5thrt
  17068. 5th root
  17069. @end table
  17070. Default value is @samp{log}.
  17071. @item saturation
  17072. Set saturation modifier for displayed colors. Negative values provide
  17073. alternative color scheme. @code{0} is no saturation at all.
  17074. Saturation must be in [-10.0, 10.0] range.
  17075. Default value is @code{1}.
  17076. @item win_func
  17077. Set window function.
  17078. It accepts the following values:
  17079. @table @samp
  17080. @item rect
  17081. @item bartlett
  17082. @item hann
  17083. @item hanning
  17084. @item hamming
  17085. @item blackman
  17086. @item welch
  17087. @item flattop
  17088. @item bharris
  17089. @item bnuttall
  17090. @item bhann
  17091. @item sine
  17092. @item nuttall
  17093. @item lanczos
  17094. @item gauss
  17095. @item tukey
  17096. @item dolph
  17097. @item cauchy
  17098. @item parzen
  17099. @item poisson
  17100. @item bohman
  17101. @end table
  17102. Default value is @code{hann}.
  17103. @item orientation
  17104. Set orientation of time vs frequency axis. Can be @code{vertical} or
  17105. @code{horizontal}. Default is @code{vertical}.
  17106. @item gain
  17107. Set scale gain for calculating intensity color values.
  17108. Default value is @code{1}.
  17109. @item legend
  17110. Draw time and frequency axes and legends. Default is enabled.
  17111. @item rotation
  17112. Set color rotation, must be in [-1.0, 1.0] range.
  17113. Default value is @code{0}.
  17114. @item start
  17115. Set start frequency from which to display spectrogram. Default is @code{0}.
  17116. @item stop
  17117. Set stop frequency to which to display spectrogram. Default is @code{0}.
  17118. @end table
  17119. @subsection Examples
  17120. @itemize
  17121. @item
  17122. Extract an audio spectrogram of a whole audio track
  17123. in a 1024x1024 picture using @command{ffmpeg}:
  17124. @example
  17125. ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
  17126. @end example
  17127. @end itemize
  17128. @section showvolume
  17129. Convert input audio volume to a video output.
  17130. The filter accepts the following options:
  17131. @table @option
  17132. @item rate, r
  17133. Set video rate.
  17134. @item b
  17135. Set border width, allowed range is [0, 5]. Default is 1.
  17136. @item w
  17137. Set channel width, allowed range is [80, 8192]. Default is 400.
  17138. @item h
  17139. Set channel height, allowed range is [1, 900]. Default is 20.
  17140. @item f
  17141. Set fade, allowed range is [0, 1]. Default is 0.95.
  17142. @item c
  17143. Set volume color expression.
  17144. The expression can use the following variables:
  17145. @table @option
  17146. @item VOLUME
  17147. Current max volume of channel in dB.
  17148. @item PEAK
  17149. Current peak.
  17150. @item CHANNEL
  17151. Current channel number, starting from 0.
  17152. @end table
  17153. @item t
  17154. If set, displays channel names. Default is enabled.
  17155. @item v
  17156. If set, displays volume values. Default is enabled.
  17157. @item o
  17158. Set orientation, can be horizontal: @code{h} or vertical: @code{v},
  17159. default is @code{h}.
  17160. @item s
  17161. Set step size, allowed range is [0, 5]. Default is 0, which means
  17162. step is disabled.
  17163. @item p
  17164. Set background opacity, allowed range is [0, 1]. Default is 0.
  17165. @item m
  17166. Set metering mode, can be peak: @code{p} or rms: @code{r},
  17167. default is @code{p}.
  17168. @item ds
  17169. Set display scale, can be linear: @code{lin} or log: @code{log},
  17170. default is @code{lin}.
  17171. @item dm
  17172. In second.
  17173. If set to > 0., display a line for the max level
  17174. in the previous seconds.
  17175. default is disabled: @code{0.}
  17176. @item dmc
  17177. The color of the max line. Use when @code{dm} option is set to > 0.
  17178. default is: @code{orange}
  17179. @end table
  17180. @section showwaves
  17181. Convert input audio to a video output, representing the samples waves.
  17182. The filter accepts the following options:
  17183. @table @option
  17184. @item size, s
  17185. Specify the video size for the output. For the syntax of this option, check the
  17186. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  17187. Default value is @code{600x240}.
  17188. @item mode
  17189. Set display mode.
  17190. Available values are:
  17191. @table @samp
  17192. @item point
  17193. Draw a point for each sample.
  17194. @item line
  17195. Draw a vertical line for each sample.
  17196. @item p2p
  17197. Draw a point for each sample and a line between them.
  17198. @item cline
  17199. Draw a centered vertical line for each sample.
  17200. @end table
  17201. Default value is @code{point}.
  17202. @item n
  17203. Set the number of samples which are printed on the same column. A
  17204. larger value will decrease the frame rate. Must be a positive
  17205. integer. This option can be set only if the value for @var{rate}
  17206. is not explicitly specified.
  17207. @item rate, r
  17208. Set the (approximate) output frame rate. This is done by setting the
  17209. option @var{n}. Default value is "25".
  17210. @item split_channels
  17211. Set if channels should be drawn separately or overlap. Default value is 0.
  17212. @item colors
  17213. Set colors separated by '|' which are going to be used for drawing of each channel.
  17214. @item scale
  17215. Set amplitude scale.
  17216. Available values are:
  17217. @table @samp
  17218. @item lin
  17219. Linear.
  17220. @item log
  17221. Logarithmic.
  17222. @item sqrt
  17223. Square root.
  17224. @item cbrt
  17225. Cubic root.
  17226. @end table
  17227. Default is linear.
  17228. @item draw
  17229. Set the draw mode. This is mostly useful to set for high @var{n}.
  17230. Available values are:
  17231. @table @samp
  17232. @item scale
  17233. Scale pixel values for each drawn sample.
  17234. @item full
  17235. Draw every sample directly.
  17236. @end table
  17237. Default value is @code{scale}.
  17238. @end table
  17239. @subsection Examples
  17240. @itemize
  17241. @item
  17242. Output the input file audio and the corresponding video representation
  17243. at the same time:
  17244. @example
  17245. amovie=a.mp3,asplit[out0],showwaves[out1]
  17246. @end example
  17247. @item
  17248. Create a synthetic signal and show it with showwaves, forcing a
  17249. frame rate of 30 frames per second:
  17250. @example
  17251. aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
  17252. @end example
  17253. @end itemize
  17254. @section showwavespic
  17255. Convert input audio to a single video frame, representing the samples waves.
  17256. The filter accepts the following options:
  17257. @table @option
  17258. @item size, s
  17259. Specify the video size for the output. For the syntax of this option, check the
  17260. @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
  17261. Default value is @code{600x240}.
  17262. @item split_channels
  17263. Set if channels should be drawn separately or overlap. Default value is 0.
  17264. @item colors
  17265. Set colors separated by '|' which are going to be used for drawing of each channel.
  17266. @item scale
  17267. Set amplitude scale.
  17268. Available values are:
  17269. @table @samp
  17270. @item lin
  17271. Linear.
  17272. @item log
  17273. Logarithmic.
  17274. @item sqrt
  17275. Square root.
  17276. @item cbrt
  17277. Cubic root.
  17278. @end table
  17279. Default is linear.
  17280. @end table
  17281. @subsection Examples
  17282. @itemize
  17283. @item
  17284. Extract a channel split representation of the wave form of a whole audio track
  17285. in a 1024x800 picture using @command{ffmpeg}:
  17286. @example
  17287. ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
  17288. @end example
  17289. @end itemize
  17290. @section sidedata, asidedata
  17291. Delete frame side data, or select frames based on it.
  17292. This filter accepts the following options:
  17293. @table @option
  17294. @item mode
  17295. Set mode of operation of the filter.
  17296. Can be one of the following:
  17297. @table @samp
  17298. @item select
  17299. Select every frame with side data of @code{type}.
  17300. @item delete
  17301. Delete side data of @code{type}. If @code{type} is not set, delete all side
  17302. data in the frame.
  17303. @end table
  17304. @item type
  17305. Set side data type used with all modes. Must be set for @code{select} mode. For
  17306. the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
  17307. in @file{libavutil/frame.h}. For example, to choose
  17308. @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
  17309. @end table
  17310. @section spectrumsynth
  17311. Sythesize audio from 2 input video spectrums, first input stream represents
  17312. magnitude across time and second represents phase across time.
  17313. The filter will transform from frequency domain as displayed in videos back
  17314. to time domain as presented in audio output.
  17315. This filter is primarily created for reversing processed @ref{showspectrum}
  17316. filter outputs, but can synthesize sound from other spectrograms too.
  17317. But in such case results are going to be poor if the phase data is not
  17318. available, because in such cases phase data need to be recreated, usually
  17319. it's just recreated from random noise.
  17320. For best results use gray only output (@code{channel} color mode in
  17321. @ref{showspectrum} filter) and @code{log} scale for magnitude video and
  17322. @code{lin} scale for phase video. To produce phase, for 2nd video, use
  17323. @code{data} option. Inputs videos should generally use @code{fullframe}
  17324. slide mode as that saves resources needed for decoding video.
  17325. The filter accepts the following options:
  17326. @table @option
  17327. @item sample_rate
  17328. Specify sample rate of output audio, the sample rate of audio from which
  17329. spectrum was generated may differ.
  17330. @item channels
  17331. Set number of channels represented in input video spectrums.
  17332. @item scale
  17333. Set scale which was used when generating magnitude input spectrum.
  17334. Can be @code{lin} or @code{log}. Default is @code{log}.
  17335. @item slide
  17336. Set slide which was used when generating inputs spectrums.
  17337. Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
  17338. Default is @code{fullframe}.
  17339. @item win_func
  17340. Set window function used for resynthesis.
  17341. @item overlap
  17342. Set window overlap. In range @code{[0, 1]}. Default is @code{1},
  17343. which means optimal overlap for selected window function will be picked.
  17344. @item orientation
  17345. Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
  17346. Default is @code{vertical}.
  17347. @end table
  17348. @subsection Examples
  17349. @itemize
  17350. @item
  17351. First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
  17352. then resynthesize videos back to audio with spectrumsynth:
  17353. @example
  17354. 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
  17355. 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
  17356. ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
  17357. @end example
  17358. @end itemize
  17359. @section split, asplit
  17360. Split input into several identical outputs.
  17361. @code{asplit} works with audio input, @code{split} with video.
  17362. The filter accepts a single parameter which specifies the number of outputs. If
  17363. unspecified, it defaults to 2.
  17364. @subsection Examples
  17365. @itemize
  17366. @item
  17367. Create two separate outputs from the same input:
  17368. @example
  17369. [in] split [out0][out1]
  17370. @end example
  17371. @item
  17372. To create 3 or more outputs, you need to specify the number of
  17373. outputs, like in:
  17374. @example
  17375. [in] asplit=3 [out0][out1][out2]
  17376. @end example
  17377. @item
  17378. Create two separate outputs from the same input, one cropped and
  17379. one padded:
  17380. @example
  17381. [in] split [splitout1][splitout2];
  17382. [splitout1] crop=100:100:0:0 [cropout];
  17383. [splitout2] pad=200:200:100:100 [padout];
  17384. @end example
  17385. @item
  17386. Create 5 copies of the input audio with @command{ffmpeg}:
  17387. @example
  17388. ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
  17389. @end example
  17390. @end itemize
  17391. @section zmq, azmq
  17392. Receive commands sent through a libzmq client, and forward them to
  17393. filters in the filtergraph.
  17394. @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
  17395. must be inserted between two video filters, @code{azmq} between two
  17396. audio filters. Both are capable to send messages to any filter type.
  17397. To enable these filters you need to install the libzmq library and
  17398. headers and configure FFmpeg with @code{--enable-libzmq}.
  17399. For more information about libzmq see:
  17400. @url{http://www.zeromq.org/}
  17401. The @code{zmq} and @code{azmq} filters work as a libzmq server, which
  17402. receives messages sent through a network interface defined by the
  17403. @option{bind_address} (or the abbreviation "@option{b}") option.
  17404. Default value of this option is @file{tcp://localhost:5555}. You may
  17405. want to alter this value to your needs, but do not forget to escape any
  17406. ':' signs (see @ref{filtergraph escaping}).
  17407. The received message must be in the form:
  17408. @example
  17409. @var{TARGET} @var{COMMAND} [@var{ARG}]
  17410. @end example
  17411. @var{TARGET} specifies the target of the command, usually the name of
  17412. the filter class or a specific filter instance name. The default
  17413. filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
  17414. but you can override this by using the @samp{filter_name@@id} syntax
  17415. (see @ref{Filtergraph syntax}).
  17416. @var{COMMAND} specifies the name of the command for the target filter.
  17417. @var{ARG} is optional and specifies the optional argument list for the
  17418. given @var{COMMAND}.
  17419. Upon reception, the message is processed and the corresponding command
  17420. is injected into the filtergraph. Depending on the result, the filter
  17421. will send a reply to the client, adopting the format:
  17422. @example
  17423. @var{ERROR_CODE} @var{ERROR_REASON}
  17424. @var{MESSAGE}
  17425. @end example
  17426. @var{MESSAGE} is optional.
  17427. @subsection Examples
  17428. Look at @file{tools/zmqsend} for an example of a zmq client which can
  17429. be used to send commands processed by these filters.
  17430. Consider the following filtergraph generated by @command{ffplay}.
  17431. In this example the last overlay filter has an instance name. All other
  17432. filters will have default instance names.
  17433. @example
  17434. ffplay -dumpgraph 1 -f lavfi "
  17435. color=s=100x100:c=red [l];
  17436. color=s=100x100:c=blue [r];
  17437. nullsrc=s=200x100, zmq [bg];
  17438. [bg][l] overlay [bg+l];
  17439. [bg+l][r] overlay@@my=x=100 "
  17440. @end example
  17441. To change the color of the left side of the video, the following
  17442. command can be used:
  17443. @example
  17444. echo Parsed_color_0 c yellow | tools/zmqsend
  17445. @end example
  17446. To change the right side:
  17447. @example
  17448. echo Parsed_color_1 c pink | tools/zmqsend
  17449. @end example
  17450. To change the position of the right side:
  17451. @example
  17452. echo overlay@@my x 150 | tools/zmqsend
  17453. @end example
  17454. @c man end MULTIMEDIA FILTERS
  17455. @chapter Multimedia Sources
  17456. @c man begin MULTIMEDIA SOURCES
  17457. Below is a description of the currently available multimedia sources.
  17458. @section amovie
  17459. This is the same as @ref{movie} source, except it selects an audio
  17460. stream by default.
  17461. @anchor{movie}
  17462. @section movie
  17463. Read audio and/or video stream(s) from a movie container.
  17464. It accepts the following parameters:
  17465. @table @option
  17466. @item filename
  17467. The name of the resource to read (not necessarily a file; it can also be a
  17468. device or a stream accessed through some protocol).
  17469. @item format_name, f
  17470. Specifies the format assumed for the movie to read, and can be either
  17471. the name of a container or an input device. If not specified, the
  17472. format is guessed from @var{movie_name} or by probing.
  17473. @item seek_point, sp
  17474. Specifies the seek point in seconds. The frames will be output
  17475. starting from this seek point. The parameter is evaluated with
  17476. @code{av_strtod}, so the numerical value may be suffixed by an IS
  17477. postfix. The default value is "0".
  17478. @item streams, s
  17479. Specifies the streams to read. Several streams can be specified,
  17480. separated by "+". The source will then have as many outputs, in the
  17481. same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
  17482. section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
  17483. respectively the default (best suited) video and audio stream. Default
  17484. is "dv", or "da" if the filter is called as "amovie".
  17485. @item stream_index, si
  17486. Specifies the index of the video stream to read. If the value is -1,
  17487. the most suitable video stream will be automatically selected. The default
  17488. value is "-1". Deprecated. If the filter is called "amovie", it will select
  17489. audio instead of video.
  17490. @item loop
  17491. Specifies how many times to read the stream in sequence.
  17492. If the value is 0, the stream will be looped infinitely.
  17493. Default value is "1".
  17494. Note that when the movie is looped the source timestamps are not
  17495. changed, so it will generate non monotonically increasing timestamps.
  17496. @item discontinuity
  17497. Specifies the time difference between frames above which the point is
  17498. considered a timestamp discontinuity which is removed by adjusting the later
  17499. timestamps.
  17500. @end table
  17501. It allows overlaying a second video on top of the main input of
  17502. a filtergraph, as shown in this graph:
  17503. @example
  17504. input -----------> deltapts0 --> overlay --> output
  17505. ^
  17506. |
  17507. movie --> scale--> deltapts1 -------+
  17508. @end example
  17509. @subsection Examples
  17510. @itemize
  17511. @item
  17512. Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
  17513. on top of the input labelled "in":
  17514. @example
  17515. movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
  17516. [in] setpts=PTS-STARTPTS [main];
  17517. [main][over] overlay=16:16 [out]
  17518. @end example
  17519. @item
  17520. Read from a video4linux2 device, and overlay it on top of the input
  17521. labelled "in":
  17522. @example
  17523. movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
  17524. [in] setpts=PTS-STARTPTS [main];
  17525. [main][over] overlay=16:16 [out]
  17526. @end example
  17527. @item
  17528. Read the first video stream and the audio stream with id 0x81 from
  17529. dvd.vob; the video is connected to the pad named "video" and the audio is
  17530. connected to the pad named "audio":
  17531. @example
  17532. movie=dvd.vob:s=v:0+#0x81 [video] [audio]
  17533. @end example
  17534. @end itemize
  17535. @subsection Commands
  17536. Both movie and amovie support the following commands:
  17537. @table @option
  17538. @item seek
  17539. Perform seek using "av_seek_frame".
  17540. The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
  17541. @itemize
  17542. @item
  17543. @var{stream_index}: If stream_index is -1, a default
  17544. stream is selected, and @var{timestamp} is automatically converted
  17545. from AV_TIME_BASE units to the stream specific time_base.
  17546. @item
  17547. @var{timestamp}: Timestamp in AVStream.time_base units
  17548. or, if no stream is specified, in AV_TIME_BASE units.
  17549. @item
  17550. @var{flags}: Flags which select direction and seeking mode.
  17551. @end itemize
  17552. @item get_duration
  17553. Get movie duration in AV_TIME_BASE units.
  17554. @end table
  17555. @c man end MULTIMEDIA SOURCES