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.

11830 lines
323KB

  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. @example
  9. [main]
  10. input --> split ---------------------> overlay --> output
  11. | ^
  12. |[tmp] [flip]|
  13. +-----> crop --> vflip -------+
  14. @end example
  15. This filtergraph splits the input stream in two streams, then sends one
  16. stream through the crop filter and the vflip filter, before merging it
  17. back with the other stream by overlaying it on top. You can use the
  18. following command to achieve this:
  19. @example
  20. ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
  21. @end example
  22. The result will be that the top half of the video is mirrored
  23. onto the bottom half of the output video.
  24. Filters in the same linear chain are separated by commas, and distinct
  25. linear chains of filters are separated by semicolons. In our example,
  26. @var{crop,vflip} are in one linear chain, @var{split} and
  27. @var{overlay} are separately in another. The points where the linear
  28. chains join are labelled by names enclosed in square brackets. In the
  29. example, the split filter generates two outputs that are associated to
  30. the labels @var{[main]} and @var{[tmp]}.
  31. The stream sent to the second output of @var{split}, labelled as
  32. @var{[tmp]}, is processed through the @var{crop} filter, which crops
  33. away the lower half part of the video, and then vertically flipped. The
  34. @var{overlay} filter takes in input the first unchanged output of the
  35. split filter (which was labelled as @var{[main]}), and overlay on its
  36. lower half the output generated by the @var{crop,vflip} filterchain.
  37. Some filters take in input a list of parameters: they are specified
  38. after the filter name and an equal sign, and are separated from each other
  39. by a colon.
  40. There exist so-called @var{source filters} that do not have an
  41. audio/video input, and @var{sink filters} that will not have audio/video
  42. output.
  43. @c man end FILTERING INTRODUCTION
  44. @chapter graph2dot
  45. @c man begin GRAPH2DOT
  46. The @file{graph2dot} program included in the FFmpeg @file{tools}
  47. directory can be used to parse a filtergraph description and issue a
  48. corresponding textual representation in the dot language.
  49. Invoke the command:
  50. @example
  51. graph2dot -h
  52. @end example
  53. to see how to use @file{graph2dot}.
  54. You can then pass the dot description to the @file{dot} program (from
  55. the graphviz suite of programs) and obtain a graphical representation
  56. of the filtergraph.
  57. For example the sequence of commands:
  58. @example
  59. echo @var{GRAPH_DESCRIPTION} | \
  60. tools/graph2dot -o graph.tmp && \
  61. dot -Tpng graph.tmp -o graph.png && \
  62. display graph.png
  63. @end example
  64. can be used to create and display an image representing the graph
  65. described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
  66. a complete self-contained graph, with its inputs and outputs explicitly defined.
  67. For example if your command line is of the form:
  68. @example
  69. ffmpeg -i infile -vf scale=640:360 outfile
  70. @end example
  71. your @var{GRAPH_DESCRIPTION} string will need to be of the form:
  72. @example
  73. nullsrc,scale=640:360,nullsink
  74. @end example
  75. you may also need to set the @var{nullsrc} parameters and add a @var{format}
  76. filter in order to simulate a specific input file.
  77. @c man end GRAPH2DOT
  78. @chapter Filtergraph description
  79. @c man begin FILTERGRAPH DESCRIPTION
  80. A filtergraph is a directed graph of connected filters. It can contain
  81. cycles, and there can be multiple links between a pair of
  82. filters. Each link has one input pad on one side connecting it to one
  83. filter from which it takes its input, and one output pad on the other
  84. side connecting it to one filter accepting its output.
  85. Each filter in a filtergraph is an instance of a filter class
  86. registered in the application, which defines the features and the
  87. number of input and output pads of the filter.
  88. A filter with no input pads is called a "source", and a filter with no
  89. output pads is called a "sink".
  90. @anchor{Filtergraph syntax}
  91. @section Filtergraph syntax
  92. A filtergraph has a textual representation, which is recognized by the
  93. @option{-filter}/@option{-vf}/@option{-af} and
  94. @option{-filter_complex} options in @command{ffmpeg} and
  95. @option{-vf}/@option{-af} in @command{ffplay}, and by the
  96. @code{avfilter_graph_parse_ptr()} function defined in
  97. @file{libavfilter/avfilter.h}.
  98. A filterchain consists of a sequence of connected filters, each one
  99. connected to the previous one in the sequence. A filterchain is
  100. represented by a list of ","-separated filter descriptions.
  101. A filtergraph consists of a sequence of filterchains. A sequence of
  102. filterchains is represented by a list of ";"-separated filterchain
  103. descriptions.
  104. A filter is represented by a string of the form:
  105. [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
  106. @var{filter_name} is the name of the filter class of which the
  107. described filter is an instance of, and has to be the name of one of
  108. the filter classes registered in the program.
  109. The name of the filter class is optionally followed by a string
  110. "=@var{arguments}".
  111. @var{arguments} is a string which contains the parameters used to
  112. initialize the filter instance. It may have one of two forms:
  113. @itemize
  114. @item
  115. A ':'-separated list of @var{key=value} pairs.
  116. @item
  117. A ':'-separated list of @var{value}. In this case, the keys are assumed to be
  118. the option names in the order they are declared. E.g. the @code{fade} filter
  119. declares three options in this order -- @option{type}, @option{start_frame} and
  120. @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
  121. @var{in} is assigned to the option @option{type}, @var{0} to
  122. @option{start_frame} and @var{30} to @option{nb_frames}.
  123. @item
  124. A ':'-separated list of mixed direct @var{value} and long @var{key=value}
  125. pairs. The direct @var{value} must precede the @var{key=value} pairs, and
  126. follow the same constraints order of the previous point. The following
  127. @var{key=value} pairs can be set in any preferred order.
  128. @end itemize
  129. If the option value itself is a list of items (e.g. the @code{format} filter
  130. takes a list of pixel formats), the items in the list are usually separated by
  131. '|'.
  132. The list of arguments can be quoted using the character "'" as initial
  133. and ending mark, and the character '\' 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. "[]=;,") is encountered.
  137. The name and arguments of the filter are optionally preceded and
  138. followed by a list of link labels.
  139. A link label allows one to name a link and associate it to a filter output
  140. or input pad. The preceding labels @var{in_link_1}
  141. ... @var{in_link_N}, are associated to the filter input pads,
  142. the following labels @var{out_link_1} ... @var{out_link_M}, are
  143. associated to the output pads.
  144. When two link labels with the same name are found in the
  145. filtergraph, a link between the corresponding input and output pad is
  146. created.
  147. If an output pad is not labelled, it is linked by default to the first
  148. unlabelled input pad of the next filter in the filterchain.
  149. For example in the filterchain
  150. @example
  151. nullsrc, split[L1], [L2]overlay, nullsink
  152. @end example
  153. the split filter instance has two output pads, and the overlay filter
  154. instance two input pads. The first output pad of split is labelled
  155. "L1", the first input pad of overlay is labelled "L2", and the second
  156. output pad of split is linked to the second input pad of overlay,
  157. which are both unlabelled.
  158. In a filter description, if the input label of the first filter is not
  159. specified, "in" is assumed; if the output label of the last filter is not
  160. specified, "out" is assumed.
  161. In a complete filterchain all the unlabelled filter input and output
  162. pads must be connected. A filtergraph is considered valid if all the
  163. filter input and output pads of all the filterchains are connected.
  164. Libavfilter will automatically insert @ref{scale} filters where format
  165. conversion is required. It is possible to specify swscale flags
  166. for those automatically inserted scalers by prepending
  167. @code{sws_flags=@var{flags};}
  168. to the filtergraph description.
  169. Here is a BNF description of the filtergraph syntax:
  170. @example
  171. @var{NAME} ::= sequence of alphanumeric characters and '_'
  172. @var{LINKLABEL} ::= "[" @var{NAME} "]"
  173. @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
  174. @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
  175. @var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
  176. @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
  177. @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
  178. @end example
  179. @section Notes on filtergraph escaping
  180. Filtergraph description composition entails several levels of
  181. escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
  182. section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
  183. information about the employed escaping procedure.
  184. A first level escaping affects the content of each filter option
  185. value, which may contain the special character @code{:} used to
  186. separate values, or one of the escaping characters @code{\'}.
  187. A second level escaping affects the whole filter description, which
  188. may contain the escaping characters @code{\'} or the special
  189. characters @code{[],;} used by the filtergraph description.
  190. Finally, when you specify a filtergraph on a shell commandline, you
  191. need to perform a third level escaping for the shell special
  192. characters contained within it.
  193. For example, consider the following string to be embedded in
  194. the @ref{drawtext} filter description @option{text} value:
  195. @example
  196. this is a 'string': may contain one, or more, special characters
  197. @end example
  198. This string contains the @code{'} special escaping character, and the
  199. @code{:} special character, so it needs to be escaped in this way:
  200. @example
  201. text=this is a \'string\'\: may contain one, or more, special characters
  202. @end example
  203. A second level of escaping is required when embedding the filter
  204. description in a filtergraph description, in order to escape all the
  205. filtergraph special characters. Thus the example above becomes:
  206. @example
  207. drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
  208. @end example
  209. (note that in addition to the @code{\'} escaping special characters,
  210. also @code{,} needs to be escaped).
  211. Finally an additional level of escaping is needed when writing the
  212. filtergraph description in a shell command, which depends on the
  213. escaping rules of the adopted shell. For example, assuming that
  214. @code{\} is special and needs to be escaped with another @code{\}, the
  215. previous string will finally result in:
  216. @example
  217. -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
  218. @end example
  219. @chapter Timeline editing
  220. Some filters support a generic @option{enable} option. For the filters
  221. supporting timeline editing, this option can be set to an expression which is
  222. evaluated before sending a frame to the filter. If the evaluation is non-zero,
  223. the filter will be enabled, otherwise the frame will be sent unchanged to the
  224. next filter in the filtergraph.
  225. The expression accepts the following values:
  226. @table @samp
  227. @item t
  228. timestamp expressed in seconds, NAN if the input timestamp is unknown
  229. @item n
  230. sequential number of the input frame, starting from 0
  231. @item pos
  232. the position in the file of the input frame, NAN if unknown
  233. @item w
  234. @item h
  235. width and height of the input frame if video
  236. @end table
  237. Additionally, these filters support an @option{enable} command that can be used
  238. to re-define the expression.
  239. Like any other filtering option, the @option{enable} option follows the same
  240. rules.
  241. For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
  242. minutes, and a @ref{curves} filter starting at 3 seconds:
  243. @example
  244. smartblur = enable='between(t,10,3*60)',
  245. curves = enable='gte(t,3)' : preset=cross_process
  246. @end example
  247. @c man end FILTERGRAPH DESCRIPTION
  248. @chapter Audio Filters
  249. @c man begin AUDIO FILTERS
  250. When you configure your FFmpeg build, you can disable any of the
  251. existing filters using @code{--disable-filters}.
  252. The configure output will show the audio filters included in your
  253. build.
  254. Below is a description of the currently available audio filters.
  255. @section adelay
  256. Delay one or more audio channels.
  257. Samples in delayed channel are filled with silence.
  258. The filter accepts the following option:
  259. @table @option
  260. @item delays
  261. Set list of delays in milliseconds for each channel separated by '|'.
  262. At least one delay greater than 0 should be provided.
  263. Unused delays will be silently ignored. If number of given delays is
  264. smaller than number of channels all remaining channels will not be delayed.
  265. @end table
  266. @subsection Examples
  267. @itemize
  268. @item
  269. Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
  270. the second channel (and any other channels that may be present) unchanged.
  271. @example
  272. adelay=1500|0|500
  273. @end example
  274. @end itemize
  275. @section aecho
  276. Apply echoing to the input audio.
  277. Echoes are reflected sound and can occur naturally amongst mountains
  278. (and sometimes large buildings) when talking or shouting; digital echo
  279. effects emulate this behaviour and are often used to help fill out the
  280. sound of a single instrument or vocal. The time difference between the
  281. original signal and the reflection is the @code{delay}, and the
  282. loudness of the reflected signal is the @code{decay}.
  283. Multiple echoes can have different delays and decays.
  284. A description of the accepted parameters follows.
  285. @table @option
  286. @item in_gain
  287. Set input gain of reflected signal. Default is @code{0.6}.
  288. @item out_gain
  289. Set output gain of reflected signal. Default is @code{0.3}.
  290. @item delays
  291. Set list of time intervals in milliseconds between original signal and reflections
  292. separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
  293. Default is @code{1000}.
  294. @item decays
  295. Set list of loudnesses of reflected signals separated by '|'.
  296. Allowed range for each @code{decay} is @code{(0 - 1.0]}.
  297. Default is @code{0.5}.
  298. @end table
  299. @subsection Examples
  300. @itemize
  301. @item
  302. Make it sound as if there are twice as many instruments as are actually playing:
  303. @example
  304. aecho=0.8:0.88:60:0.4
  305. @end example
  306. @item
  307. If delay is very short, then it sound like a (metallic) robot playing music:
  308. @example
  309. aecho=0.8:0.88:6:0.4
  310. @end example
  311. @item
  312. A longer delay will sound like an open air concert in the mountains:
  313. @example
  314. aecho=0.8:0.9:1000:0.3
  315. @end example
  316. @item
  317. Same as above but with one more mountain:
  318. @example
  319. aecho=0.8:0.9:1000|1800:0.3|0.25
  320. @end example
  321. @end itemize
  322. @section aeval
  323. Modify an audio signal according to the specified expressions.
  324. This filter accepts one or more expressions (one for each channel),
  325. which are evaluated and used to modify a corresponding audio signal.
  326. It accepts the following parameters:
  327. @table @option
  328. @item exprs
  329. Set the '|'-separated expressions list for each separate channel. If
  330. the number of input channels is greater than the number of
  331. expressions, the last specified expression is used for the remaining
  332. output channels.
  333. @item channel_layout, c
  334. Set output channel layout. If not specified, the channel layout is
  335. specified by the number of expressions. If set to @samp{same}, it will
  336. use by default the same input channel layout.
  337. @end table
  338. Each expression in @var{exprs} can contain the following constants and functions:
  339. @table @option
  340. @item ch
  341. channel number of the current expression
  342. @item n
  343. number of the evaluated sample, starting from 0
  344. @item s
  345. sample rate
  346. @item t
  347. time of the evaluated sample expressed in seconds
  348. @item nb_in_channels
  349. @item nb_out_channels
  350. input and output number of channels
  351. @item val(CH)
  352. the value of input channel with number @var{CH}
  353. @end table
  354. Note: this filter is slow. For faster processing you should use a
  355. dedicated filter.
  356. @subsection Examples
  357. @itemize
  358. @item
  359. Half volume:
  360. @example
  361. aeval=val(ch)/2:c=same
  362. @end example
  363. @item
  364. Invert phase of the second channel:
  365. @example
  366. aeval=val(0)|-val(1)
  367. @end example
  368. @end itemize
  369. @section afade
  370. Apply fade-in/out effect to input audio.
  371. A description of the accepted parameters follows.
  372. @table @option
  373. @item type, t
  374. Specify the effect type, can be either @code{in} for fade-in, or
  375. @code{out} for a fade-out effect. Default is @code{in}.
  376. @item start_sample, ss
  377. Specify the number of the start sample for starting to apply the fade
  378. effect. Default is 0.
  379. @item nb_samples, ns
  380. Specify the number of samples for which the fade effect has to last. At
  381. the end of the fade-in effect the output audio will have the same
  382. volume as the input audio, at the end of the fade-out transition
  383. the output audio will be silence. Default is 44100.
  384. @item start_time, st
  385. Specify the start time of the fade effect. Default is 0.
  386. The value must be specified as a time duration; see
  387. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  388. for the accepted syntax.
  389. If set this option is used instead of @var{start_sample}.
  390. @item duration, d
  391. Specify the duration of the fade effect. See
  392. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  393. for the accepted syntax.
  394. At the end of the fade-in effect the output audio will have the same
  395. volume as the input audio, at the end of the fade-out transition
  396. the output audio will be silence.
  397. By default the duration is determined by @var{nb_samples}.
  398. If set this option is used instead of @var{nb_samples}.
  399. @item curve
  400. Set curve for fade transition.
  401. It accepts the following values:
  402. @table @option
  403. @item tri
  404. select triangular, linear slope (default)
  405. @item qsin
  406. select quarter of sine wave
  407. @item hsin
  408. select half of sine wave
  409. @item esin
  410. select exponential sine wave
  411. @item log
  412. select logarithmic
  413. @item par
  414. select inverted parabola
  415. @item qua
  416. select quadratic
  417. @item cub
  418. select cubic
  419. @item squ
  420. select square root
  421. @item cbr
  422. select cubic root
  423. @end table
  424. @end table
  425. @subsection Examples
  426. @itemize
  427. @item
  428. Fade in first 15 seconds of audio:
  429. @example
  430. afade=t=in:ss=0:d=15
  431. @end example
  432. @item
  433. Fade out last 25 seconds of a 900 seconds audio:
  434. @example
  435. afade=t=out:st=875:d=25
  436. @end example
  437. @end itemize
  438. @anchor{aformat}
  439. @section aformat
  440. Set output format constraints for the input audio. The framework will
  441. negotiate the most appropriate format to minimize conversions.
  442. It accepts the following parameters:
  443. @table @option
  444. @item sample_fmts
  445. A '|'-separated list of requested sample formats.
  446. @item sample_rates
  447. A '|'-separated list of requested sample rates.
  448. @item channel_layouts
  449. A '|'-separated list of requested channel layouts.
  450. See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  451. for the required syntax.
  452. @end table
  453. If a parameter is omitted, all values are allowed.
  454. Force the output to either unsigned 8-bit or signed 16-bit stereo
  455. @example
  456. aformat=sample_fmts=u8|s16:channel_layouts=stereo
  457. @end example
  458. @section allpass
  459. Apply a two-pole all-pass filter with central frequency (in Hz)
  460. @var{frequency}, and filter-width @var{width}.
  461. An all-pass filter changes the audio's frequency to phase relationship
  462. without changing its frequency to amplitude relationship.
  463. The filter accepts the following options:
  464. @table @option
  465. @item frequency, f
  466. Set frequency in Hz.
  467. @item width_type
  468. Set method to specify band-width of filter.
  469. @table @option
  470. @item h
  471. Hz
  472. @item q
  473. Q-Factor
  474. @item o
  475. octave
  476. @item s
  477. slope
  478. @end table
  479. @item width, w
  480. Specify the band-width of a filter in width_type units.
  481. @end table
  482. @section amerge
  483. Merge two or more audio streams into a single multi-channel stream.
  484. The filter accepts the following options:
  485. @table @option
  486. @item inputs
  487. Set the number of inputs. Default is 2.
  488. @end table
  489. If the channel layouts of the inputs are disjoint, and therefore compatible,
  490. the channel layout of the output will be set accordingly and the channels
  491. will be reordered as necessary. If the channel layouts of the inputs are not
  492. disjoint, the output will have all the channels of the first input then all
  493. the channels of the second input, in that order, and the channel layout of
  494. the output will be the default value corresponding to the total number of
  495. channels.
  496. For example, if the first input is in 2.1 (FL+FR+LF) and the second input
  497. is FC+BL+BR, then the output will be in 5.1, with the channels in the
  498. following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
  499. first input, b1 is the first channel of the second input).
  500. On the other hand, if both input are in stereo, the output channels will be
  501. in the default order: a1, a2, b1, b2, and the channel layout will be
  502. arbitrarily set to 4.0, which may or may not be the expected value.
  503. All inputs must have the same sample rate, and format.
  504. If inputs do not have the same duration, the output will stop with the
  505. shortest.
  506. @subsection Examples
  507. @itemize
  508. @item
  509. Merge two mono files into a stereo stream:
  510. @example
  511. amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
  512. @end example
  513. @item
  514. Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
  515. @example
  516. 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
  517. @end example
  518. @end itemize
  519. @section amix
  520. Mixes multiple audio inputs into a single output.
  521. Note that this filter only supports float samples (the @var{amerge}
  522. and @var{pan} audio filters support many formats). If the @var{amix}
  523. input has integer samples then @ref{aresample} will be automatically
  524. inserted to perform the conversion to float samples.
  525. For example
  526. @example
  527. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
  528. @end example
  529. will mix 3 input audio streams to a single output with the same duration as the
  530. first input and a dropout transition time of 3 seconds.
  531. It accepts the following parameters:
  532. @table @option
  533. @item inputs
  534. The number of inputs. If unspecified, it defaults to 2.
  535. @item duration
  536. How to determine the end-of-stream.
  537. @table @option
  538. @item longest
  539. The duration of the longest input. (default)
  540. @item shortest
  541. The duration of the shortest input.
  542. @item first
  543. The duration of the first input.
  544. @end table
  545. @item dropout_transition
  546. The transition time, in seconds, for volume renormalization when an input
  547. stream ends. The default value is 2 seconds.
  548. @end table
  549. @section anull
  550. Pass the audio source unchanged to the output.
  551. @section apad
  552. Pad the end of an audio stream with silence.
  553. This can be used together with @command{ffmpeg} @option{-shortest} to
  554. extend audio streams to the same length as the video stream.
  555. A description of the accepted options follows.
  556. @table @option
  557. @item packet_size
  558. Set silence packet size. Default value is 4096.
  559. @item pad_len
  560. Set the number of samples of silence to add to the end. After the
  561. value is reached, the stream is terminated. This option is mutually
  562. exclusive with @option{whole_len}.
  563. @item whole_len
  564. Set the minimum total number of samples in the output audio stream. If
  565. the value is longer than the input audio length, silence is added to
  566. the end, until the value is reached. This option is mutually exclusive
  567. with @option{pad_len}.
  568. @end table
  569. If neither the @option{pad_len} nor the @option{whole_len} option is
  570. set, the filter will add silence to the end of the input stream
  571. indefinitely.
  572. @subsection Examples
  573. @itemize
  574. @item
  575. Add 1024 samples of silence to the end of the input:
  576. @example
  577. apad=pad_len=1024
  578. @end example
  579. @item
  580. Make sure the audio output will contain at least 10000 samples, pad
  581. the input with silence if required:
  582. @example
  583. apad=whole_len=10000
  584. @end example
  585. @item
  586. Use @command{ffmpeg} to pad the audio input with silence, so that the
  587. video stream will always result the shortest and will be converted
  588. until the end in the output file when using the @option{shortest}
  589. option:
  590. @example
  591. ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
  592. @end example
  593. @end itemize
  594. @section aphaser
  595. Add a phasing effect to the input audio.
  596. A phaser filter creates series of peaks and troughs in the frequency spectrum.
  597. The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
  598. A description of the accepted parameters follows.
  599. @table @option
  600. @item in_gain
  601. Set input gain. Default is 0.4.
  602. @item out_gain
  603. Set output gain. Default is 0.74
  604. @item delay
  605. Set delay in milliseconds. Default is 3.0.
  606. @item decay
  607. Set decay. Default is 0.4.
  608. @item speed
  609. Set modulation speed in Hz. Default is 0.5.
  610. @item type
  611. Set modulation type. Default is triangular.
  612. It accepts the following values:
  613. @table @samp
  614. @item triangular, t
  615. @item sinusoidal, s
  616. @end table
  617. @end table
  618. @anchor{aresample}
  619. @section aresample
  620. Resample the input audio to the specified parameters, using the
  621. libswresample library. If none are specified then the filter will
  622. automatically convert between its input and output.
  623. This filter is also able to stretch/squeeze the audio data to make it match
  624. the timestamps or to inject silence / cut out audio to make it match the
  625. timestamps, do a combination of both or do neither.
  626. The filter accepts the syntax
  627. [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
  628. expresses a sample rate and @var{resampler_options} is a list of
  629. @var{key}=@var{value} pairs, separated by ":". See the
  630. ffmpeg-resampler manual for the complete list of supported options.
  631. @subsection Examples
  632. @itemize
  633. @item
  634. Resample the input audio to 44100Hz:
  635. @example
  636. aresample=44100
  637. @end example
  638. @item
  639. Stretch/squeeze samples to the given timestamps, with a maximum of 1000
  640. samples per second compensation:
  641. @example
  642. aresample=async=1000
  643. @end example
  644. @end itemize
  645. @section asetnsamples
  646. Set the number of samples per each output audio frame.
  647. The last output packet may contain a different number of samples, as
  648. the filter will flush all the remaining samples when the input audio
  649. signal its end.
  650. The filter accepts the following options:
  651. @table @option
  652. @item nb_out_samples, n
  653. Set the number of frames per each output audio frame. The number is
  654. intended as the number of samples @emph{per each channel}.
  655. Default value is 1024.
  656. @item pad, p
  657. If set to 1, the filter will pad the last audio frame with zeroes, so
  658. that the last frame will contain the same number of samples as the
  659. previous ones. Default value is 1.
  660. @end table
  661. For example, to set the number of per-frame samples to 1234 and
  662. disable padding for the last frame, use:
  663. @example
  664. asetnsamples=n=1234:p=0
  665. @end example
  666. @section asetrate
  667. Set the sample rate without altering the PCM data.
  668. This will result in a change of speed and pitch.
  669. The filter accepts the following options:
  670. @table @option
  671. @item sample_rate, r
  672. Set the output sample rate. Default is 44100 Hz.
  673. @end table
  674. @section ashowinfo
  675. Show a line containing various information for each input audio frame.
  676. The input audio is not modified.
  677. The shown line contains a sequence of key/value pairs of the form
  678. @var{key}:@var{value}.
  679. The following values are shown in the output:
  680. @table @option
  681. @item n
  682. The (sequential) number of the input frame, starting from 0.
  683. @item pts
  684. The presentation timestamp of the input frame, in time base units; the time base
  685. depends on the filter input pad, and is usually 1/@var{sample_rate}.
  686. @item pts_time
  687. The presentation timestamp of the input frame in seconds.
  688. @item pos
  689. position of the frame in the input stream, -1 if this information in
  690. unavailable and/or meaningless (for example in case of synthetic audio)
  691. @item fmt
  692. The sample format.
  693. @item chlayout
  694. The channel layout.
  695. @item rate
  696. The sample rate for the audio frame.
  697. @item nb_samples
  698. The number of samples (per channel) in the frame.
  699. @item checksum
  700. The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
  701. audio, the data is treated as if all the planes were concatenated.
  702. @item plane_checksums
  703. A list of Adler-32 checksums for each data plane.
  704. @end table
  705. @anchor{astats}
  706. @section astats
  707. Display time domain statistical information about the audio channels.
  708. Statistics are calculated and displayed for each audio channel and,
  709. where applicable, an overall figure is also given.
  710. It accepts the following option:
  711. @table @option
  712. @item length
  713. Short window length in seconds, used for peak and trough RMS measurement.
  714. Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.1 - 10]}.
  715. @end table
  716. A description of each shown parameter follows:
  717. @table @option
  718. @item DC offset
  719. Mean amplitude displacement from zero.
  720. @item Min level
  721. Minimal sample level.
  722. @item Max level
  723. Maximal sample level.
  724. @item Peak level dB
  725. @item RMS level dB
  726. Standard peak and RMS level measured in dBFS.
  727. @item RMS peak dB
  728. @item RMS trough dB
  729. Peak and trough values for RMS level measured over a short window.
  730. @item Crest factor
  731. Standard ratio of peak to RMS level (note: not in dB).
  732. @item Flat factor
  733. Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
  734. (i.e. either @var{Min level} or @var{Max level}).
  735. @item Peak count
  736. Number of occasions (not the number of samples) that the signal attained either
  737. @var{Min level} or @var{Max level}.
  738. @end table
  739. @section astreamsync
  740. Forward two audio streams and control the order the buffers are forwarded.
  741. The filter accepts the following options:
  742. @table @option
  743. @item expr, e
  744. Set the expression deciding which stream should be
  745. forwarded next: if the result is negative, the first stream is forwarded; if
  746. the result is positive or zero, the second stream is forwarded. It can use
  747. the following variables:
  748. @table @var
  749. @item b1 b2
  750. number of buffers forwarded so far on each stream
  751. @item s1 s2
  752. number of samples forwarded so far on each stream
  753. @item t1 t2
  754. current timestamp of each stream
  755. @end table
  756. The default value is @code{t1-t2}, which means to always forward the stream
  757. that has a smaller timestamp.
  758. @end table
  759. @subsection Examples
  760. Stress-test @code{amerge} by randomly sending buffers on the wrong
  761. input, while avoiding too much of a desynchronization:
  762. @example
  763. amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
  764. [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
  765. [a2] [b2] amerge
  766. @end example
  767. @section asyncts
  768. Synchronize audio data with timestamps by squeezing/stretching it and/or
  769. dropping samples/adding silence when needed.
  770. This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
  771. It accepts the following parameters:
  772. @table @option
  773. @item compensate
  774. Enable stretching/squeezing the data to make it match the timestamps. Disabled
  775. by default. When disabled, time gaps are covered with silence.
  776. @item min_delta
  777. The minimum difference between timestamps and audio data (in seconds) to trigger
  778. adding/dropping samples. The default value is 0.1. If you get an imperfect
  779. sync with this filter, try setting this parameter to 0.
  780. @item max_comp
  781. The maximum compensation in samples per second. Only relevant with compensate=1.
  782. The default value is 500.
  783. @item first_pts
  784. Assume that the first PTS should be this value. The time base is 1 / sample
  785. rate. This allows for padding/trimming at the start of the stream. By default,
  786. no assumption is made about the first frame's expected PTS, so no padding or
  787. trimming is done. For example, this could be set to 0 to pad the beginning with
  788. silence if an audio stream starts after the video stream or to trim any samples
  789. with a negative PTS due to encoder delay.
  790. @end table
  791. @section atempo
  792. Adjust audio tempo.
  793. The filter accepts exactly one parameter, the audio tempo. If not
  794. specified then the filter will assume nominal 1.0 tempo. Tempo must
  795. be in the [0.5, 2.0] range.
  796. @subsection Examples
  797. @itemize
  798. @item
  799. Slow down audio to 80% tempo:
  800. @example
  801. atempo=0.8
  802. @end example
  803. @item
  804. To speed up audio to 125% tempo:
  805. @example
  806. atempo=1.25
  807. @end example
  808. @end itemize
  809. @section atrim
  810. Trim the input so that the output contains one continuous subpart of the input.
  811. It accepts the following parameters:
  812. @table @option
  813. @item start
  814. Timestamp (in seconds) of the start of the section to keep. I.e. the audio
  815. sample with the timestamp @var{start} will be the first sample in the output.
  816. @item end
  817. Specify time of the first audio sample that will be dropped, i.e. the
  818. audio sample immediately preceding the one with the timestamp @var{end} will be
  819. the last sample in the output.
  820. @item start_pts
  821. Same as @var{start}, except this option sets the start timestamp in samples
  822. instead of seconds.
  823. @item end_pts
  824. Same as @var{end}, except this option sets the end timestamp in samples instead
  825. of seconds.
  826. @item duration
  827. The maximum duration of the output in seconds.
  828. @item start_sample
  829. The number of the first sample that should be output.
  830. @item end_sample
  831. The number of the first sample that should be dropped.
  832. @end table
  833. @option{start}, @option{end}, and @option{duration} are expressed as time
  834. duration specifications; see
  835. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  836. Note that the first two sets of the start/end options and the @option{duration}
  837. option look at the frame timestamp, while the _sample options simply count the
  838. samples that pass through the filter. So start/end_pts and start/end_sample will
  839. give different results when the timestamps are wrong, inexact or do not start at
  840. zero. Also note that this filter does not modify the timestamps. If you wish
  841. to have the output timestamps start at zero, insert the asetpts filter after the
  842. atrim filter.
  843. If multiple start or end options are set, this filter tries to be greedy and
  844. keep all samples that match at least one of the specified constraints. To keep
  845. only the part that matches all the constraints at once, chain multiple atrim
  846. filters.
  847. The defaults are such that all the input is kept. So it is possible to set e.g.
  848. just the end values to keep everything before the specified time.
  849. Examples:
  850. @itemize
  851. @item
  852. Drop everything except the second minute of input:
  853. @example
  854. ffmpeg -i INPUT -af atrim=60:120
  855. @end example
  856. @item
  857. Keep only the first 1000 samples:
  858. @example
  859. ffmpeg -i INPUT -af atrim=end_sample=1000
  860. @end example
  861. @end itemize
  862. @section bandpass
  863. Apply a two-pole Butterworth band-pass filter with central
  864. frequency @var{frequency}, and (3dB-point) band-width width.
  865. The @var{csg} option selects a constant skirt gain (peak gain = Q)
  866. instead of the default: constant 0dB peak gain.
  867. The filter roll off at 6dB per octave (20dB per decade).
  868. The filter accepts the following options:
  869. @table @option
  870. @item frequency, f
  871. Set the filter's central frequency. Default is @code{3000}.
  872. @item csg
  873. Constant skirt gain if set to 1. Defaults to 0.
  874. @item width_type
  875. Set method to specify band-width of filter.
  876. @table @option
  877. @item h
  878. Hz
  879. @item q
  880. Q-Factor
  881. @item o
  882. octave
  883. @item s
  884. slope
  885. @end table
  886. @item width, w
  887. Specify the band-width of a filter in width_type units.
  888. @end table
  889. @section bandreject
  890. Apply a two-pole Butterworth band-reject filter with central
  891. frequency @var{frequency}, and (3dB-point) band-width @var{width}.
  892. The filter roll off at 6dB per octave (20dB per decade).
  893. The filter accepts the following options:
  894. @table @option
  895. @item frequency, f
  896. Set the filter's central frequency. Default is @code{3000}.
  897. @item width_type
  898. Set method to specify band-width of filter.
  899. @table @option
  900. @item h
  901. Hz
  902. @item q
  903. Q-Factor
  904. @item o
  905. octave
  906. @item s
  907. slope
  908. @end table
  909. @item width, w
  910. Specify the band-width of a filter in width_type units.
  911. @end table
  912. @section bass
  913. Boost or cut the bass (lower) frequencies of the audio using a two-pole
  914. shelving filter with a response similar to that of a standard
  915. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  916. The filter accepts the following options:
  917. @table @option
  918. @item gain, g
  919. Give the gain at 0 Hz. Its useful range is about -20
  920. (for a large cut) to +20 (for a large boost).
  921. Beware of clipping when using a positive gain.
  922. @item frequency, f
  923. Set the filter's central frequency and so can be used
  924. to extend or reduce the frequency range to be boosted or cut.
  925. The default value is @code{100} Hz.
  926. @item width_type
  927. Set method to specify band-width of filter.
  928. @table @option
  929. @item h
  930. Hz
  931. @item q
  932. Q-Factor
  933. @item o
  934. octave
  935. @item s
  936. slope
  937. @end table
  938. @item width, w
  939. Determine how steep is the filter's shelf transition.
  940. @end table
  941. @section biquad
  942. Apply a biquad IIR filter with the given coefficients.
  943. Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
  944. are the numerator and denominator coefficients respectively.
  945. @section bs2b
  946. Bauer stereo to binaural transformation, which improves headphone listening of
  947. stereo audio records.
  948. It accepts the following parameters:
  949. @table @option
  950. @item profile
  951. Pre-defined crossfeed level.
  952. @table @option
  953. @item default
  954. Default level (fcut=700, feed=50).
  955. @item cmoy
  956. Chu Moy circuit (fcut=700, feed=60).
  957. @item jmeier
  958. Jan Meier circuit (fcut=650, feed=95).
  959. @end table
  960. @item fcut
  961. Cut frequency (in Hz).
  962. @item feed
  963. Feed level (in Hz).
  964. @end table
  965. @section channelmap
  966. Remap input channels to new locations.
  967. It accepts the following parameters:
  968. @table @option
  969. @item channel_layout
  970. The channel layout of the output stream.
  971. @item map
  972. Map channels from input to output. The argument is a '|'-separated list of
  973. mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
  974. @var{in_channel} form. @var{in_channel} can be either the name of the input
  975. channel (e.g. FL for front left) or its index in the input channel layout.
  976. @var{out_channel} is the name of the output channel or its index in the output
  977. channel layout. If @var{out_channel} is not given then it is implicitly an
  978. index, starting with zero and increasing by one for each mapping.
  979. @end table
  980. If no mapping is present, the filter will implicitly map input channels to
  981. output channels, preserving indices.
  982. For example, assuming a 5.1+downmix input MOV file,
  983. @example
  984. ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
  985. @end example
  986. will create an output WAV file tagged as stereo from the downmix channels of
  987. the input.
  988. To fix a 5.1 WAV improperly encoded in AAC's native channel order
  989. @example
  990. ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
  991. @end example
  992. @section channelsplit
  993. Split each channel from an input audio stream into a separate output stream.
  994. It accepts the following parameters:
  995. @table @option
  996. @item channel_layout
  997. The channel layout of the input stream. The default is "stereo".
  998. @end table
  999. For example, assuming a stereo input MP3 file,
  1000. @example
  1001. ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
  1002. @end example
  1003. will create an output Matroska file with two audio streams, one containing only
  1004. the left channel and the other the right channel.
  1005. Split a 5.1 WAV file into per-channel files:
  1006. @example
  1007. ffmpeg -i in.wav -filter_complex
  1008. 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
  1009. -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
  1010. front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
  1011. side_right.wav
  1012. @end example
  1013. @section compand
  1014. Compress or expand the audio's dynamic range.
  1015. It accepts the following parameters:
  1016. @table @option
  1017. @item attacks
  1018. @item decays
  1019. A list of times in seconds for each channel over which the instantaneous level
  1020. of the input signal is averaged to determine its volume. @var{attacks} refers to
  1021. increase of volume and @var{decays} refers to decrease of volume. For most
  1022. situations, the attack time (response to the audio getting louder) should be
  1023. shorter than the decay time, because the human ear is more sensitive to sudden
  1024. loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
  1025. a typical value for decay is 0.8 seconds.
  1026. @item points
  1027. A list of points for the transfer function, specified in dB relative to the
  1028. maximum possible signal amplitude. Each key points list must be defined using
  1029. the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
  1030. @code{x0/y0 x1/y1 x2/y2 ....}
  1031. The input values must be in strictly increasing order but the transfer function
  1032. does not have to be monotonically rising. The point @code{0/0} is assumed but
  1033. may be overridden (by @code{0/out-dBn}). Typical values for the transfer
  1034. function are @code{-70/-70|-60/-20}.
  1035. @item soft-knee
  1036. Set the curve radius in dB for all joints. It defaults to 0.01.
  1037. @item gain
  1038. Set the additional gain in dB to be applied at all points on the transfer
  1039. function. This allows for easy adjustment of the overall gain.
  1040. It defaults to 0.
  1041. @item volume
  1042. Set an initial volume, in dB, to be assumed for each channel when filtering
  1043. starts. This permits the user to supply a nominal level initially, so that, for
  1044. example, a very large gain is not applied to initial signal levels before the
  1045. companding has begun to operate. A typical value for audio which is initially
  1046. quiet is -90 dB. It defaults to 0.
  1047. @item delay
  1048. Set a delay, in seconds. The input audio is analyzed immediately, but audio is
  1049. delayed before being fed to the volume adjuster. Specifying a delay
  1050. approximately equal to the attack/decay times allows the filter to effectively
  1051. operate in predictive rather than reactive mode. It defaults to 0.
  1052. @end table
  1053. @subsection Examples
  1054. @itemize
  1055. @item
  1056. Make music with both quiet and loud passages suitable for listening to in a
  1057. noisy environment:
  1058. @example
  1059. compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
  1060. @end example
  1061. @item
  1062. A noise gate for when the noise is at a lower level than the signal:
  1063. @example
  1064. compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
  1065. @end example
  1066. @item
  1067. Here is another noise gate, this time for when the noise is at a higher level
  1068. than the signal (making it, in some ways, similar to squelch):
  1069. @example
  1070. compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
  1071. @end example
  1072. @end itemize
  1073. @section dcshift
  1074. Apply a DC shift to the audio.
  1075. This can be useful to remove a DC offset (caused perhaps by a hardware problem
  1076. in the recording chain) from the audio. The effect of a DC offset is reduced
  1077. headroom and hence volume. The @ref{astats} filter can be used to determine if
  1078. a signal has a DC offset.
  1079. @table @option
  1080. @item shift
  1081. Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
  1082. the audio.
  1083. @item limitergain
  1084. Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
  1085. used to prevent clipping.
  1086. @end table
  1087. @section earwax
  1088. Make audio easier to listen to on headphones.
  1089. This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
  1090. so that when listened to on headphones the stereo image is moved from
  1091. inside your head (standard for headphones) to outside and in front of
  1092. the listener (standard for speakers).
  1093. Ported from SoX.
  1094. @section equalizer
  1095. Apply a two-pole peaking equalisation (EQ) filter. With this
  1096. filter, the signal-level at and around a selected frequency can
  1097. be increased or decreased, whilst (unlike bandpass and bandreject
  1098. filters) that at all other frequencies is unchanged.
  1099. In order to produce complex equalisation curves, this filter can
  1100. be given several times, each with a different central frequency.
  1101. The filter accepts the following options:
  1102. @table @option
  1103. @item frequency, f
  1104. Set the filter's central frequency in Hz.
  1105. @item width_type
  1106. Set method to specify band-width of filter.
  1107. @table @option
  1108. @item h
  1109. Hz
  1110. @item q
  1111. Q-Factor
  1112. @item o
  1113. octave
  1114. @item s
  1115. slope
  1116. @end table
  1117. @item width, w
  1118. Specify the band-width of a filter in width_type units.
  1119. @item gain, g
  1120. Set the required gain or attenuation in dB.
  1121. Beware of clipping when using a positive gain.
  1122. @end table
  1123. @subsection Examples
  1124. @itemize
  1125. @item
  1126. Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
  1127. @example
  1128. equalizer=f=1000:width_type=h:width=200:g=-10
  1129. @end example
  1130. @item
  1131. Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
  1132. @example
  1133. equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5
  1134. @end example
  1135. @end itemize
  1136. @section flanger
  1137. Apply a flanging effect to the audio.
  1138. The filter accepts the following options:
  1139. @table @option
  1140. @item delay
  1141. Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
  1142. @item depth
  1143. Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2.
  1144. @item regen
  1145. Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
  1146. Default value is 0.
  1147. @item width
  1148. Set percentage of delayed signal mixed with original. Range from 0 to 100.
  1149. Default value is 71.
  1150. @item speed
  1151. Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
  1152. @item shape
  1153. Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
  1154. Default value is @var{sinusoidal}.
  1155. @item phase
  1156. Set swept wave percentage-shift for multi channel. Range from 0 to 100.
  1157. Default value is 25.
  1158. @item interp
  1159. Set delay-line interpolation, @var{linear} or @var{quadratic}.
  1160. Default is @var{linear}.
  1161. @end table
  1162. @section highpass
  1163. Apply a high-pass filter with 3dB point frequency.
  1164. The filter can be either single-pole, or double-pole (the default).
  1165. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  1166. The filter accepts the following options:
  1167. @table @option
  1168. @item frequency, f
  1169. Set frequency in Hz. Default is 3000.
  1170. @item poles, p
  1171. Set number of poles. Default is 2.
  1172. @item width_type
  1173. Set method to specify band-width of filter.
  1174. @table @option
  1175. @item h
  1176. Hz
  1177. @item q
  1178. Q-Factor
  1179. @item o
  1180. octave
  1181. @item s
  1182. slope
  1183. @end table
  1184. @item width, w
  1185. Specify the band-width of a filter in width_type units.
  1186. Applies only to double-pole filter.
  1187. The default is 0.707q and gives a Butterworth response.
  1188. @end table
  1189. @section join
  1190. Join multiple input streams into one multi-channel stream.
  1191. It accepts the following parameters:
  1192. @table @option
  1193. @item inputs
  1194. The number of input streams. It defaults to 2.
  1195. @item channel_layout
  1196. The desired output channel layout. It defaults to stereo.
  1197. @item map
  1198. Map channels from inputs to output. The argument is a '|'-separated list of
  1199. mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
  1200. form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
  1201. can be either the name of the input channel (e.g. FL for front left) or its
  1202. index in the specified input stream. @var{out_channel} is the name of the output
  1203. channel.
  1204. @end table
  1205. The filter will attempt to guess the mappings when they are not specified
  1206. explicitly. It does so by first trying to find an unused matching input channel
  1207. and if that fails it picks the first unused input channel.
  1208. Join 3 inputs (with properly set channel layouts):
  1209. @example
  1210. ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
  1211. @end example
  1212. Build a 5.1 output from 6 single-channel streams:
  1213. @example
  1214. ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
  1215. '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'
  1216. out
  1217. @end example
  1218. @section ladspa
  1219. Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
  1220. To enable compilation of this filter you need to configure FFmpeg with
  1221. @code{--enable-ladspa}.
  1222. @table @option
  1223. @item file, f
  1224. Specifies the name of LADSPA plugin library to load. If the environment
  1225. variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
  1226. each one of the directories specified by the colon separated list in
  1227. @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
  1228. this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
  1229. @file{/usr/lib/ladspa/}.
  1230. @item plugin, p
  1231. Specifies the plugin within the library. Some libraries contain only
  1232. one plugin, but others contain many of them. If this is not set filter
  1233. will list all available plugins within the specified library.
  1234. @item controls, c
  1235. Set the '|' separated list of controls which are zero or more floating point
  1236. values that determine the behavior of the loaded plugin (for example delay,
  1237. threshold or gain).
  1238. Controls need to be defined using the following syntax:
  1239. c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
  1240. @var{valuei} is the value set on the @var{i}-th control.
  1241. If @option{controls} is set to @code{help}, all available controls and
  1242. their valid ranges are printed.
  1243. @item sample_rate, s
  1244. Specify the sample rate, default to 44100. Only used if plugin have
  1245. zero inputs.
  1246. @item nb_samples, n
  1247. Set the number of samples per channel per each output frame, default
  1248. is 1024. Only used if plugin have zero inputs.
  1249. @item duration, d
  1250. Set the minimum duration of the sourced audio. See
  1251. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  1252. for the accepted syntax.
  1253. Note that the resulting duration may be greater than the specified duration,
  1254. as the generated audio is always cut at the end of a complete frame.
  1255. If not specified, or the expressed duration is negative, the audio is
  1256. supposed to be generated forever.
  1257. Only used if plugin have zero inputs.
  1258. @end table
  1259. @subsection Examples
  1260. @itemize
  1261. @item
  1262. List all available plugins within amp (LADSPA example plugin) library:
  1263. @example
  1264. ladspa=file=amp
  1265. @end example
  1266. @item
  1267. List all available controls and their valid ranges for @code{vcf_notch}
  1268. plugin from @code{VCF} library:
  1269. @example
  1270. ladspa=f=vcf:p=vcf_notch:c=help
  1271. @end example
  1272. @item
  1273. Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
  1274. plugin library:
  1275. @example
  1276. ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
  1277. @end example
  1278. @item
  1279. Add reverberation to the audio using TAP-plugins
  1280. (Tom's Audio Processing plugins):
  1281. @example
  1282. ladspa=file=tap_reverb:tap_reverb
  1283. @end example
  1284. @item
  1285. Generate white noise, with 0.2 amplitude:
  1286. @example
  1287. ladspa=file=cmt:noise_source_white:c=c0=.2
  1288. @end example
  1289. @item
  1290. Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
  1291. @code{C* Audio Plugin Suite} (CAPS) library:
  1292. @example
  1293. ladspa=file=caps:Click:c=c1=20'
  1294. @end example
  1295. @item
  1296. Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
  1297. @example
  1298. ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
  1299. @end example
  1300. @end itemize
  1301. @subsection Commands
  1302. This filter supports the following commands:
  1303. @table @option
  1304. @item cN
  1305. Modify the @var{N}-th control value.
  1306. If the specified value is not valid, it is ignored and prior one is kept.
  1307. @end table
  1308. @section lowpass
  1309. Apply a low-pass filter with 3dB point frequency.
  1310. The filter can be either single-pole or double-pole (the default).
  1311. The filter roll off at 6dB per pole per octave (20dB per pole per decade).
  1312. The filter accepts the following options:
  1313. @table @option
  1314. @item frequency, f
  1315. Set frequency in Hz. Default is 500.
  1316. @item poles, p
  1317. Set number of poles. Default is 2.
  1318. @item width_type
  1319. Set method to specify band-width of filter.
  1320. @table @option
  1321. @item h
  1322. Hz
  1323. @item q
  1324. Q-Factor
  1325. @item o
  1326. octave
  1327. @item s
  1328. slope
  1329. @end table
  1330. @item width, w
  1331. Specify the band-width of a filter in width_type units.
  1332. Applies only to double-pole filter.
  1333. The default is 0.707q and gives a Butterworth response.
  1334. @end table
  1335. @section pan
  1336. Mix channels with specific gain levels. The filter accepts the output
  1337. channel layout followed by a set of channels definitions.
  1338. This filter is also designed to efficiently remap the channels of an audio
  1339. stream.
  1340. The filter accepts parameters of the form:
  1341. "@var{l}|@var{outdef}|@var{outdef}|..."
  1342. @table @option
  1343. @item l
  1344. output channel layout or number of channels
  1345. @item outdef
  1346. output channel specification, of the form:
  1347. "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
  1348. @item out_name
  1349. output channel to define, either a channel name (FL, FR, etc.) or a channel
  1350. number (c0, c1, etc.)
  1351. @item gain
  1352. multiplicative coefficient for the channel, 1 leaving the volume unchanged
  1353. @item in_name
  1354. input channel to use, see out_name for details; it is not possible to mix
  1355. named and numbered input channels
  1356. @end table
  1357. If the `=' in a channel specification is replaced by `<', then the gains for
  1358. that specification will be renormalized so that the total is 1, thus
  1359. avoiding clipping noise.
  1360. @subsection Mixing examples
  1361. For example, if you want to down-mix from stereo to mono, but with a bigger
  1362. factor for the left channel:
  1363. @example
  1364. pan=1c|c0=0.9*c0+0.1*c1
  1365. @end example
  1366. A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
  1367. 7-channels surround:
  1368. @example
  1369. pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
  1370. @end example
  1371. Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
  1372. that should be preferred (see "-ac" option) unless you have very specific
  1373. needs.
  1374. @subsection Remapping examples
  1375. The channel remapping will be effective if, and only if:
  1376. @itemize
  1377. @item gain coefficients are zeroes or ones,
  1378. @item only one input per channel output,
  1379. @end itemize
  1380. If all these conditions are satisfied, the filter will notify the user ("Pure
  1381. channel mapping detected"), and use an optimized and lossless method to do the
  1382. remapping.
  1383. For example, if you have a 5.1 source and want a stereo audio stream by
  1384. dropping the extra channels:
  1385. @example
  1386. pan="stereo| c0=FL | c1=FR"
  1387. @end example
  1388. Given the same source, you can also switch front left and front right channels
  1389. and keep the input channel layout:
  1390. @example
  1391. pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
  1392. @end example
  1393. If the input is a stereo audio stream, you can mute the front left channel (and
  1394. still keep the stereo channel layout) with:
  1395. @example
  1396. pan="stereo|c1=c1"
  1397. @end example
  1398. Still with a stereo audio stream input, you can copy the right channel in both
  1399. front left and right:
  1400. @example
  1401. pan="stereo| c0=FR | c1=FR"
  1402. @end example
  1403. @section replaygain
  1404. ReplayGain scanner filter. This filter takes an audio stream as an input and
  1405. outputs it unchanged.
  1406. At end of filtering it displays @code{track_gain} and @code{track_peak}.
  1407. @section resample
  1408. Convert the audio sample format, sample rate and channel layout. It is
  1409. not meant to be used directly.
  1410. @section silencedetect
  1411. Detect silence in an audio stream.
  1412. This filter logs a message when it detects that the input audio volume is less
  1413. or equal to a noise tolerance value for a duration greater or equal to the
  1414. minimum detected noise duration.
  1415. The printed times and duration are expressed in seconds.
  1416. The filter accepts the following options:
  1417. @table @option
  1418. @item duration, d
  1419. Set silence duration until notification (default is 2 seconds).
  1420. @item noise, n
  1421. Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
  1422. specified value) or amplitude ratio. Default is -60dB, or 0.001.
  1423. @end table
  1424. @subsection Examples
  1425. @itemize
  1426. @item
  1427. Detect 5 seconds of silence with -50dB noise tolerance:
  1428. @example
  1429. silencedetect=n=-50dB:d=5
  1430. @end example
  1431. @item
  1432. Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
  1433. tolerance in @file{silence.mp3}:
  1434. @example
  1435. ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
  1436. @end example
  1437. @end itemize
  1438. @section silenceremove
  1439. Remove silence from the beginning, middle or end of the audio.
  1440. The filter accepts the following options:
  1441. @table @option
  1442. @item start_periods
  1443. This value is used to indicate if audio should be trimmed at beginning of
  1444. the audio. A value of zero indicates no silence should be trimmed from the
  1445. beginning. When specifying a non-zero value, it trims audio up until it
  1446. finds non-silence. Normally, when trimming silence from beginning of audio
  1447. the @var{start_periods} will be @code{1} but it can be increased to higher
  1448. values to trim all audio up to specific count of non-silence periods.
  1449. Default value is @code{0}.
  1450. @item start_duration
  1451. Specify the amount of time that non-silence must be detected before it stops
  1452. trimming audio. By increasing the duration, bursts of noises can be treated
  1453. as silence and trimmed off. Default value is @code{0}.
  1454. @item start_threshold
  1455. This indicates what sample value should be treated as silence. For digital
  1456. audio, a value of @code{0} may be fine but for audio recorded from analog,
  1457. you may wish to increase the value to account for background noise.
  1458. Can be specified in dB (in case "dB" is appended to the specified value)
  1459. or amplitude ratio. Default value is @code{0}.
  1460. @item stop_periods
  1461. Set the count for trimming silence from the end of audio.
  1462. To remove silence from the middle of a file, specify a @var{stop_periods}
  1463. that is negative. This value is then treated as a positive value and is
  1464. used to indicate the effect should restart processing as specified by
  1465. @var{start_periods}, making it suitable for removing periods of silence
  1466. in the middle of the audio.
  1467. Default value is @code{0}.
  1468. @item stop_duration
  1469. Specify a duration of silence that must exist before audio is not copied any
  1470. more. By specifying a higher duration, silence that is wanted can be left in
  1471. the audio.
  1472. Default value is @code{0}.
  1473. @item stop_threshold
  1474. This is the same as @option{start_threshold} but for trimming silence from
  1475. the end of audio.
  1476. Can be specified in dB (in case "dB" is appended to the specified value)
  1477. or amplitude ratio. Default value is @code{0}.
  1478. @item leave_silence
  1479. This indicate that @var{stop_duration} length of audio should be left intact
  1480. at the beginning of each period of silence.
  1481. For example, if you want to remove long pauses between words but do not want
  1482. to remove the pauses completely. Default value is @code{0}.
  1483. @end table
  1484. @subsection Examples
  1485. @itemize
  1486. @item
  1487. The following example shows how this filter can be used to start a recording
  1488. that does not contain the delay at the start which usually occurs between
  1489. pressing the record button and the start of the performance:
  1490. @example
  1491. silenceremove=1:5:0.02
  1492. @end example
  1493. @end itemize
  1494. @section treble
  1495. Boost or cut treble (upper) frequencies of the audio using a two-pole
  1496. shelving filter with a response similar to that of a standard
  1497. hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
  1498. The filter accepts the following options:
  1499. @table @option
  1500. @item gain, g
  1501. Give the gain at whichever is the lower of ~22 kHz and the
  1502. Nyquist frequency. Its useful range is about -20 (for a large cut)
  1503. to +20 (for a large boost). Beware of clipping when using a positive gain.
  1504. @item frequency, f
  1505. Set the filter's central frequency and so can be used
  1506. to extend or reduce the frequency range to be boosted or cut.
  1507. The default value is @code{3000} Hz.
  1508. @item width_type
  1509. Set method to specify band-width of filter.
  1510. @table @option
  1511. @item h
  1512. Hz
  1513. @item q
  1514. Q-Factor
  1515. @item o
  1516. octave
  1517. @item s
  1518. slope
  1519. @end table
  1520. @item width, w
  1521. Determine how steep is the filter's shelf transition.
  1522. @end table
  1523. @section volume
  1524. Adjust the input audio volume.
  1525. It accepts the following parameters:
  1526. @table @option
  1527. @item volume
  1528. Set audio volume expression.
  1529. Output values are clipped to the maximum value.
  1530. The output audio volume is given by the relation:
  1531. @example
  1532. @var{output_volume} = @var{volume} * @var{input_volume}
  1533. @end example
  1534. The default value for @var{volume} is "1.0".
  1535. @item precision
  1536. This parameter represents the mathematical precision.
  1537. It determines which input sample formats will be allowed, which affects the
  1538. precision of the volume scaling.
  1539. @table @option
  1540. @item fixed
  1541. 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
  1542. @item float
  1543. 32-bit floating-point; this limits input sample format to FLT. (default)
  1544. @item double
  1545. 64-bit floating-point; this limits input sample format to DBL.
  1546. @end table
  1547. @item replaygain
  1548. Choose the behaviour on encountering ReplayGain side data in input frames.
  1549. @table @option
  1550. @item drop
  1551. Remove ReplayGain side data, ignoring its contents (the default).
  1552. @item ignore
  1553. Ignore ReplayGain side data, but leave it in the frame.
  1554. @item track
  1555. Prefer the track gain, if present.
  1556. @item album
  1557. Prefer the album gain, if present.
  1558. @end table
  1559. @item replaygain_preamp
  1560. Pre-amplification gain in dB to apply to the selected replaygain gain.
  1561. Default value for @var{replaygain_preamp} is 0.0.
  1562. @item eval
  1563. Set when the volume expression is evaluated.
  1564. It accepts the following values:
  1565. @table @samp
  1566. @item once
  1567. only evaluate expression once during the filter initialization, or
  1568. when the @samp{volume} command is sent
  1569. @item frame
  1570. evaluate expression for each incoming frame
  1571. @end table
  1572. Default value is @samp{once}.
  1573. @end table
  1574. The volume expression can contain the following parameters.
  1575. @table @option
  1576. @item n
  1577. frame number (starting at zero)
  1578. @item nb_channels
  1579. number of channels
  1580. @item nb_consumed_samples
  1581. number of samples consumed by the filter
  1582. @item nb_samples
  1583. number of samples in the current frame
  1584. @item pos
  1585. original frame position in the file
  1586. @item pts
  1587. frame PTS
  1588. @item sample_rate
  1589. sample rate
  1590. @item startpts
  1591. PTS at start of stream
  1592. @item startt
  1593. time at start of stream
  1594. @item t
  1595. frame time
  1596. @item tb
  1597. timestamp timebase
  1598. @item volume
  1599. last set volume value
  1600. @end table
  1601. Note that when @option{eval} is set to @samp{once} only the
  1602. @var{sample_rate} and @var{tb} variables are available, all other
  1603. variables will evaluate to NAN.
  1604. @subsection Commands
  1605. This filter supports the following commands:
  1606. @table @option
  1607. @item volume
  1608. Modify the volume expression.
  1609. The command accepts the same syntax of the corresponding option.
  1610. If the specified expression is not valid, it is kept at its current
  1611. value.
  1612. @item replaygain_noclip
  1613. Prevent clipping by limiting the gain applied.
  1614. Default value for @var{replaygain_noclip} is 1.
  1615. @end table
  1616. @subsection Examples
  1617. @itemize
  1618. @item
  1619. Halve the input audio volume:
  1620. @example
  1621. volume=volume=0.5
  1622. volume=volume=1/2
  1623. volume=volume=-6.0206dB
  1624. @end example
  1625. In all the above example the named key for @option{volume} can be
  1626. omitted, for example like in:
  1627. @example
  1628. volume=0.5
  1629. @end example
  1630. @item
  1631. Increase input audio power by 6 decibels using fixed-point precision:
  1632. @example
  1633. volume=volume=6dB:precision=fixed
  1634. @end example
  1635. @item
  1636. Fade volume after time 10 with an annihilation period of 5 seconds:
  1637. @example
  1638. volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
  1639. @end example
  1640. @end itemize
  1641. @section volumedetect
  1642. Detect the volume of the input video.
  1643. The filter has no parameters. The input is not modified. Statistics about
  1644. the volume will be printed in the log when the input stream end is reached.
  1645. In particular it will show the mean volume (root mean square), maximum
  1646. volume (on a per-sample basis), and the beginning of a histogram of the
  1647. registered volume values (from the maximum value to a cumulated 1/1000 of
  1648. the samples).
  1649. All volumes are in decibels relative to the maximum PCM value.
  1650. @subsection Examples
  1651. Here is an excerpt of the output:
  1652. @example
  1653. [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
  1654. [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
  1655. [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
  1656. [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
  1657. [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
  1658. [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
  1659. [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
  1660. [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
  1661. [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
  1662. @end example
  1663. It means that:
  1664. @itemize
  1665. @item
  1666. The mean square energy is approximately -27 dB, or 10^-2.7.
  1667. @item
  1668. The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
  1669. @item
  1670. There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
  1671. @end itemize
  1672. In other words, raising the volume by +4 dB does not cause any clipping,
  1673. raising it by +5 dB causes clipping for 6 samples, etc.
  1674. @c man end AUDIO FILTERS
  1675. @chapter Audio Sources
  1676. @c man begin AUDIO SOURCES
  1677. Below is a description of the currently available audio sources.
  1678. @section abuffer
  1679. Buffer audio frames, and make them available to the filter chain.
  1680. This source is mainly intended for a programmatic use, in particular
  1681. through the interface defined in @file{libavfilter/asrc_abuffer.h}.
  1682. It accepts the following parameters:
  1683. @table @option
  1684. @item time_base
  1685. The timebase which will be used for timestamps of submitted frames. It must be
  1686. either a floating-point number or in @var{numerator}/@var{denominator} form.
  1687. @item sample_rate
  1688. The sample rate of the incoming audio buffers.
  1689. @item sample_fmt
  1690. The sample format of the incoming audio buffers.
  1691. Either a sample format name or its corresponding integer representation from
  1692. the enum AVSampleFormat in @file{libavutil/samplefmt.h}
  1693. @item channel_layout
  1694. The channel layout of the incoming audio buffers.
  1695. Either a channel layout name from channel_layout_map in
  1696. @file{libavutil/channel_layout.c} or its corresponding integer representation
  1697. from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
  1698. @item channels
  1699. The number of channels of the incoming audio buffers.
  1700. If both @var{channels} and @var{channel_layout} are specified, then they
  1701. must be consistent.
  1702. @end table
  1703. @subsection Examples
  1704. @example
  1705. abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
  1706. @end example
  1707. will instruct the source to accept planar 16bit signed stereo at 44100Hz.
  1708. Since the sample format with name "s16p" corresponds to the number
  1709. 6 and the "stereo" channel layout corresponds to the value 0x3, this is
  1710. equivalent to:
  1711. @example
  1712. abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
  1713. @end example
  1714. @section aevalsrc
  1715. Generate an audio signal specified by an expression.
  1716. This source accepts in input one or more expressions (one for each
  1717. channel), which are evaluated and used to generate a corresponding
  1718. audio signal.
  1719. This source accepts the following options:
  1720. @table @option
  1721. @item exprs
  1722. Set the '|'-separated expressions list for each separate channel. In case the
  1723. @option{channel_layout} option is not specified, the selected channel layout
  1724. depends on the number of provided expressions. Otherwise the last
  1725. specified expression is applied to the remaining output channels.
  1726. @item channel_layout, c
  1727. Set the channel layout. The number of channels in the specified layout
  1728. must be equal to the number of specified expressions.
  1729. @item duration, d
  1730. Set the minimum duration of the sourced audio. See
  1731. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  1732. for the accepted syntax.
  1733. Note that the resulting duration may be greater than the specified
  1734. duration, as the generated audio is always cut at the end of a
  1735. complete frame.
  1736. If not specified, or the expressed duration is negative, the audio is
  1737. supposed to be generated forever.
  1738. @item nb_samples, n
  1739. Set the number of samples per channel per each output frame,
  1740. default to 1024.
  1741. @item sample_rate, s
  1742. Specify the sample rate, default to 44100.
  1743. @end table
  1744. Each expression in @var{exprs} can contain the following constants:
  1745. @table @option
  1746. @item n
  1747. number of the evaluated sample, starting from 0
  1748. @item t
  1749. time of the evaluated sample expressed in seconds, starting from 0
  1750. @item s
  1751. sample rate
  1752. @end table
  1753. @subsection Examples
  1754. @itemize
  1755. @item
  1756. Generate silence:
  1757. @example
  1758. aevalsrc=0
  1759. @end example
  1760. @item
  1761. Generate a sin signal with frequency of 440 Hz, set sample rate to
  1762. 8000 Hz:
  1763. @example
  1764. aevalsrc="sin(440*2*PI*t):s=8000"
  1765. @end example
  1766. @item
  1767. Generate a two channels signal, specify the channel layout (Front
  1768. Center + Back Center) explicitly:
  1769. @example
  1770. aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
  1771. @end example
  1772. @item
  1773. Generate white noise:
  1774. @example
  1775. aevalsrc="-2+random(0)"
  1776. @end example
  1777. @item
  1778. Generate an amplitude modulated signal:
  1779. @example
  1780. aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
  1781. @end example
  1782. @item
  1783. Generate 2.5 Hz binaural beats on a 360 Hz carrier:
  1784. @example
  1785. aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
  1786. @end example
  1787. @end itemize
  1788. @section anullsrc
  1789. The null audio source, return unprocessed audio frames. It is mainly useful
  1790. as a template and to be employed in analysis / debugging tools, or as
  1791. the source for filters which ignore the input data (for example the sox
  1792. synth filter).
  1793. This source accepts the following options:
  1794. @table @option
  1795. @item channel_layout, cl
  1796. Specifies the channel layout, and can be either an integer or a string
  1797. representing a channel layout. The default value of @var{channel_layout}
  1798. is "stereo".
  1799. Check the channel_layout_map definition in
  1800. @file{libavutil/channel_layout.c} for the mapping between strings and
  1801. channel layout values.
  1802. @item sample_rate, r
  1803. Specifies the sample rate, and defaults to 44100.
  1804. @item nb_samples, n
  1805. Set the number of samples per requested frames.
  1806. @end table
  1807. @subsection Examples
  1808. @itemize
  1809. @item
  1810. Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
  1811. @example
  1812. anullsrc=r=48000:cl=4
  1813. @end example
  1814. @item
  1815. Do the same operation with a more obvious syntax:
  1816. @example
  1817. anullsrc=r=48000:cl=mono
  1818. @end example
  1819. @end itemize
  1820. All the parameters need to be explicitly defined.
  1821. @section flite
  1822. Synthesize a voice utterance using the libflite library.
  1823. To enable compilation of this filter you need to configure FFmpeg with
  1824. @code{--enable-libflite}.
  1825. Note that the flite library is not thread-safe.
  1826. The filter accepts the following options:
  1827. @table @option
  1828. @item list_voices
  1829. If set to 1, list the names of the available voices and exit
  1830. immediately. Default value is 0.
  1831. @item nb_samples, n
  1832. Set the maximum number of samples per frame. Default value is 512.
  1833. @item textfile
  1834. Set the filename containing the text to speak.
  1835. @item text
  1836. Set the text to speak.
  1837. @item voice, v
  1838. Set the voice to use for the speech synthesis. Default value is
  1839. @code{kal}. See also the @var{list_voices} option.
  1840. @end table
  1841. @subsection Examples
  1842. @itemize
  1843. @item
  1844. Read from file @file{speech.txt}, and synthesize the text using the
  1845. standard flite voice:
  1846. @example
  1847. flite=textfile=speech.txt
  1848. @end example
  1849. @item
  1850. Read the specified text selecting the @code{slt} voice:
  1851. @example
  1852. flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  1853. @end example
  1854. @item
  1855. Input text to ffmpeg:
  1856. @example
  1857. ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
  1858. @end example
  1859. @item
  1860. Make @file{ffplay} speak the specified text, using @code{flite} and
  1861. the @code{lavfi} device:
  1862. @example
  1863. ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
  1864. @end example
  1865. @end itemize
  1866. For more information about libflite, check:
  1867. @url{http://www.speech.cs.cmu.edu/flite/}
  1868. @section sine
  1869. Generate an audio signal made of a sine wave with amplitude 1/8.
  1870. The audio signal is bit-exact.
  1871. The filter accepts the following options:
  1872. @table @option
  1873. @item frequency, f
  1874. Set the carrier frequency. Default is 440 Hz.
  1875. @item beep_factor, b
  1876. Enable a periodic beep every second with frequency @var{beep_factor} times
  1877. the carrier frequency. Default is 0, meaning the beep is disabled.
  1878. @item sample_rate, r
  1879. Specify the sample rate, default is 44100.
  1880. @item duration, d
  1881. Specify the duration of the generated audio stream.
  1882. @item samples_per_frame
  1883. Set the number of samples per output frame, default is 1024.
  1884. @end table
  1885. @subsection Examples
  1886. @itemize
  1887. @item
  1888. Generate a simple 440 Hz sine wave:
  1889. @example
  1890. sine
  1891. @end example
  1892. @item
  1893. Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
  1894. @example
  1895. sine=220:4:d=5
  1896. sine=f=220:b=4:d=5
  1897. sine=frequency=220:beep_factor=4:duration=5
  1898. @end example
  1899. @end itemize
  1900. @c man end AUDIO SOURCES
  1901. @chapter Audio Sinks
  1902. @c man begin AUDIO SINKS
  1903. Below is a description of the currently available audio sinks.
  1904. @section abuffersink
  1905. Buffer audio frames, and make them available to the end of filter chain.
  1906. This sink is mainly intended for programmatic use, in particular
  1907. through the interface defined in @file{libavfilter/buffersink.h}
  1908. or the options system.
  1909. It accepts a pointer to an AVABufferSinkContext structure, which
  1910. defines the incoming buffers' formats, to be passed as the opaque
  1911. parameter to @code{avfilter_init_filter} for initialization.
  1912. @section anullsink
  1913. Null audio sink; do absolutely nothing with the input audio. It is
  1914. mainly useful as a template and for use in analysis / debugging
  1915. tools.
  1916. @c man end AUDIO SINKS
  1917. @chapter Video Filters
  1918. @c man begin VIDEO FILTERS
  1919. When you configure your FFmpeg build, you can disable any of the
  1920. existing filters using @code{--disable-filters}.
  1921. The configure output will show the video filters included in your
  1922. build.
  1923. Below is a description of the currently available video filters.
  1924. @section alphaextract
  1925. Extract the alpha component from the input as a grayscale video. This
  1926. is especially useful with the @var{alphamerge} filter.
  1927. @section alphamerge
  1928. Add or replace the alpha component of the primary input with the
  1929. grayscale value of a second input. This is intended for use with
  1930. @var{alphaextract} to allow the transmission or storage of frame
  1931. sequences that have alpha in a format that doesn't support an alpha
  1932. channel.
  1933. For example, to reconstruct full frames from a normal YUV-encoded video
  1934. and a separate video created with @var{alphaextract}, you might use:
  1935. @example
  1936. movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
  1937. @end example
  1938. Since this filter is designed for reconstruction, it operates on frame
  1939. sequences without considering timestamps, and terminates when either
  1940. input reaches end of stream. This will cause problems if your encoding
  1941. pipeline drops frames. If you're trying to apply an image as an
  1942. overlay to a video stream, consider the @var{overlay} filter instead.
  1943. @section ass
  1944. Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
  1945. and libavformat to work. On the other hand, it is limited to ASS (Advanced
  1946. Substation Alpha) subtitles files.
  1947. This filter accepts the following option in addition to the common options from
  1948. the @ref{subtitles} filter:
  1949. @table @option
  1950. @item shaping
  1951. Set the shaping engine
  1952. Available values are:
  1953. @table @samp
  1954. @item auto
  1955. The default libass shaping engine, which is the best available.
  1956. @item simple
  1957. Fast, font-agnostic shaper that can do only substitutions
  1958. @item complex
  1959. Slower shaper using OpenType for substitutions and positioning
  1960. @end table
  1961. The default is @code{auto}.
  1962. @end table
  1963. @section bbox
  1964. Compute the bounding box for the non-black pixels in the input frame
  1965. luminance plane.
  1966. This filter computes the bounding box containing all the pixels with a
  1967. luminance value greater than the minimum allowed value.
  1968. The parameters describing the bounding box are printed on the filter
  1969. log.
  1970. The filter accepts the following option:
  1971. @table @option
  1972. @item min_val
  1973. Set the minimal luminance value. Default is @code{16}.
  1974. @end table
  1975. @section blackdetect
  1976. Detect video intervals that are (almost) completely black. Can be
  1977. useful to detect chapter transitions, commercials, or invalid
  1978. recordings. Output lines contains the time for the start, end and
  1979. duration of the detected black interval expressed in seconds.
  1980. In order to display the output lines, you need to set the loglevel at
  1981. least to the AV_LOG_INFO value.
  1982. The filter accepts the following options:
  1983. @table @option
  1984. @item black_min_duration, d
  1985. Set the minimum detected black duration expressed in seconds. It must
  1986. be a non-negative floating point number.
  1987. Default value is 2.0.
  1988. @item picture_black_ratio_th, pic_th
  1989. Set the threshold for considering a picture "black".
  1990. Express the minimum value for the ratio:
  1991. @example
  1992. @var{nb_black_pixels} / @var{nb_pixels}
  1993. @end example
  1994. for which a picture is considered black.
  1995. Default value is 0.98.
  1996. @item pixel_black_th, pix_th
  1997. Set the threshold for considering a pixel "black".
  1998. The threshold expresses the maximum pixel luminance value for which a
  1999. pixel is considered "black". The provided value is scaled according to
  2000. the following equation:
  2001. @example
  2002. @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
  2003. @end example
  2004. @var{luminance_range_size} and @var{luminance_minimum_value} depend on
  2005. the input video format, the range is [0-255] for YUV full-range
  2006. formats and [16-235] for YUV non full-range formats.
  2007. Default value is 0.10.
  2008. @end table
  2009. The following example sets the maximum pixel threshold to the minimum
  2010. value, and detects only black intervals of 2 or more seconds:
  2011. @example
  2012. blackdetect=d=2:pix_th=0.00
  2013. @end example
  2014. @section blackframe
  2015. Detect frames that are (almost) completely black. Can be useful to
  2016. detect chapter transitions or commercials. Output lines consist of
  2017. the frame number of the detected frame, the percentage of blackness,
  2018. the position in the file if known or -1 and the timestamp in seconds.
  2019. In order to display the output lines, you need to set the loglevel at
  2020. least to the AV_LOG_INFO value.
  2021. It accepts the following parameters:
  2022. @table @option
  2023. @item amount
  2024. The percentage of the pixels that have to be below the threshold; it defaults to
  2025. @code{98}.
  2026. @item threshold, thresh
  2027. The threshold below which a pixel value is considered black; it defaults to
  2028. @code{32}.
  2029. @end table
  2030. @section blend, tblend
  2031. Blend two video frames into each other.
  2032. The @code{blend} filter takes two input streams and outputs one
  2033. stream, the first input is the "top" layer and second input is
  2034. "bottom" layer. Output terminates when shortest input terminates.
  2035. The @code{tblend} (time blend) filter takes two consecutive frames
  2036. from one single stream, and outputs the result obtained by blending
  2037. the new frame on top of the old frame.
  2038. A description of the accepted options follows.
  2039. @table @option
  2040. @item c0_mode
  2041. @item c1_mode
  2042. @item c2_mode
  2043. @item c3_mode
  2044. @item all_mode
  2045. Set blend mode for specific pixel component or all pixel components in case
  2046. of @var{all_mode}. Default value is @code{normal}.
  2047. Available values for component modes are:
  2048. @table @samp
  2049. @item addition
  2050. @item and
  2051. @item average
  2052. @item burn
  2053. @item darken
  2054. @item difference
  2055. @item difference128
  2056. @item divide
  2057. @item dodge
  2058. @item exclusion
  2059. @item hardlight
  2060. @item lighten
  2061. @item multiply
  2062. @item negation
  2063. @item normal
  2064. @item or
  2065. @item overlay
  2066. @item phoenix
  2067. @item pinlight
  2068. @item reflect
  2069. @item screen
  2070. @item softlight
  2071. @item subtract
  2072. @item vividlight
  2073. @item xor
  2074. @end table
  2075. @item c0_opacity
  2076. @item c1_opacity
  2077. @item c2_opacity
  2078. @item c3_opacity
  2079. @item all_opacity
  2080. Set blend opacity for specific pixel component or all pixel components in case
  2081. of @var{all_opacity}. Only used in combination with pixel component blend modes.
  2082. @item c0_expr
  2083. @item c1_expr
  2084. @item c2_expr
  2085. @item c3_expr
  2086. @item all_expr
  2087. Set blend expression for specific pixel component or all pixel components in case
  2088. of @var{all_expr}. Note that related mode options will be ignored if those are set.
  2089. The expressions can use the following variables:
  2090. @table @option
  2091. @item N
  2092. The sequential number of the filtered frame, starting from @code{0}.
  2093. @item X
  2094. @item Y
  2095. the coordinates of the current sample
  2096. @item W
  2097. @item H
  2098. the width and height of currently filtered plane
  2099. @item SW
  2100. @item SH
  2101. Width and height scale depending on the currently filtered plane. It is the
  2102. ratio between the corresponding luma plane number of pixels and the current
  2103. plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
  2104. @code{0.5,0.5} for chroma planes.
  2105. @item T
  2106. Time of the current frame, expressed in seconds.
  2107. @item TOP, A
  2108. Value of pixel component at current location for first video frame (top layer).
  2109. @item BOTTOM, B
  2110. Value of pixel component at current location for second video frame (bottom layer).
  2111. @end table
  2112. @item shortest
  2113. Force termination when the shortest input terminates. Default is
  2114. @code{0}. This option is only defined for the @code{blend} filter.
  2115. @item repeatlast
  2116. Continue applying the last bottom frame after the end of the stream. A value of
  2117. @code{0} disable the filter after the last frame of the bottom layer is reached.
  2118. Default is @code{1}. This option is only defined for the @code{blend} filter.
  2119. @end table
  2120. @subsection Examples
  2121. @itemize
  2122. @item
  2123. Apply transition from bottom layer to top layer in first 10 seconds:
  2124. @example
  2125. blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
  2126. @end example
  2127. @item
  2128. Apply 1x1 checkerboard effect:
  2129. @example
  2130. blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
  2131. @end example
  2132. @item
  2133. Apply uncover left effect:
  2134. @example
  2135. blend=all_expr='if(gte(N*SW+X,W),A,B)'
  2136. @end example
  2137. @item
  2138. Apply uncover down effect:
  2139. @example
  2140. blend=all_expr='if(gte(Y-N*SH,0),A,B)'
  2141. @end example
  2142. @item
  2143. Apply uncover up-left effect:
  2144. @example
  2145. blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
  2146. @end example
  2147. @item
  2148. Display differences between the current and the previous frame:
  2149. @example
  2150. tblend=all_mode=difference128
  2151. @end example
  2152. @end itemize
  2153. @section boxblur
  2154. Apply a boxblur algorithm to the input video.
  2155. It accepts the following parameters:
  2156. @table @option
  2157. @item luma_radius, lr
  2158. @item luma_power, lp
  2159. @item chroma_radius, cr
  2160. @item chroma_power, cp
  2161. @item alpha_radius, ar
  2162. @item alpha_power, ap
  2163. @end table
  2164. A description of the accepted options follows.
  2165. @table @option
  2166. @item luma_radius, lr
  2167. @item chroma_radius, cr
  2168. @item alpha_radius, ar
  2169. Set an expression for the box radius in pixels used for blurring the
  2170. corresponding input plane.
  2171. The radius value must be a non-negative number, and must not be
  2172. greater than the value of the expression @code{min(w,h)/2} for the
  2173. luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
  2174. planes.
  2175. Default value for @option{luma_radius} is "2". If not specified,
  2176. @option{chroma_radius} and @option{alpha_radius} default to the
  2177. corresponding value set for @option{luma_radius}.
  2178. The expressions can contain the following constants:
  2179. @table @option
  2180. @item w
  2181. @item h
  2182. The input width and height in pixels.
  2183. @item cw
  2184. @item ch
  2185. The input chroma image width and height in pixels.
  2186. @item hsub
  2187. @item vsub
  2188. The horizontal and vertical chroma subsample values. For example, for the
  2189. pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
  2190. @end table
  2191. @item luma_power, lp
  2192. @item chroma_power, cp
  2193. @item alpha_power, ap
  2194. Specify how many times the boxblur filter is applied to the
  2195. corresponding plane.
  2196. Default value for @option{luma_power} is 2. If not specified,
  2197. @option{chroma_power} and @option{alpha_power} default to the
  2198. corresponding value set for @option{luma_power}.
  2199. A value of 0 will disable the effect.
  2200. @end table
  2201. @subsection Examples
  2202. @itemize
  2203. @item
  2204. Apply a boxblur filter with the luma, chroma, and alpha radii
  2205. set to 2:
  2206. @example
  2207. boxblur=luma_radius=2:luma_power=1
  2208. boxblur=2:1
  2209. @end example
  2210. @item
  2211. Set the luma radius to 2, and alpha and chroma radius to 0:
  2212. @example
  2213. boxblur=2:1:cr=0:ar=0
  2214. @end example
  2215. @item
  2216. Set the luma and chroma radii to a fraction of the video dimension:
  2217. @example
  2218. boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
  2219. @end example
  2220. @end itemize
  2221. @section codecview
  2222. Visualize information exported by some codecs.
  2223. Some codecs can export information through frames using side-data or other
  2224. means. For example, some MPEG based codecs export motion vectors through the
  2225. @var{export_mvs} flag in the codec @option{flags2} option.
  2226. The filter accepts the following option:
  2227. @table @option
  2228. @item mv
  2229. Set motion vectors to visualize.
  2230. Available flags for @var{mv} are:
  2231. @table @samp
  2232. @item pf
  2233. forward predicted MVs of P-frames
  2234. @item bf
  2235. forward predicted MVs of B-frames
  2236. @item bb
  2237. backward predicted MVs of B-frames
  2238. @end table
  2239. @end table
  2240. @subsection Examples
  2241. @itemize
  2242. @item
  2243. Visualizes multi-directionals MVs from P and B-Frames using @command{ffplay}:
  2244. @example
  2245. ffplay -flags2 +export_mvs input.mpg -vf codecview=mv=pf+bf+bb
  2246. @end example
  2247. @end itemize
  2248. @section colorbalance
  2249. Modify intensity of primary colors (red, green and blue) of input frames.
  2250. The filter allows an input frame to be adjusted in the shadows, midtones or highlights
  2251. regions for the red-cyan, green-magenta or blue-yellow balance.
  2252. A positive adjustment value shifts the balance towards the primary color, a negative
  2253. value towards the complementary color.
  2254. The filter accepts the following options:
  2255. @table @option
  2256. @item rs
  2257. @item gs
  2258. @item bs
  2259. Adjust red, green and blue shadows (darkest pixels).
  2260. @item rm
  2261. @item gm
  2262. @item bm
  2263. Adjust red, green and blue midtones (medium pixels).
  2264. @item rh
  2265. @item gh
  2266. @item bh
  2267. Adjust red, green and blue highlights (brightest pixels).
  2268. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  2269. @end table
  2270. @subsection Examples
  2271. @itemize
  2272. @item
  2273. Add red color cast to shadows:
  2274. @example
  2275. colorbalance=rs=.3
  2276. @end example
  2277. @end itemize
  2278. @section colorlevels
  2279. Adjust video input frames using levels.
  2280. The filter accepts the following options:
  2281. @table @option
  2282. @item rimin
  2283. @item gimin
  2284. @item bimin
  2285. @item aimin
  2286. Adjust red, green, blue and alpha input black point.
  2287. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
  2288. @item rimax
  2289. @item gimax
  2290. @item bimax
  2291. @item aimax
  2292. Adjust red, green, blue and alpha input white point.
  2293. Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
  2294. Input levels are used to lighten highlights (bright tones), darken shadows
  2295. (dark tones), change the balance of bright and dark tones.
  2296. @item romin
  2297. @item gomin
  2298. @item bomin
  2299. @item aomin
  2300. Adjust red, green, blue and alpha output black point.
  2301. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
  2302. @item romax
  2303. @item gomax
  2304. @item bomax
  2305. @item aomax
  2306. Adjust red, green, blue and alpha output white point.
  2307. Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
  2308. Output levels allows manual selection of a constrained output level range.
  2309. @end table
  2310. @subsection Examples
  2311. @itemize
  2312. @item
  2313. Make video output darker:
  2314. @example
  2315. colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
  2316. @end example
  2317. @item
  2318. Increase contrast:
  2319. @example
  2320. colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
  2321. @end example
  2322. @item
  2323. Make video output lighter:
  2324. @example
  2325. colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
  2326. @end example
  2327. @item
  2328. Increase brightness:
  2329. @example
  2330. colorlevels=romin=0.5:gomin=0.5:bomin=0.5
  2331. @end example
  2332. @end itemize
  2333. @section colorchannelmixer
  2334. Adjust video input frames by re-mixing color channels.
  2335. This filter modifies a color channel by adding the values associated to
  2336. the other channels of the same pixels. For example if the value to
  2337. modify is red, the output value will be:
  2338. @example
  2339. @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
  2340. @end example
  2341. The filter accepts the following options:
  2342. @table @option
  2343. @item rr
  2344. @item rg
  2345. @item rb
  2346. @item ra
  2347. Adjust contribution of input red, green, blue and alpha channels for output red channel.
  2348. Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
  2349. @item gr
  2350. @item gg
  2351. @item gb
  2352. @item ga
  2353. Adjust contribution of input red, green, blue and alpha channels for output green channel.
  2354. Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
  2355. @item br
  2356. @item bg
  2357. @item bb
  2358. @item ba
  2359. Adjust contribution of input red, green, blue and alpha channels for output blue channel.
  2360. Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
  2361. @item ar
  2362. @item ag
  2363. @item ab
  2364. @item aa
  2365. Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
  2366. Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
  2367. Allowed ranges for options are @code{[-2.0, 2.0]}.
  2368. @end table
  2369. @subsection Examples
  2370. @itemize
  2371. @item
  2372. Convert source to grayscale:
  2373. @example
  2374. colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
  2375. @end example
  2376. @item
  2377. Simulate sepia tones:
  2378. @example
  2379. colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
  2380. @end example
  2381. @end itemize
  2382. @section colormatrix
  2383. Convert color matrix.
  2384. The filter accepts the following options:
  2385. @table @option
  2386. @item src
  2387. @item dst
  2388. Specify the source and destination color matrix. Both values must be
  2389. specified.
  2390. The accepted values are:
  2391. @table @samp
  2392. @item bt709
  2393. BT.709
  2394. @item bt601
  2395. BT.601
  2396. @item smpte240m
  2397. SMPTE-240M
  2398. @item fcc
  2399. FCC
  2400. @end table
  2401. @end table
  2402. For example to convert from BT.601 to SMPTE-240M, use the command:
  2403. @example
  2404. colormatrix=bt601:smpte240m
  2405. @end example
  2406. @section copy
  2407. Copy the input source unchanged to the output. This is mainly useful for
  2408. testing purposes.
  2409. @section crop
  2410. Crop the input video to given dimensions.
  2411. It accepts the following parameters:
  2412. @table @option
  2413. @item w, out_w
  2414. The width of the output video. It defaults to @code{iw}.
  2415. This expression is evaluated only once during the filter
  2416. configuration.
  2417. @item h, out_h
  2418. The height of the output video. It defaults to @code{ih}.
  2419. This expression is evaluated only once during the filter
  2420. configuration.
  2421. @item x
  2422. The horizontal position, in the input video, of the left edge of the output
  2423. video. It defaults to @code{(in_w-out_w)/2}.
  2424. This expression is evaluated per-frame.
  2425. @item y
  2426. The vertical position, in the input video, of the top edge of the output video.
  2427. It defaults to @code{(in_h-out_h)/2}.
  2428. This expression is evaluated per-frame.
  2429. @item keep_aspect
  2430. If set to 1 will force the output display aspect ratio
  2431. to be the same of the input, by changing the output sample aspect
  2432. ratio. It defaults to 0.
  2433. @end table
  2434. The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
  2435. expressions containing the following constants:
  2436. @table @option
  2437. @item x
  2438. @item y
  2439. The computed values for @var{x} and @var{y}. They are evaluated for
  2440. each new frame.
  2441. @item in_w
  2442. @item in_h
  2443. The input width and height.
  2444. @item iw
  2445. @item ih
  2446. These are the same as @var{in_w} and @var{in_h}.
  2447. @item out_w
  2448. @item out_h
  2449. The output (cropped) width and height.
  2450. @item ow
  2451. @item oh
  2452. These are the same as @var{out_w} and @var{out_h}.
  2453. @item a
  2454. same as @var{iw} / @var{ih}
  2455. @item sar
  2456. input sample aspect ratio
  2457. @item dar
  2458. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  2459. @item hsub
  2460. @item vsub
  2461. horizontal and vertical chroma subsample values. For example for the
  2462. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  2463. @item n
  2464. The number of the input frame, starting from 0.
  2465. @item pos
  2466. the position in the file of the input frame, NAN if unknown
  2467. @item t
  2468. The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
  2469. @end table
  2470. The expression for @var{out_w} may depend on the value of @var{out_h},
  2471. and the expression for @var{out_h} may depend on @var{out_w}, but they
  2472. cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
  2473. evaluated after @var{out_w} and @var{out_h}.
  2474. The @var{x} and @var{y} parameters specify the expressions for the
  2475. position of the top-left corner of the output (non-cropped) area. They
  2476. are evaluated for each frame. If the evaluated value is not valid, it
  2477. is approximated to the nearest valid value.
  2478. The expression for @var{x} may depend on @var{y}, and the expression
  2479. for @var{y} may depend on @var{x}.
  2480. @subsection Examples
  2481. @itemize
  2482. @item
  2483. Crop area with size 100x100 at position (12,34).
  2484. @example
  2485. crop=100:100:12:34
  2486. @end example
  2487. Using named options, the example above becomes:
  2488. @example
  2489. crop=w=100:h=100:x=12:y=34
  2490. @end example
  2491. @item
  2492. Crop the central input area with size 100x100:
  2493. @example
  2494. crop=100:100
  2495. @end example
  2496. @item
  2497. Crop the central input area with size 2/3 of the input video:
  2498. @example
  2499. crop=2/3*in_w:2/3*in_h
  2500. @end example
  2501. @item
  2502. Crop the input video central square:
  2503. @example
  2504. crop=out_w=in_h
  2505. crop=in_h
  2506. @end example
  2507. @item
  2508. Delimit the rectangle with the top-left corner placed at position
  2509. 100:100 and the right-bottom corner corresponding to the right-bottom
  2510. corner of the input image.
  2511. @example
  2512. crop=in_w-100:in_h-100:100:100
  2513. @end example
  2514. @item
  2515. Crop 10 pixels from the left and right borders, and 20 pixels from
  2516. the top and bottom borders
  2517. @example
  2518. crop=in_w-2*10:in_h-2*20
  2519. @end example
  2520. @item
  2521. Keep only the bottom right quarter of the input image:
  2522. @example
  2523. crop=in_w/2:in_h/2:in_w/2:in_h/2
  2524. @end example
  2525. @item
  2526. Crop height for getting Greek harmony:
  2527. @example
  2528. crop=in_w:1/PHI*in_w
  2529. @end example
  2530. @item
  2531. Apply trembling effect:
  2532. @example
  2533. 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)
  2534. @end example
  2535. @item
  2536. Apply erratic camera effect depending on timestamp:
  2537. @example
  2538. 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)"
  2539. @end example
  2540. @item
  2541. Set x depending on the value of y:
  2542. @example
  2543. crop=in_w/2:in_h/2:y:10+10*sin(n/10)
  2544. @end example
  2545. @end itemize
  2546. @section cropdetect
  2547. Auto-detect the crop size.
  2548. It calculates the necessary cropping parameters and prints the
  2549. recommended parameters via the logging system. The detected dimensions
  2550. correspond to the non-black area of the input video.
  2551. It accepts the following parameters:
  2552. @table @option
  2553. @item limit
  2554. Set higher black value threshold, which can be optionally specified
  2555. from nothing (0) to everything (255 for 8bit based formats). An intensity
  2556. value greater to the set value is considered non-black. It defaults to 24.
  2557. You can also specify a value between 0.0 and 1.0 which will be scaled depending
  2558. on the bitdepth of the pixel format.
  2559. @item round
  2560. The value which the width/height should be divisible by. It defaults to
  2561. 16. The offset is automatically adjusted to center the video. Use 2 to
  2562. get only even dimensions (needed for 4:2:2 video). 16 is best when
  2563. encoding to most video codecs.
  2564. @item reset_count, reset
  2565. Set the counter that determines after how many frames cropdetect will
  2566. reset the previously detected largest video area and start over to
  2567. detect the current optimal crop area. Default value is 0.
  2568. This can be useful when channel logos distort the video area. 0
  2569. indicates 'never reset', and returns the largest area encountered during
  2570. playback.
  2571. @end table
  2572. @anchor{curves}
  2573. @section curves
  2574. Apply color adjustments using curves.
  2575. This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
  2576. component (red, green and blue) has its values defined by @var{N} key points
  2577. tied from each other using a smooth curve. The x-axis represents the pixel
  2578. values from the input frame, and the y-axis the new pixel values to be set for
  2579. the output frame.
  2580. By default, a component curve is defined by the two points @var{(0;0)} and
  2581. @var{(1;1)}. This creates a straight line where each original pixel value is
  2582. "adjusted" to its own value, which means no change to the image.
  2583. The filter allows you to redefine these two points and add some more. A new
  2584. curve (using a natural cubic spline interpolation) will be define to pass
  2585. smoothly through all these new coordinates. The new defined points needs to be
  2586. strictly increasing over the x-axis, and their @var{x} and @var{y} values must
  2587. be in the @var{[0;1]} interval. If the computed curves happened to go outside
  2588. the vector spaces, the values will be clipped accordingly.
  2589. If there is no key point defined in @code{x=0}, the filter will automatically
  2590. insert a @var{(0;0)} point. In the same way, if there is no key point defined
  2591. in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
  2592. The filter accepts the following options:
  2593. @table @option
  2594. @item preset
  2595. Select one of the available color presets. This option can be used in addition
  2596. to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
  2597. options takes priority on the preset values.
  2598. Available presets are:
  2599. @table @samp
  2600. @item none
  2601. @item color_negative
  2602. @item cross_process
  2603. @item darker
  2604. @item increase_contrast
  2605. @item lighter
  2606. @item linear_contrast
  2607. @item medium_contrast
  2608. @item negative
  2609. @item strong_contrast
  2610. @item vintage
  2611. @end table
  2612. Default is @code{none}.
  2613. @item master, m
  2614. Set the master key points. These points will define a second pass mapping. It
  2615. is sometimes called a "luminance" or "value" mapping. It can be used with
  2616. @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
  2617. post-processing LUT.
  2618. @item red, r
  2619. Set the key points for the red component.
  2620. @item green, g
  2621. Set the key points for the green component.
  2622. @item blue, b
  2623. Set the key points for the blue component.
  2624. @item all
  2625. Set the key points for all components (not including master).
  2626. Can be used in addition to the other key points component
  2627. options. In this case, the unset component(s) will fallback on this
  2628. @option{all} setting.
  2629. @item psfile
  2630. Specify a Photoshop curves file (@code{.asv}) to import the settings from.
  2631. @end table
  2632. To avoid some filtergraph syntax conflicts, each key points list need to be
  2633. defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
  2634. @subsection Examples
  2635. @itemize
  2636. @item
  2637. Increase slightly the middle level of blue:
  2638. @example
  2639. curves=blue='0.5/0.58'
  2640. @end example
  2641. @item
  2642. Vintage effect:
  2643. @example
  2644. curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
  2645. @end example
  2646. Here we obtain the following coordinates for each components:
  2647. @table @var
  2648. @item red
  2649. @code{(0;0.11) (0.42;0.51) (1;0.95)}
  2650. @item green
  2651. @code{(0;0) (0.50;0.48) (1;1)}
  2652. @item blue
  2653. @code{(0;0.22) (0.49;0.44) (1;0.80)}
  2654. @end table
  2655. @item
  2656. The previous example can also be achieved with the associated built-in preset:
  2657. @example
  2658. curves=preset=vintage
  2659. @end example
  2660. @item
  2661. Or simply:
  2662. @example
  2663. curves=vintage
  2664. @end example
  2665. @item
  2666. Use a Photoshop preset and redefine the points of the green component:
  2667. @example
  2668. curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
  2669. @end example
  2670. @end itemize
  2671. @section dctdnoiz
  2672. Denoise frames using 2D DCT (frequency domain filtering).
  2673. This filter is not designed for real time.
  2674. The filter accepts the following options:
  2675. @table @option
  2676. @item sigma, s
  2677. Set the noise sigma constant.
  2678. This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
  2679. coefficient (absolute value) below this threshold with be dropped.
  2680. If you need a more advanced filtering, see @option{expr}.
  2681. Default is @code{0}.
  2682. @item overlap
  2683. Set number overlapping pixels for each block. Since the filter can be slow, you
  2684. may want to reduce this value, at the cost of a less effective filter and the
  2685. risk of various artefacts.
  2686. If the overlapping value doesn't allow to process the whole input width or
  2687. height, a warning will be displayed and according borders won't be denoised.
  2688. Default value is @var{blocksize}-1, which is the best possible setting.
  2689. @item expr, e
  2690. Set the coefficient factor expression.
  2691. For each coefficient of a DCT block, this expression will be evaluated as a
  2692. multiplier value for the coefficient.
  2693. If this is option is set, the @option{sigma} option will be ignored.
  2694. The absolute value of the coefficient can be accessed through the @var{c}
  2695. variable.
  2696. @item n
  2697. Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
  2698. @var{blocksize}, which is the width and height of the processed blocks.
  2699. The default value is @var{3} (8x8) and can be raised to @var{4} for a
  2700. @var{blocksize} of 16x16. Note that changing this setting has huge consequences
  2701. on the speed processing. Also, a larger block size does not necessarily means a
  2702. better de-noising.
  2703. @end table
  2704. @subsection Examples
  2705. Apply a denoise with a @option{sigma} of @code{4.5}:
  2706. @example
  2707. dctdnoiz=4.5
  2708. @end example
  2709. The same operation can be achieved using the expression system:
  2710. @example
  2711. dctdnoiz=e='gte(c, 4.5*3)'
  2712. @end example
  2713. Violent denoise using a block size of @code{16x16}:
  2714. @example
  2715. dctdnoiz=15:n=4
  2716. @end example
  2717. @anchor{decimate}
  2718. @section decimate
  2719. Drop duplicated frames at regular intervals.
  2720. The filter accepts the following options:
  2721. @table @option
  2722. @item cycle
  2723. Set the number of frames from which one will be dropped. Setting this to
  2724. @var{N} means one frame in every batch of @var{N} frames will be dropped.
  2725. Default is @code{5}.
  2726. @item dupthresh
  2727. Set the threshold for duplicate detection. If the difference metric for a frame
  2728. is less than or equal to this value, then it is declared as duplicate. Default
  2729. is @code{1.1}
  2730. @item scthresh
  2731. Set scene change threshold. Default is @code{15}.
  2732. @item blockx
  2733. @item blocky
  2734. Set the size of the x and y-axis blocks used during metric calculations.
  2735. Larger blocks give better noise suppression, but also give worse detection of
  2736. small movements. Must be a power of two. Default is @code{32}.
  2737. @item ppsrc
  2738. Mark main input as a pre-processed input and activate clean source input
  2739. stream. This allows the input to be pre-processed with various filters to help
  2740. the metrics calculation while keeping the frame selection lossless. When set to
  2741. @code{1}, the first stream is for the pre-processed input, and the second
  2742. stream is the clean source from where the kept frames are chosen. Default is
  2743. @code{0}.
  2744. @item chroma
  2745. Set whether or not chroma is considered in the metric calculations. Default is
  2746. @code{1}.
  2747. @end table
  2748. @section dejudder
  2749. Remove judder produced by partially interlaced telecined content.
  2750. Judder can be introduced, for instance, by @ref{pullup} filter. If the original
  2751. source was partially telecined content then the output of @code{pullup,dejudder}
  2752. will have a variable frame rate. May change the recorded frame rate of the
  2753. container. Aside from that change, this filter will not affect constant frame
  2754. rate video.
  2755. The option available in this filter is:
  2756. @table @option
  2757. @item cycle
  2758. Specify the length of the window over which the judder repeats.
  2759. Accepts any integer greater than 1. Useful values are:
  2760. @table @samp
  2761. @item 4
  2762. If the original was telecined from 24 to 30 fps (Film to NTSC).
  2763. @item 5
  2764. If the original was telecined from 25 to 30 fps (PAL to NTSC).
  2765. @item 20
  2766. If a mixture of the two.
  2767. @end table
  2768. The default is @samp{4}.
  2769. @end table
  2770. @section delogo
  2771. Suppress a TV station logo by a simple interpolation of the surrounding
  2772. pixels. Just set a rectangle covering the logo and watch it disappear
  2773. (and sometimes something even uglier appear - your mileage may vary).
  2774. It accepts the following parameters:
  2775. @table @option
  2776. @item x
  2777. @item y
  2778. Specify the top left corner coordinates of the logo. They must be
  2779. specified.
  2780. @item w
  2781. @item h
  2782. Specify the width and height of the logo to clear. They must be
  2783. specified.
  2784. @item band, t
  2785. Specify the thickness of the fuzzy edge of the rectangle (added to
  2786. @var{w} and @var{h}). The default value is 4.
  2787. @item show
  2788. When set to 1, a green rectangle is drawn on the screen to simplify
  2789. finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
  2790. The default value is 0.
  2791. The rectangle is drawn on the outermost pixels which will be (partly)
  2792. replaced with interpolated values. The values of the next pixels
  2793. immediately outside this rectangle in each direction will be used to
  2794. compute the interpolated pixel values inside the rectangle.
  2795. @end table
  2796. @subsection Examples
  2797. @itemize
  2798. @item
  2799. Set a rectangle covering the area with top left corner coordinates 0,0
  2800. and size 100x77, and a band of size 10:
  2801. @example
  2802. delogo=x=0:y=0:w=100:h=77:band=10
  2803. @end example
  2804. @end itemize
  2805. @section deshake
  2806. Attempt to fix small changes in horizontal and/or vertical shift. This
  2807. filter helps remove camera shake from hand-holding a camera, bumping a
  2808. tripod, moving on a vehicle, etc.
  2809. The filter accepts the following options:
  2810. @table @option
  2811. @item x
  2812. @item y
  2813. @item w
  2814. @item h
  2815. Specify a rectangular area where to limit the search for motion
  2816. vectors.
  2817. If desired the search for motion vectors can be limited to a
  2818. rectangular area of the frame defined by its top left corner, width
  2819. and height. These parameters have the same meaning as the drawbox
  2820. filter which can be used to visualise the position of the bounding
  2821. box.
  2822. This is useful when simultaneous movement of subjects within the frame
  2823. might be confused for camera motion by the motion vector search.
  2824. If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
  2825. then the full frame is used. This allows later options to be set
  2826. without specifying the bounding box for the motion vector search.
  2827. Default - search the whole frame.
  2828. @item rx
  2829. @item ry
  2830. Specify the maximum extent of movement in x and y directions in the
  2831. range 0-64 pixels. Default 16.
  2832. @item edge
  2833. Specify how to generate pixels to fill blanks at the edge of the
  2834. frame. Available values are:
  2835. @table @samp
  2836. @item blank, 0
  2837. Fill zeroes at blank locations
  2838. @item original, 1
  2839. Original image at blank locations
  2840. @item clamp, 2
  2841. Extruded edge value at blank locations
  2842. @item mirror, 3
  2843. Mirrored edge at blank locations
  2844. @end table
  2845. Default value is @samp{mirror}.
  2846. @item blocksize
  2847. Specify the blocksize to use for motion search. Range 4-128 pixels,
  2848. default 8.
  2849. @item contrast
  2850. Specify the contrast threshold for blocks. Only blocks with more than
  2851. the specified contrast (difference between darkest and lightest
  2852. pixels) will be considered. Range 1-255, default 125.
  2853. @item search
  2854. Specify the search strategy. Available values are:
  2855. @table @samp
  2856. @item exhaustive, 0
  2857. Set exhaustive search
  2858. @item less, 1
  2859. Set less exhaustive search.
  2860. @end table
  2861. Default value is @samp{exhaustive}.
  2862. @item filename
  2863. If set then a detailed log of the motion search is written to the
  2864. specified file.
  2865. @item opencl
  2866. If set to 1, specify using OpenCL capabilities, only available if
  2867. FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
  2868. @end table
  2869. @section drawbox
  2870. Draw a colored box on the input image.
  2871. It accepts the following parameters:
  2872. @table @option
  2873. @item x
  2874. @item y
  2875. The expressions which specify the top left corner coordinates of the box. It defaults to 0.
  2876. @item width, w
  2877. @item height, h
  2878. The expressions which specify the width and height of the box; if 0 they are interpreted as
  2879. the input width and height. It defaults to 0.
  2880. @item color, c
  2881. Specify the color of the box to write. For the general syntax of this option,
  2882. check the "Color" section in the ffmpeg-utils manual. If the special
  2883. value @code{invert} is used, the box edge color is the same as the
  2884. video with inverted luma.
  2885. @item thickness, t
  2886. The expression which sets the thickness of the box edge. Default value is @code{3}.
  2887. See below for the list of accepted constants.
  2888. @end table
  2889. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  2890. following constants:
  2891. @table @option
  2892. @item dar
  2893. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  2894. @item hsub
  2895. @item vsub
  2896. horizontal and vertical chroma subsample values. For example for the
  2897. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  2898. @item in_h, ih
  2899. @item in_w, iw
  2900. The input width and height.
  2901. @item sar
  2902. The input sample aspect ratio.
  2903. @item x
  2904. @item y
  2905. The x and y offset coordinates where the box is drawn.
  2906. @item w
  2907. @item h
  2908. The width and height of the drawn box.
  2909. @item t
  2910. The thickness of the drawn box.
  2911. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  2912. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  2913. @end table
  2914. @subsection Examples
  2915. @itemize
  2916. @item
  2917. Draw a black box around the edge of the input image:
  2918. @example
  2919. drawbox
  2920. @end example
  2921. @item
  2922. Draw a box with color red and an opacity of 50%:
  2923. @example
  2924. drawbox=10:20:200:60:red@@0.5
  2925. @end example
  2926. The previous example can be specified as:
  2927. @example
  2928. drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
  2929. @end example
  2930. @item
  2931. Fill the box with pink color:
  2932. @example
  2933. drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
  2934. @end example
  2935. @item
  2936. Draw a 2-pixel red 2.40:1 mask:
  2937. @example
  2938. 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
  2939. @end example
  2940. @end itemize
  2941. @section drawgrid
  2942. Draw a grid on the input image.
  2943. It accepts the following parameters:
  2944. @table @option
  2945. @item x
  2946. @item y
  2947. The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
  2948. @item width, w
  2949. @item height, h
  2950. The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
  2951. input width and height, respectively, minus @code{thickness}, so image gets
  2952. framed. Default to 0.
  2953. @item color, c
  2954. Specify the color of the grid. For the general syntax of this option,
  2955. check the "Color" section in the ffmpeg-utils manual. If the special
  2956. value @code{invert} is used, the grid color is the same as the
  2957. video with inverted luma.
  2958. @item thickness, t
  2959. The expression which sets the thickness of the grid line. Default value is @code{1}.
  2960. See below for the list of accepted constants.
  2961. @end table
  2962. The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
  2963. following constants:
  2964. @table @option
  2965. @item dar
  2966. The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
  2967. @item hsub
  2968. @item vsub
  2969. horizontal and vertical chroma subsample values. For example for the
  2970. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  2971. @item in_h, ih
  2972. @item in_w, iw
  2973. The input grid cell width and height.
  2974. @item sar
  2975. The input sample aspect ratio.
  2976. @item x
  2977. @item y
  2978. The x and y coordinates of some point of grid intersection (meant to configure offset).
  2979. @item w
  2980. @item h
  2981. The width and height of the drawn cell.
  2982. @item t
  2983. The thickness of the drawn cell.
  2984. These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
  2985. each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
  2986. @end table
  2987. @subsection Examples
  2988. @itemize
  2989. @item
  2990. Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
  2991. @example
  2992. drawgrid=width=100:height=100:thickness=2:color=red@@0.5
  2993. @end example
  2994. @item
  2995. Draw a white 3x3 grid with an opacity of 50%:
  2996. @example
  2997. drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
  2998. @end example
  2999. @end itemize
  3000. @anchor{drawtext}
  3001. @section drawtext
  3002. Draw a text string or text from a specified file on top of a video, using the
  3003. libfreetype library.
  3004. To enable compilation of this filter, you need to configure FFmpeg with
  3005. @code{--enable-libfreetype}.
  3006. To enable default font fallback and the @var{font} option you need to
  3007. configure FFmpeg with @code{--enable-libfontconfig}.
  3008. To enable the @var{text_shaping} option, you need to configure FFmpeg with
  3009. @code{--enable-libfribidi}.
  3010. @subsection Syntax
  3011. It accepts the following parameters:
  3012. @table @option
  3013. @item box
  3014. Used to draw a box around text using the background color.
  3015. The value must be either 1 (enable) or 0 (disable).
  3016. The default value of @var{box} is 0.
  3017. @item boxcolor
  3018. The color to be used for drawing box around text. For the syntax of this
  3019. option, check the "Color" section in the ffmpeg-utils manual.
  3020. The default value of @var{boxcolor} is "white".
  3021. @item borderw
  3022. Set the width of the border to be drawn around the text using @var{bordercolor}.
  3023. The default value of @var{borderw} is 0.
  3024. @item bordercolor
  3025. Set the color to be used for drawing border around text. For the syntax of this
  3026. option, check the "Color" section in the ffmpeg-utils manual.
  3027. The default value of @var{bordercolor} is "black".
  3028. @item expansion
  3029. Select how the @var{text} is expanded. Can be either @code{none},
  3030. @code{strftime} (deprecated) or
  3031. @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
  3032. below for details.
  3033. @item fix_bounds
  3034. If true, check and fix text coords to avoid clipping.
  3035. @item fontcolor
  3036. The color to be used for drawing fonts. For the syntax of this option, check
  3037. the "Color" section in the ffmpeg-utils manual.
  3038. The default value of @var{fontcolor} is "black".
  3039. @item fontcolor_expr
  3040. String which is expanded the same way as @var{text} to obtain dynamic
  3041. @var{fontcolor} value. By default this option has empty value and is not
  3042. processed. When this option is set, it overrides @var{fontcolor} option.
  3043. @item font
  3044. The font family to be used for drawing text. By default Sans.
  3045. @item fontfile
  3046. The font file to be used for drawing text. The path must be included.
  3047. This parameter is mandatory if the fontconfig support is disabled.
  3048. @item fontsize
  3049. The font size to be used for drawing text.
  3050. The default value of @var{fontsize} is 16.
  3051. @item text_shaping
  3052. If set to 1, attempt to shape the text (for example, reverse the order of
  3053. right-to-left text and join Arabic characters) before drawing it.
  3054. Otherwise, just draw the text exactly as given.
  3055. By default 1 (if supported).
  3056. @item ft_load_flags
  3057. The flags to be used for loading the fonts.
  3058. The flags map the corresponding flags supported by libfreetype, and are
  3059. a combination of the following values:
  3060. @table @var
  3061. @item default
  3062. @item no_scale
  3063. @item no_hinting
  3064. @item render
  3065. @item no_bitmap
  3066. @item vertical_layout
  3067. @item force_autohint
  3068. @item crop_bitmap
  3069. @item pedantic
  3070. @item ignore_global_advance_width
  3071. @item no_recurse
  3072. @item ignore_transform
  3073. @item monochrome
  3074. @item linear_design
  3075. @item no_autohint
  3076. @end table
  3077. Default value is "default".
  3078. For more information consult the documentation for the FT_LOAD_*
  3079. libfreetype flags.
  3080. @item shadowcolor
  3081. The color to be used for drawing a shadow behind the drawn text. For the
  3082. syntax of this option, check the "Color" section in the ffmpeg-utils manual.
  3083. The default value of @var{shadowcolor} is "black".
  3084. @item shadowx
  3085. @item shadowy
  3086. The x and y offsets for the text shadow position with respect to the
  3087. position of the text. They can be either positive or negative
  3088. values. The default value for both is "0".
  3089. @item start_number
  3090. The starting frame number for the n/frame_num variable. The default value
  3091. is "0".
  3092. @item tabsize
  3093. The size in number of spaces to use for rendering the tab.
  3094. Default value is 4.
  3095. @item timecode
  3096. Set the initial timecode representation in "hh:mm:ss[:;.]ff"
  3097. format. It can be used with or without text parameter. @var{timecode_rate}
  3098. option must be specified.
  3099. @item timecode_rate, rate, r
  3100. Set the timecode frame rate (timecode only).
  3101. @item text
  3102. The text string to be drawn. The text must be a sequence of UTF-8
  3103. encoded characters.
  3104. This parameter is mandatory if no file is specified with the parameter
  3105. @var{textfile}.
  3106. @item textfile
  3107. A text file containing text to be drawn. The text must be a sequence
  3108. of UTF-8 encoded characters.
  3109. This parameter is mandatory if no text string is specified with the
  3110. parameter @var{text}.
  3111. If both @var{text} and @var{textfile} are specified, an error is thrown.
  3112. @item reload
  3113. If set to 1, the @var{textfile} will be reloaded before each frame.
  3114. Be sure to update it atomically, or it may be read partially, or even fail.
  3115. @item x
  3116. @item y
  3117. The expressions which specify the offsets where text will be drawn
  3118. within the video frame. They are relative to the top/left border of the
  3119. output image.
  3120. The default value of @var{x} and @var{y} is "0".
  3121. See below for the list of accepted constants and functions.
  3122. @end table
  3123. The parameters for @var{x} and @var{y} are expressions containing the
  3124. following constants and functions:
  3125. @table @option
  3126. @item dar
  3127. input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
  3128. @item hsub
  3129. @item vsub
  3130. horizontal and vertical chroma subsample values. For example for the
  3131. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  3132. @item line_h, lh
  3133. the height of each text line
  3134. @item main_h, h, H
  3135. the input height
  3136. @item main_w, w, W
  3137. the input width
  3138. @item max_glyph_a, ascent
  3139. the maximum distance from the baseline to the highest/upper grid
  3140. coordinate used to place a glyph outline point, for all the rendered
  3141. glyphs.
  3142. It is a positive value, due to the grid's orientation with the Y axis
  3143. upwards.
  3144. @item max_glyph_d, descent
  3145. the maximum distance from the baseline to the lowest grid coordinate
  3146. used to place a glyph outline point, for all the rendered glyphs.
  3147. This is a negative value, due to the grid's orientation, with the Y axis
  3148. upwards.
  3149. @item max_glyph_h
  3150. maximum glyph height, that is the maximum height for all the glyphs
  3151. contained in the rendered text, it is equivalent to @var{ascent} -
  3152. @var{descent}.
  3153. @item max_glyph_w
  3154. maximum glyph width, that is the maximum width for all the glyphs
  3155. contained in the rendered text
  3156. @item n
  3157. the number of input frame, starting from 0
  3158. @item rand(min, max)
  3159. return a random number included between @var{min} and @var{max}
  3160. @item sar
  3161. The input sample aspect ratio.
  3162. @item t
  3163. timestamp expressed in seconds, NAN if the input timestamp is unknown
  3164. @item text_h, th
  3165. the height of the rendered text
  3166. @item text_w, tw
  3167. the width of the rendered text
  3168. @item x
  3169. @item y
  3170. the x and y offset coordinates where the text is drawn.
  3171. These parameters allow the @var{x} and @var{y} expressions to refer
  3172. each other, so you can for example specify @code{y=x/dar}.
  3173. @end table
  3174. @anchor{drawtext_expansion}
  3175. @subsection Text expansion
  3176. If @option{expansion} is set to @code{strftime},
  3177. the filter recognizes strftime() sequences in the provided text and
  3178. expands them accordingly. Check the documentation of strftime(). This
  3179. feature is deprecated.
  3180. If @option{expansion} is set to @code{none}, the text is printed verbatim.
  3181. If @option{expansion} is set to @code{normal} (which is the default),
  3182. the following expansion mechanism is used.
  3183. The backslash character '\', followed by any character, always expands to
  3184. the second character.
  3185. Sequence of the form @code{%@{...@}} are expanded. The text between the
  3186. braces is a function name, possibly followed by arguments separated by ':'.
  3187. If the arguments contain special characters or delimiters (':' or '@}'),
  3188. they should be escaped.
  3189. Note that they probably must also be escaped as the value for the
  3190. @option{text} option in the filter argument string and as the filter
  3191. argument in the filtergraph description, and possibly also for the shell,
  3192. that makes up to four levels of escaping; using a text file avoids these
  3193. problems.
  3194. The following functions are available:
  3195. @table @command
  3196. @item expr, e
  3197. The expression evaluation result.
  3198. It must take one argument specifying the expression to be evaluated,
  3199. which accepts the same constants and functions as the @var{x} and
  3200. @var{y} values. Note that not all constants should be used, for
  3201. example the text size is not known when evaluating the expression, so
  3202. the constants @var{text_w} and @var{text_h} will have an undefined
  3203. value.
  3204. @item expr_int_format, eif
  3205. Evaluate the expression's value and output as formatted integer.
  3206. The first argument is the expression to be evaluated, just as for the @var{expr} function.
  3207. The second argument specifies the output format. Allowed values are 'x', 'X', 'd' and
  3208. 'u'. They are treated exactly as in the printf function.
  3209. The third parameter is optional and sets the number of positions taken by the output.
  3210. It can be used to add padding with zeros from the left.
  3211. @item gmtime
  3212. The time at which the filter is running, expressed in UTC.
  3213. It can accept an argument: a strftime() format string.
  3214. @item localtime
  3215. The time at which the filter is running, expressed in the local time zone.
  3216. It can accept an argument: a strftime() format string.
  3217. @item metadata
  3218. Frame metadata. It must take one argument specifying metadata key.
  3219. @item n, frame_num
  3220. The frame number, starting from 0.
  3221. @item pict_type
  3222. A 1 character description of the current picture type.
  3223. @item pts
  3224. The timestamp of the current frame.
  3225. It can take up to two arguments.
  3226. The first argument is the format of the timestamp; it defaults to @code{flt}
  3227. for seconds as a decimal number with microsecond accuracy; @code{hms} stands
  3228. for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
  3229. The second argument is an offset added to the timestamp.
  3230. @end table
  3231. @subsection Examples
  3232. @itemize
  3233. @item
  3234. Draw "Test Text" with font FreeSerif, using the default values for the
  3235. optional parameters.
  3236. @example
  3237. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
  3238. @end example
  3239. @item
  3240. Draw 'Test Text' with font FreeSerif of size 24 at position x=100
  3241. and y=50 (counting from the top-left corner of the screen), text is
  3242. yellow with a red box around it. Both the text and the box have an
  3243. opacity of 20%.
  3244. @example
  3245. drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
  3246. x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
  3247. @end example
  3248. Note that the double quotes are not necessary if spaces are not used
  3249. within the parameter list.
  3250. @item
  3251. Show the text at the center of the video frame:
  3252. @example
  3253. drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
  3254. @end example
  3255. @item
  3256. Show a text line sliding from right to left in the last row of the video
  3257. frame. The file @file{LONG_LINE} is assumed to contain a single line
  3258. with no newlines.
  3259. @example
  3260. drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
  3261. @end example
  3262. @item
  3263. Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
  3264. @example
  3265. drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
  3266. @end example
  3267. @item
  3268. Draw a single green letter "g", at the center of the input video.
  3269. The glyph baseline is placed at half screen height.
  3270. @example
  3271. drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
  3272. @end example
  3273. @item
  3274. Show text for 1 second every 3 seconds:
  3275. @example
  3276. drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
  3277. @end example
  3278. @item
  3279. Use fontconfig to set the font. Note that the colons need to be escaped.
  3280. @example
  3281. drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
  3282. @end example
  3283. @item
  3284. Print the date of a real-time encoding (see strftime(3)):
  3285. @example
  3286. drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
  3287. @end example
  3288. @item
  3289. Show text fading in and out (appearing/disappearing):
  3290. @example
  3291. #!/bin/sh
  3292. DS=1.0 # display start
  3293. DE=10.0 # display end
  3294. FID=1.5 # fade in duration
  3295. FOD=5 # fade out duration
  3296. 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 @}"
  3297. @end example
  3298. @end itemize
  3299. For more information about libfreetype, check:
  3300. @url{http://www.freetype.org/}.
  3301. For more information about fontconfig, check:
  3302. @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
  3303. For more information about libfribidi, check:
  3304. @url{http://fribidi.org/}.
  3305. @section edgedetect
  3306. Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
  3307. The filter accepts the following options:
  3308. @table @option
  3309. @item low
  3310. @item high
  3311. Set low and high threshold values used by the Canny thresholding
  3312. algorithm.
  3313. The high threshold selects the "strong" edge pixels, which are then
  3314. connected through 8-connectivity with the "weak" edge pixels selected
  3315. by the low threshold.
  3316. @var{low} and @var{high} threshold values must be chosen in the range
  3317. [0,1], and @var{low} should be lesser or equal to @var{high}.
  3318. Default value for @var{low} is @code{20/255}, and default value for @var{high}
  3319. is @code{50/255}.
  3320. @item mode
  3321. Define the drawing mode.
  3322. @table @samp
  3323. @item wires
  3324. Draw white/gray wires on black background.
  3325. @item colormix
  3326. Mix the colors to create a paint/cartoon effect.
  3327. @end table
  3328. Default value is @var{wires}.
  3329. @end table
  3330. @subsection Examples
  3331. @itemize
  3332. @item
  3333. Standard edge detection with custom values for the hysteresis thresholding:
  3334. @example
  3335. edgedetect=low=0.1:high=0.4
  3336. @end example
  3337. @item
  3338. Painting effect without thresholding:
  3339. @example
  3340. edgedetect=mode=colormix:high=0
  3341. @end example
  3342. @end itemize
  3343. @section eq
  3344. Set brightness, contrast, saturation and approximate gamma adjustment.
  3345. The filter accepts the following options:
  3346. @table @option
  3347. @item contrast
  3348. Set the contrast value. It accepts a float value in range @code{-2.0} to
  3349. @code{2.0}. The default value is @code{0.0}.
  3350. @item brightness
  3351. Set the brightness value. It accepts a float value in range @code{-1.0} to
  3352. @code{1.0}. The default value is @code{0.0}.
  3353. @item saturation
  3354. Set the saturation value. It accepts a float value in range @code{0.0} to
  3355. @code{3.0}. The default value is @code{1.0}.
  3356. @item gamma
  3357. Set the gamma value. It accepts a float value in range @code{0.1} to @code{10.0}.
  3358. The default value is @code{1.0}.
  3359. @item gamma_r
  3360. Set the gamma value for red. It accepts a float value in range
  3361. @code{0.1} to @code{10.0}. The default value is @code{1.0}.
  3362. @item gamma_g
  3363. Set the gamma value for green. It accepts a float value in range
  3364. @code{0.1} to @code{10.0}. The default value is @code{1.0}.
  3365. @item gamma_b
  3366. Set the gamma value for blue. It accepts a float value in range
  3367. @code{0.1} to @code{10.0}. The default value is @code{1.0}.
  3368. @item gamma_weight
  3369. Can be used to reduce the effect of a high gamma value on bright image areas,
  3370. e.g. keep them from getting overamplified and just plain white. It accepts a
  3371. float value in range @code{0.0} to @code{1.0}.A value of @code{0.0} turns the
  3372. gamma correction all the way down while @code{1.0} leaves it at its full strength.
  3373. Default is @code{1.0}.
  3374. @end table
  3375. @section extractplanes
  3376. Extract color channel components from input video stream into
  3377. separate grayscale video streams.
  3378. The filter accepts the following option:
  3379. @table @option
  3380. @item planes
  3381. Set plane(s) to extract.
  3382. Available values for planes are:
  3383. @table @samp
  3384. @item y
  3385. @item u
  3386. @item v
  3387. @item a
  3388. @item r
  3389. @item g
  3390. @item b
  3391. @end table
  3392. Choosing planes not available in the input will result in an error.
  3393. That means you cannot select @code{r}, @code{g}, @code{b} planes
  3394. with @code{y}, @code{u}, @code{v} planes at same time.
  3395. @end table
  3396. @subsection Examples
  3397. @itemize
  3398. @item
  3399. Extract luma, u and v color channel component from input video frame
  3400. into 3 grayscale outputs:
  3401. @example
  3402. 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
  3403. @end example
  3404. @end itemize
  3405. @section elbg
  3406. Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
  3407. For each input image, the filter will compute the optimal mapping from
  3408. the input to the output given the codebook length, that is the number
  3409. of distinct output colors.
  3410. This filter accepts the following options.
  3411. @table @option
  3412. @item codebook_length, l
  3413. Set codebook length. The value must be a positive integer, and
  3414. represents the number of distinct output colors. Default value is 256.
  3415. @item nb_steps, n
  3416. Set the maximum number of iterations to apply for computing the optimal
  3417. mapping. The higher the value the better the result and the higher the
  3418. computation time. Default value is 1.
  3419. @item seed, s
  3420. Set a random seed, must be an integer included between 0 and
  3421. UINT32_MAX. If not specified, or if explicitly set to -1, the filter
  3422. will try to use a good random seed on a best effort basis.
  3423. @end table
  3424. @section fade
  3425. Apply a fade-in/out effect to the input video.
  3426. It accepts the following parameters:
  3427. @table @option
  3428. @item type, t
  3429. The effect type can be either "in" for a fade-in, or "out" for a fade-out
  3430. effect.
  3431. Default is @code{in}.
  3432. @item start_frame, s
  3433. Specify the number of the frame to start applying the fade
  3434. effect at. Default is 0.
  3435. @item nb_frames, n
  3436. The number of frames that the fade effect lasts. At the end of the
  3437. fade-in effect, the output video will have the same intensity as the input video.
  3438. At the end of the fade-out transition, the output video will be filled with the
  3439. selected @option{color}.
  3440. Default is 25.
  3441. @item alpha
  3442. If set to 1, fade only alpha channel, if one exists on the input.
  3443. Default value is 0.
  3444. @item start_time, st
  3445. Specify the timestamp (in seconds) of the frame to start to apply the fade
  3446. effect. If both start_frame and start_time are specified, the fade will start at
  3447. whichever comes last. Default is 0.
  3448. @item duration, d
  3449. The number of seconds for which the fade effect has to last. At the end of the
  3450. fade-in effect the output video will have the same intensity as the input video,
  3451. at the end of the fade-out transition the output video will be filled with the
  3452. selected @option{color}.
  3453. If both duration and nb_frames are specified, duration is used. Default is 0.
  3454. @item color, c
  3455. Specify the color of the fade. Default is "black".
  3456. @end table
  3457. @subsection Examples
  3458. @itemize
  3459. @item
  3460. Fade in the first 30 frames of video:
  3461. @example
  3462. fade=in:0:30
  3463. @end example
  3464. The command above is equivalent to:
  3465. @example
  3466. fade=t=in:s=0:n=30
  3467. @end example
  3468. @item
  3469. Fade out the last 45 frames of a 200-frame video:
  3470. @example
  3471. fade=out:155:45
  3472. fade=type=out:start_frame=155:nb_frames=45
  3473. @end example
  3474. @item
  3475. Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
  3476. @example
  3477. fade=in:0:25, fade=out:975:25
  3478. @end example
  3479. @item
  3480. Make the first 5 frames yellow, then fade in from frame 5-24:
  3481. @example
  3482. fade=in:5:20:color=yellow
  3483. @end example
  3484. @item
  3485. Fade in alpha over first 25 frames of video:
  3486. @example
  3487. fade=in:0:25:alpha=1
  3488. @end example
  3489. @item
  3490. Make the first 5.5 seconds black, then fade in for 0.5 seconds:
  3491. @example
  3492. fade=t=in:st=5.5:d=0.5
  3493. @end example
  3494. @end itemize
  3495. @section field
  3496. Extract a single field from an interlaced image using stride
  3497. arithmetic to avoid wasting CPU time. The output frames are marked as
  3498. non-interlaced.
  3499. The filter accepts the following options:
  3500. @table @option
  3501. @item type
  3502. Specify whether to extract the top (if the value is @code{0} or
  3503. @code{top}) or the bottom field (if the value is @code{1} or
  3504. @code{bottom}).
  3505. @end table
  3506. @section fieldmatch
  3507. Field matching filter for inverse telecine. It is meant to reconstruct the
  3508. progressive frames from a telecined stream. The filter does not drop duplicated
  3509. frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
  3510. followed by a decimation filter such as @ref{decimate} in the filtergraph.
  3511. The separation of the field matching and the decimation is notably motivated by
  3512. the possibility of inserting a de-interlacing filter fallback between the two.
  3513. If the source has mixed telecined and real interlaced content,
  3514. @code{fieldmatch} will not be able to match fields for the interlaced parts.
  3515. But these remaining combed frames will be marked as interlaced, and thus can be
  3516. de-interlaced by a later filter such as @ref{yadif} before decimation.
  3517. In addition to the various configuration options, @code{fieldmatch} can take an
  3518. optional second stream, activated through the @option{ppsrc} option. If
  3519. enabled, the frames reconstruction will be based on the fields and frames from
  3520. this second stream. This allows the first input to be pre-processed in order to
  3521. help the various algorithms of the filter, while keeping the output lossless
  3522. (assuming the fields are matched properly). Typically, a field-aware denoiser,
  3523. or brightness/contrast adjustments can help.
  3524. Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
  3525. and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
  3526. which @code{fieldmatch} is based on. While the semantic and usage are very
  3527. close, some behaviour and options names can differ.
  3528. The @ref{decimate} filter currently only works for constant frame rate input.
  3529. Do not use @code{fieldmatch} and @ref{decimate} if your input has mixed
  3530. telecined and progressive content with changing framerate.
  3531. The filter accepts the following options:
  3532. @table @option
  3533. @item order
  3534. Specify the assumed field order of the input stream. Available values are:
  3535. @table @samp
  3536. @item auto
  3537. Auto detect parity (use FFmpeg's internal parity value).
  3538. @item bff
  3539. Assume bottom field first.
  3540. @item tff
  3541. Assume top field first.
  3542. @end table
  3543. Note that it is sometimes recommended not to trust the parity announced by the
  3544. stream.
  3545. Default value is @var{auto}.
  3546. @item mode
  3547. Set the matching mode or strategy to use. @option{pc} mode is the safest in the
  3548. sense that it won't risk creating jerkiness due to duplicate frames when
  3549. possible, but if there are bad edits or blended fields it will end up
  3550. outputting combed frames when a good match might actually exist. On the other
  3551. hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
  3552. but will almost always find a good frame if there is one. The other values are
  3553. all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
  3554. jerkiness and creating duplicate frames versus finding good matches in sections
  3555. with bad edits, orphaned fields, blended fields, etc.
  3556. More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
  3557. Available values are:
  3558. @table @samp
  3559. @item pc
  3560. 2-way matching (p/c)
  3561. @item pc_n
  3562. 2-way matching, and trying 3rd match if still combed (p/c + n)
  3563. @item pc_u
  3564. 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
  3565. @item pc_n_ub
  3566. 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
  3567. still combed (p/c + n + u/b)
  3568. @item pcn
  3569. 3-way matching (p/c/n)
  3570. @item pcn_ub
  3571. 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
  3572. detected as combed (p/c/n + u/b)
  3573. @end table
  3574. The parenthesis at the end indicate the matches that would be used for that
  3575. mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
  3576. @var{top}).
  3577. In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
  3578. the slowest.
  3579. Default value is @var{pc_n}.
  3580. @item ppsrc
  3581. Mark the main input stream as a pre-processed input, and enable the secondary
  3582. input stream as the clean source to pick the fields from. See the filter
  3583. introduction for more details. It is similar to the @option{clip2} feature from
  3584. VFM/TFM.
  3585. Default value is @code{0} (disabled).
  3586. @item field
  3587. Set the field to match from. It is recommended to set this to the same value as
  3588. @option{order} unless you experience matching failures with that setting. In
  3589. certain circumstances changing the field that is used to match from can have a
  3590. large impact on matching performance. Available values are:
  3591. @table @samp
  3592. @item auto
  3593. Automatic (same value as @option{order}).
  3594. @item bottom
  3595. Match from the bottom field.
  3596. @item top
  3597. Match from the top field.
  3598. @end table
  3599. Default value is @var{auto}.
  3600. @item mchroma
  3601. Set whether or not chroma is included during the match comparisons. In most
  3602. cases it is recommended to leave this enabled. You should set this to @code{0}
  3603. only if your clip has bad chroma problems such as heavy rainbowing or other
  3604. artifacts. Setting this to @code{0} could also be used to speed things up at
  3605. the cost of some accuracy.
  3606. Default value is @code{1}.
  3607. @item y0
  3608. @item y1
  3609. These define an exclusion band which excludes the lines between @option{y0} and
  3610. @option{y1} from being included in the field matching decision. An exclusion
  3611. band can be used to ignore subtitles, a logo, or other things that may
  3612. interfere with the matching. @option{y0} sets the starting scan line and
  3613. @option{y1} sets the ending line; all lines in between @option{y0} and
  3614. @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
  3615. @option{y0} and @option{y1} to the same value will disable the feature.
  3616. @option{y0} and @option{y1} defaults to @code{0}.
  3617. @item scthresh
  3618. Set the scene change detection threshold as a percentage of maximum change on
  3619. the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
  3620. detection is only relevant in case @option{combmatch}=@var{sc}. The range for
  3621. @option{scthresh} is @code{[0.0, 100.0]}.
  3622. Default value is @code{12.0}.
  3623. @item combmatch
  3624. When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
  3625. account the combed scores of matches when deciding what match to use as the
  3626. final match. Available values are:
  3627. @table @samp
  3628. @item none
  3629. No final matching based on combed scores.
  3630. @item sc
  3631. Combed scores are only used when a scene change is detected.
  3632. @item full
  3633. Use combed scores all the time.
  3634. @end table
  3635. Default is @var{sc}.
  3636. @item combdbg
  3637. Force @code{fieldmatch} to calculate the combed metrics for certain matches and
  3638. print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
  3639. Available values are:
  3640. @table @samp
  3641. @item none
  3642. No forced calculation.
  3643. @item pcn
  3644. Force p/c/n calculations.
  3645. @item pcnub
  3646. Force p/c/n/u/b calculations.
  3647. @end table
  3648. Default value is @var{none}.
  3649. @item cthresh
  3650. This is the area combing threshold used for combed frame detection. This
  3651. essentially controls how "strong" or "visible" combing must be to be detected.
  3652. Larger values mean combing must be more visible and smaller values mean combing
  3653. can be less visible or strong and still be detected. Valid settings are from
  3654. @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
  3655. be detected as combed). This is basically a pixel difference value. A good
  3656. range is @code{[8, 12]}.
  3657. Default value is @code{9}.
  3658. @item chroma
  3659. Sets whether or not chroma is considered in the combed frame decision. Only
  3660. disable this if your source has chroma problems (rainbowing, etc.) that are
  3661. causing problems for the combed frame detection with chroma enabled. Actually,
  3662. using @option{chroma}=@var{0} is usually more reliable, except for the case
  3663. where there is chroma only combing in the source.
  3664. Default value is @code{0}.
  3665. @item blockx
  3666. @item blocky
  3667. Respectively set the x-axis and y-axis size of the window used during combed
  3668. frame detection. This has to do with the size of the area in which
  3669. @option{combpel} pixels are required to be detected as combed for a frame to be
  3670. declared combed. See the @option{combpel} parameter description for more info.
  3671. Possible values are any number that is a power of 2 starting at 4 and going up
  3672. to 512.
  3673. Default value is @code{16}.
  3674. @item combpel
  3675. The number of combed pixels inside any of the @option{blocky} by
  3676. @option{blockx} size blocks on the frame for the frame to be detected as
  3677. combed. While @option{cthresh} controls how "visible" the combing must be, this
  3678. setting controls "how much" combing there must be in any localized area (a
  3679. window defined by the @option{blockx} and @option{blocky} settings) on the
  3680. frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
  3681. which point no frames will ever be detected as combed). This setting is known
  3682. as @option{MI} in TFM/VFM vocabulary.
  3683. Default value is @code{80}.
  3684. @end table
  3685. @anchor{p/c/n/u/b meaning}
  3686. @subsection p/c/n/u/b meaning
  3687. @subsubsection p/c/n
  3688. We assume the following telecined stream:
  3689. @example
  3690. Top fields: 1 2 2 3 4
  3691. Bottom fields: 1 2 3 4 4
  3692. @end example
  3693. The numbers correspond to the progressive frame the fields relate to. Here, the
  3694. first two frames are progressive, the 3rd and 4th are combed, and so on.
  3695. When @code{fieldmatch} is configured to run a matching from bottom
  3696. (@option{field}=@var{bottom}) this is how this input stream get transformed:
  3697. @example
  3698. Input stream:
  3699. T 1 2 2 3 4
  3700. B 1 2 3 4 4 <-- matching reference
  3701. Matches: c c n n c
  3702. Output stream:
  3703. T 1 2 3 4 4
  3704. B 1 2 3 4 4
  3705. @end example
  3706. As a result of the field matching, we can see that some frames get duplicated.
  3707. To perform a complete inverse telecine, you need to rely on a decimation filter
  3708. after this operation. See for instance the @ref{decimate} filter.
  3709. The same operation now matching from top fields (@option{field}=@var{top})
  3710. looks like this:
  3711. @example
  3712. Input stream:
  3713. T 1 2 2 3 4 <-- matching reference
  3714. B 1 2 3 4 4
  3715. Matches: c c p p c
  3716. Output stream:
  3717. T 1 2 2 3 4
  3718. B 1 2 2 3 4
  3719. @end example
  3720. In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
  3721. basically, they refer to the frame and field of the opposite parity:
  3722. @itemize
  3723. @item @var{p} matches the field of the opposite parity in the previous frame
  3724. @item @var{c} matches the field of the opposite parity in the current frame
  3725. @item @var{n} matches the field of the opposite parity in the next frame
  3726. @end itemize
  3727. @subsubsection u/b
  3728. The @var{u} and @var{b} matching are a bit special in the sense that they match
  3729. from the opposite parity flag. In the following examples, we assume that we are
  3730. currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
  3731. 'x' is placed above and below each matched fields.
  3732. With bottom matching (@option{field}=@var{bottom}):
  3733. @example
  3734. Match: c p n b u
  3735. x x x x x
  3736. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  3737. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  3738. x x x x x
  3739. Output frames:
  3740. 2 1 2 2 2
  3741. 2 2 2 1 3
  3742. @end example
  3743. With top matching (@option{field}=@var{top}):
  3744. @example
  3745. Match: c p n b u
  3746. x x x x x
  3747. Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
  3748. Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
  3749. x x x x x
  3750. Output frames:
  3751. 2 2 2 1 2
  3752. 2 1 3 2 2
  3753. @end example
  3754. @subsection Examples
  3755. Simple IVTC of a top field first telecined stream:
  3756. @example
  3757. fieldmatch=order=tff:combmatch=none, decimate
  3758. @end example
  3759. Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
  3760. @example
  3761. fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
  3762. @end example
  3763. @section fieldorder
  3764. Transform the field order of the input video.
  3765. It accepts the following parameters:
  3766. @table @option
  3767. @item order
  3768. The output field order. Valid values are @var{tff} for top field first or @var{bff}
  3769. for bottom field first.
  3770. @end table
  3771. The default value is @samp{tff}.
  3772. The transformation is done by shifting the picture content up or down
  3773. by one line, and filling the remaining line with appropriate picture content.
  3774. This method is consistent with most broadcast field order converters.
  3775. If the input video is not flagged as being interlaced, or it is already
  3776. flagged as being of the required output field order, then this filter does
  3777. not alter the incoming video.
  3778. It is very useful when converting to or from PAL DV material,
  3779. which is bottom field first.
  3780. For example:
  3781. @example
  3782. ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
  3783. @end example
  3784. @section fifo
  3785. Buffer input images and send them when they are requested.
  3786. It is mainly useful when auto-inserted by the libavfilter
  3787. framework.
  3788. It does not take parameters.
  3789. @anchor{format}
  3790. @section format
  3791. Convert the input video to one of the specified pixel formats.
  3792. Libavfilter will try to pick one that is suitable as input to
  3793. the next filter.
  3794. It accepts the following parameters:
  3795. @table @option
  3796. @item pix_fmts
  3797. A '|'-separated list of pixel format names, such as
  3798. "pix_fmts=yuv420p|monow|rgb24".
  3799. @end table
  3800. @subsection Examples
  3801. @itemize
  3802. @item
  3803. Convert the input video to the @var{yuv420p} format
  3804. @example
  3805. format=pix_fmts=yuv420p
  3806. @end example
  3807. Convert the input video to any of the formats in the list
  3808. @example
  3809. format=pix_fmts=yuv420p|yuv444p|yuv410p
  3810. @end example
  3811. @end itemize
  3812. @anchor{fps}
  3813. @section fps
  3814. Convert the video to specified constant frame rate by duplicating or dropping
  3815. frames as necessary.
  3816. It accepts the following parameters:
  3817. @table @option
  3818. @item fps
  3819. The desired output frame rate. The default is @code{25}.
  3820. @item round
  3821. Rounding method.
  3822. Possible values are:
  3823. @table @option
  3824. @item zero
  3825. zero round towards 0
  3826. @item inf
  3827. round away from 0
  3828. @item down
  3829. round towards -infinity
  3830. @item up
  3831. round towards +infinity
  3832. @item near
  3833. round to nearest
  3834. @end table
  3835. The default is @code{near}.
  3836. @item start_time
  3837. Assume the first PTS should be the given value, in seconds. This allows for
  3838. padding/trimming at the start of stream. By default, no assumption is made
  3839. about the first frame's expected PTS, so no padding or trimming is done.
  3840. For example, this could be set to 0 to pad the beginning with duplicates of
  3841. the first frame if a video stream starts after the audio stream or to trim any
  3842. frames with a negative PTS.
  3843. @end table
  3844. Alternatively, the options can be specified as a flat string:
  3845. @var{fps}[:@var{round}].
  3846. See also the @ref{setpts} filter.
  3847. @subsection Examples
  3848. @itemize
  3849. @item
  3850. A typical usage in order to set the fps to 25:
  3851. @example
  3852. fps=fps=25
  3853. @end example
  3854. @item
  3855. Sets the fps to 24, using abbreviation and rounding method to round to nearest:
  3856. @example
  3857. fps=fps=film:round=near
  3858. @end example
  3859. @end itemize
  3860. @section framepack
  3861. Pack two different video streams into a stereoscopic video, setting proper
  3862. metadata on supported codecs. The two views should have the same size and
  3863. framerate and processing will stop when the shorter video ends. Please note
  3864. that you may conveniently adjust view properties with the @ref{scale} and
  3865. @ref{fps} filters.
  3866. It accepts the following parameters:
  3867. @table @option
  3868. @item format
  3869. The desired packing format. Supported values are:
  3870. @table @option
  3871. @item sbs
  3872. The views are next to each other (default).
  3873. @item tab
  3874. The views are on top of each other.
  3875. @item lines
  3876. The views are packed by line.
  3877. @item columns
  3878. The views are packed by column.
  3879. @item frameseq
  3880. The views are temporally interleaved.
  3881. @end table
  3882. @end table
  3883. Some examples:
  3884. @example
  3885. # Convert left and right views into a frame-sequential video
  3886. ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
  3887. # Convert views into a side-by-side video with the same output resolution as the input
  3888. 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
  3889. @end example
  3890. @section framestep
  3891. Select one frame every N-th frame.
  3892. This filter accepts the following option:
  3893. @table @option
  3894. @item step
  3895. Select frame after every @code{step} frames.
  3896. Allowed values are positive integers higher than 0. Default value is @code{1}.
  3897. @end table
  3898. @anchor{frei0r}
  3899. @section frei0r
  3900. Apply a frei0r effect to the input video.
  3901. To enable the compilation of this filter, you need to install the frei0r
  3902. header and configure FFmpeg with @code{--enable-frei0r}.
  3903. It accepts the following parameters:
  3904. @table @option
  3905. @item filter_name
  3906. The name of the frei0r effect to load. If the environment variable
  3907. @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
  3908. directories specified by the colon-separated list in @env{FREIOR_PATH}.
  3909. Otherwise, the standard frei0r paths are searched, in this order:
  3910. @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
  3911. @file{/usr/lib/frei0r-1/}.
  3912. @item filter_params
  3913. A '|'-separated list of parameters to pass to the frei0r effect.
  3914. @end table
  3915. A frei0r effect parameter can be a boolean (its value is either
  3916. "y" or "n"), a double, a color (specified as
  3917. @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
  3918. numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color"
  3919. section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where
  3920. @var{X} and @var{Y} are floating point numbers) and/or a string.
  3921. The number and types of parameters depend on the loaded effect. If an
  3922. effect parameter is not specified, the default value is set.
  3923. @subsection Examples
  3924. @itemize
  3925. @item
  3926. Apply the distort0r effect, setting the first two double parameters:
  3927. @example
  3928. frei0r=filter_name=distort0r:filter_params=0.5|0.01
  3929. @end example
  3930. @item
  3931. Apply the colordistance effect, taking a color as the first parameter:
  3932. @example
  3933. frei0r=colordistance:0.2/0.3/0.4
  3934. frei0r=colordistance:violet
  3935. frei0r=colordistance:0x112233
  3936. @end example
  3937. @item
  3938. Apply the perspective effect, specifying the top left and top right image
  3939. positions:
  3940. @example
  3941. frei0r=perspective:0.2/0.2|0.8/0.2
  3942. @end example
  3943. @end itemize
  3944. For more information, see
  3945. @url{http://frei0r.dyne.org}
  3946. @section fspp
  3947. Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
  3948. It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
  3949. processing filter, one of them is performed once per block, not per pixel.
  3950. This allows for much higher speed.
  3951. The filter accepts the following options:
  3952. @table @option
  3953. @item quality
  3954. Set quality. This option defines the number of levels for averaging. It accepts
  3955. an integer in the range 4-5. Default value is @code{4}.
  3956. @item qp
  3957. Force a constant quantization parameter. It accepts an integer in range 0-63.
  3958. If not set, the filter will use the QP from the video stream (if available).
  3959. @item strength
  3960. Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
  3961. more details but also more artifacts, while higher values make the image smoother
  3962. but also blurrier. Default value is @code{0} − PSNR optimal.
  3963. @item use_bframe_qp
  3964. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  3965. option may cause flicker since the B-Frames have often larger QP. Default is
  3966. @code{0} (not enabled).
  3967. @end table
  3968. @section geq
  3969. The filter accepts the following options:
  3970. @table @option
  3971. @item lum_expr, lum
  3972. Set the luminance expression.
  3973. @item cb_expr, cb
  3974. Set the chrominance blue expression.
  3975. @item cr_expr, cr
  3976. Set the chrominance red expression.
  3977. @item alpha_expr, a
  3978. Set the alpha expression.
  3979. @item red_expr, r
  3980. Set the red expression.
  3981. @item green_expr, g
  3982. Set the green expression.
  3983. @item blue_expr, b
  3984. Set the blue expression.
  3985. @end table
  3986. The colorspace is selected according to the specified options. If one
  3987. of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
  3988. options is specified, the filter will automatically select a YCbCr
  3989. colorspace. If one of the @option{red_expr}, @option{green_expr}, or
  3990. @option{blue_expr} options is specified, it will select an RGB
  3991. colorspace.
  3992. If one of the chrominance expression is not defined, it falls back on the other
  3993. one. If no alpha expression is specified it will evaluate to opaque value.
  3994. If none of chrominance expressions are specified, they will evaluate
  3995. to the luminance expression.
  3996. The expressions can use the following variables and functions:
  3997. @table @option
  3998. @item N
  3999. The sequential number of the filtered frame, starting from @code{0}.
  4000. @item X
  4001. @item Y
  4002. The coordinates of the current sample.
  4003. @item W
  4004. @item H
  4005. The width and height of the image.
  4006. @item SW
  4007. @item SH
  4008. Width and height scale depending on the currently filtered plane. It is the
  4009. ratio between the corresponding luma plane number of pixels and the current
  4010. plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
  4011. @code{0.5,0.5} for chroma planes.
  4012. @item T
  4013. Time of the current frame, expressed in seconds.
  4014. @item p(x, y)
  4015. Return the value of the pixel at location (@var{x},@var{y}) of the current
  4016. plane.
  4017. @item lum(x, y)
  4018. Return the value of the pixel at location (@var{x},@var{y}) of the luminance
  4019. plane.
  4020. @item cb(x, y)
  4021. Return the value of the pixel at location (@var{x},@var{y}) of the
  4022. blue-difference chroma plane. Return 0 if there is no such plane.
  4023. @item cr(x, y)
  4024. Return the value of the pixel at location (@var{x},@var{y}) of the
  4025. red-difference chroma plane. Return 0 if there is no such plane.
  4026. @item r(x, y)
  4027. @item g(x, y)
  4028. @item b(x, y)
  4029. Return the value of the pixel at location (@var{x},@var{y}) of the
  4030. red/green/blue component. Return 0 if there is no such component.
  4031. @item alpha(x, y)
  4032. Return the value of the pixel at location (@var{x},@var{y}) of the alpha
  4033. plane. Return 0 if there is no such plane.
  4034. @end table
  4035. For functions, if @var{x} and @var{y} are outside the area, the value will be
  4036. automatically clipped to the closer edge.
  4037. @subsection Examples
  4038. @itemize
  4039. @item
  4040. Flip the image horizontally:
  4041. @example
  4042. geq=p(W-X\,Y)
  4043. @end example
  4044. @item
  4045. Generate a bidimensional sine wave, with angle @code{PI/3} and a
  4046. wavelength of 100 pixels:
  4047. @example
  4048. geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
  4049. @end example
  4050. @item
  4051. Generate a fancy enigmatic moving light:
  4052. @example
  4053. 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
  4054. @end example
  4055. @item
  4056. Generate a quick emboss effect:
  4057. @example
  4058. format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
  4059. @end example
  4060. @item
  4061. Modify RGB components depending on pixel position:
  4062. @example
  4063. geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
  4064. @end example
  4065. @item
  4066. Create a radial gradient that is the same size as the input (also see
  4067. the @ref{vignette} filter):
  4068. @example
  4069. geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
  4070. @end example
  4071. @item
  4072. Create a linear gradient to use as a mask for another filter, then
  4073. compose with @ref{overlay}. In this example the video will gradually
  4074. become more blurry from the top to the bottom of the y-axis as defined
  4075. by the linear gradient:
  4076. @example
  4077. ffmpeg -i input.mp4 -filter_complex "geq=lum=255*(Y/H),format=gray[grad];[0:v]boxblur=4[blur];[blur][grad]alphamerge[alpha];[0:v][alpha]overlay" output.mp4
  4078. @end example
  4079. @end itemize
  4080. @section gradfun
  4081. Fix the banding artifacts that are sometimes introduced into nearly flat
  4082. regions by truncation to 8bit color depth.
  4083. Interpolate the gradients that should go where the bands are, and
  4084. dither them.
  4085. It is designed for playback only. Do not use it prior to
  4086. lossy compression, because compression tends to lose the dither and
  4087. bring back the bands.
  4088. It accepts the following parameters:
  4089. @table @option
  4090. @item strength
  4091. The maximum amount by which the filter will change any one pixel. This is also
  4092. the threshold for detecting nearly flat regions. Acceptable values range from
  4093. .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
  4094. valid range.
  4095. @item radius
  4096. The neighborhood to fit the gradient to. A larger radius makes for smoother
  4097. gradients, but also prevents the filter from modifying the pixels near detailed
  4098. regions. Acceptable values are 8-32; the default value is 16. Out-of-range
  4099. values will be clipped to the valid range.
  4100. @end table
  4101. Alternatively, the options can be specified as a flat string:
  4102. @var{strength}[:@var{radius}]
  4103. @subsection Examples
  4104. @itemize
  4105. @item
  4106. Apply the filter with a @code{3.5} strength and radius of @code{8}:
  4107. @example
  4108. gradfun=3.5:8
  4109. @end example
  4110. @item
  4111. Specify radius, omitting the strength (which will fall-back to the default
  4112. value):
  4113. @example
  4114. gradfun=radius=8
  4115. @end example
  4116. @end itemize
  4117. @anchor{haldclut}
  4118. @section haldclut
  4119. Apply a Hald CLUT to a video stream.
  4120. First input is the video stream to process, and second one is the Hald CLUT.
  4121. The Hald CLUT input can be a simple picture or a complete video stream.
  4122. The filter accepts the following options:
  4123. @table @option
  4124. @item shortest
  4125. Force termination when the shortest input terminates. Default is @code{0}.
  4126. @item repeatlast
  4127. Continue applying the last CLUT after the end of the stream. A value of
  4128. @code{0} disable the filter after the last frame of the CLUT is reached.
  4129. Default is @code{1}.
  4130. @end table
  4131. @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
  4132. filters share the same internals).
  4133. More information about the Hald CLUT can be found on Eskil Steenberg's website
  4134. (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
  4135. @subsection Workflow examples
  4136. @subsubsection Hald CLUT video stream
  4137. Generate an identity Hald CLUT stream altered with various effects:
  4138. @example
  4139. 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
  4140. @end example
  4141. Note: make sure you use a lossless codec.
  4142. Then use it with @code{haldclut} to apply it on some random stream:
  4143. @example
  4144. ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
  4145. @end example
  4146. The Hald CLUT will be applied to the 10 first seconds (duration of
  4147. @file{clut.nut}), then the latest picture of that CLUT stream will be applied
  4148. to the remaining frames of the @code{mandelbrot} stream.
  4149. @subsubsection Hald CLUT with preview
  4150. A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
  4151. @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
  4152. biggest possible square starting at the top left of the picture. The remaining
  4153. padding pixels (bottom or right) will be ignored. This area can be used to add
  4154. a preview of the Hald CLUT.
  4155. Typically, the following generated Hald CLUT will be supported by the
  4156. @code{haldclut} filter:
  4157. @example
  4158. ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
  4159. pad=iw+320 [padded_clut];
  4160. smptebars=s=320x256, split [a][b];
  4161. [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
  4162. [main][b] overlay=W-320" -frames:v 1 clut.png
  4163. @end example
  4164. It contains the original and a preview of the effect of the CLUT: SMPTE color
  4165. bars are displayed on the right-top, and below the same color bars processed by
  4166. the color changes.
  4167. Then, the effect of this Hald CLUT can be visualized with:
  4168. @example
  4169. ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
  4170. @end example
  4171. @section hflip
  4172. Flip the input video horizontally.
  4173. For example, to horizontally flip the input video with @command{ffmpeg}:
  4174. @example
  4175. ffmpeg -i in.avi -vf "hflip" out.avi
  4176. @end example
  4177. @section histeq
  4178. This filter applies a global color histogram equalization on a
  4179. per-frame basis.
  4180. It can be used to correct video that has a compressed range of pixel
  4181. intensities. The filter redistributes the pixel intensities to
  4182. equalize their distribution across the intensity range. It may be
  4183. viewed as an "automatically adjusting contrast filter". This filter is
  4184. useful only for correcting degraded or poorly captured source
  4185. video.
  4186. The filter accepts the following options:
  4187. @table @option
  4188. @item strength
  4189. Determine the amount of equalization to be applied. As the strength
  4190. is reduced, the distribution of pixel intensities more-and-more
  4191. approaches that of the input frame. The value must be a float number
  4192. in the range [0,1] and defaults to 0.200.
  4193. @item intensity
  4194. Set the maximum intensity that can generated and scale the output
  4195. values appropriately. The strength should be set as desired and then
  4196. the intensity can be limited if needed to avoid washing-out. The value
  4197. must be a float number in the range [0,1] and defaults to 0.210.
  4198. @item antibanding
  4199. Set the antibanding level. If enabled the filter will randomly vary
  4200. the luminance of output pixels by a small amount to avoid banding of
  4201. the histogram. Possible values are @code{none}, @code{weak} or
  4202. @code{strong}. It defaults to @code{none}.
  4203. @end table
  4204. @section histogram
  4205. Compute and draw a color distribution histogram for the input video.
  4206. The computed histogram is a representation of the color component
  4207. distribution in an image.
  4208. The filter accepts the following options:
  4209. @table @option
  4210. @item mode
  4211. Set histogram mode.
  4212. It accepts the following values:
  4213. @table @samp
  4214. @item levels
  4215. Standard histogram that displays the color components distribution in an
  4216. image. Displays color graph for each color component. Shows distribution of
  4217. the Y, U, V, A or R, G, B components, depending on input format, in the
  4218. current frame. Below each graph a color component scale meter is shown.
  4219. @item color
  4220. Displays chroma values (U/V color placement) in a two dimensional
  4221. graph (which is called a vectorscope). The brighter a pixel in the
  4222. vectorscope, the more pixels of the input frame correspond to that pixel
  4223. (i.e., more pixels have this chroma value). The V component is displayed on
  4224. the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost
  4225. side being V = 255. The U component is displayed on the vertical (Y) axis,
  4226. with the top representing U = 0 and the bottom representing U = 255.
  4227. The position of a white pixel in the graph corresponds to the chroma value of
  4228. a pixel of the input clip. The graph can therefore be used to read the hue
  4229. (color flavor) and the saturation (the dominance of the hue in the color). As
  4230. the hue of a color changes, it moves around the square. At the center of the
  4231. square the saturation is zero, which means that the corresponding pixel has no
  4232. color. If the amount of a specific color is increased (while leaving the other
  4233. colors unchanged) the saturation increases, and the indicator moves towards
  4234. the edge of the square.
  4235. @item color2
  4236. Chroma values in vectorscope, similar as @code{color} but actual chroma values
  4237. are displayed.
  4238. @item waveform
  4239. Per row/column color component graph. In row mode, the graph on the left side
  4240. represents color component value 0 and the right side represents value = 255.
  4241. In column mode, the top side represents color component value = 0 and bottom
  4242. side represents value = 255.
  4243. @end table
  4244. Default value is @code{levels}.
  4245. @item level_height
  4246. Set height of level in @code{levels}. Default value is @code{200}.
  4247. Allowed range is [50, 2048].
  4248. @item scale_height
  4249. Set height of color scale in @code{levels}. Default value is @code{12}.
  4250. Allowed range is [0, 40].
  4251. @item step
  4252. Set step for @code{waveform} mode. Smaller values are useful to find out how
  4253. many values of the same luminance are distributed across input rows/columns.
  4254. Default value is @code{10}. Allowed range is [1, 255].
  4255. @item waveform_mode
  4256. Set mode for @code{waveform}. Can be either @code{row}, or @code{column}.
  4257. Default is @code{row}.
  4258. @item waveform_mirror
  4259. Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1}
  4260. means mirrored. In mirrored mode, higher values will be represented on the left
  4261. side for @code{row} mode and at the top for @code{column} mode. Default is
  4262. @code{0} (unmirrored).
  4263. @item display_mode
  4264. Set display mode for @code{waveform} and @code{levels}.
  4265. It accepts the following values:
  4266. @table @samp
  4267. @item parade
  4268. Display separate graph for the color components side by side in
  4269. @code{row} waveform mode or one below the other in @code{column} waveform mode
  4270. for @code{waveform} histogram mode. For @code{levels} histogram mode,
  4271. per color component graphs are placed below each other.
  4272. Using this display mode in @code{waveform} histogram mode makes it easy to
  4273. spot color casts in the highlights and shadows of an image, by comparing the
  4274. contours of the top and the bottom graphs of each waveform. Since whites,
  4275. grays, and blacks are characterized by exactly equal amounts of red, green,
  4276. and blue, neutral areas of the picture should display three waveforms of
  4277. roughly equal width/height. If not, the correction is easy to perform by
  4278. making level adjustments the three waveforms.
  4279. @item overlay
  4280. Presents information identical to that in the @code{parade}, except
  4281. that the graphs representing color components are superimposed directly
  4282. over one another.
  4283. This display mode in @code{waveform} histogram mode makes it easier to spot
  4284. relative differences or similarities in overlapping areas of the color
  4285. components that are supposed to be identical, such as neutral whites, grays,
  4286. or blacks.
  4287. @end table
  4288. Default is @code{parade}.
  4289. @item levels_mode
  4290. Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}.
  4291. Default is @code{linear}.
  4292. @end table
  4293. @subsection Examples
  4294. @itemize
  4295. @item
  4296. Calculate and draw histogram:
  4297. @example
  4298. ffplay -i input -vf histogram
  4299. @end example
  4300. @end itemize
  4301. @anchor{hqdn3d}
  4302. @section hqdn3d
  4303. This is a high precision/quality 3d denoise filter. It aims to reduce
  4304. image noise, producing smooth images and making still images really
  4305. still. It should enhance compressibility.
  4306. It accepts the following optional parameters:
  4307. @table @option
  4308. @item luma_spatial
  4309. A non-negative floating point number which specifies spatial luma strength.
  4310. It defaults to 4.0.
  4311. @item chroma_spatial
  4312. A non-negative floating point number which specifies spatial chroma strength.
  4313. It defaults to 3.0*@var{luma_spatial}/4.0.
  4314. @item luma_tmp
  4315. A floating point number which specifies luma temporal strength. It defaults to
  4316. 6.0*@var{luma_spatial}/4.0.
  4317. @item chroma_tmp
  4318. A floating point number which specifies chroma temporal strength. It defaults to
  4319. @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
  4320. @end table
  4321. @section hqx
  4322. Apply a high-quality magnification filter designed for pixel art. This filter
  4323. was originally created by Maxim Stepin.
  4324. It accepts the following option:
  4325. @table @option
  4326. @item n
  4327. Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
  4328. @code{hq3x} and @code{4} for @code{hq4x}.
  4329. Default is @code{3}.
  4330. @end table
  4331. @section hue
  4332. Modify the hue and/or the saturation of the input.
  4333. It accepts the following parameters:
  4334. @table @option
  4335. @item h
  4336. Specify the hue angle as a number of degrees. It accepts an expression,
  4337. and defaults to "0".
  4338. @item s
  4339. Specify the saturation in the [-10,10] range. It accepts an expression and
  4340. defaults to "1".
  4341. @item H
  4342. Specify the hue angle as a number of radians. It accepts an
  4343. expression, and defaults to "0".
  4344. @item b
  4345. Specify the brightness in the [-10,10] range. It accepts an expression and
  4346. defaults to "0".
  4347. @end table
  4348. @option{h} and @option{H} are mutually exclusive, and can't be
  4349. specified at the same time.
  4350. The @option{b}, @option{h}, @option{H} and @option{s} option values are
  4351. expressions containing the following constants:
  4352. @table @option
  4353. @item n
  4354. frame count of the input frame starting from 0
  4355. @item pts
  4356. presentation timestamp of the input frame expressed in time base units
  4357. @item r
  4358. frame rate of the input video, NAN if the input frame rate is unknown
  4359. @item t
  4360. timestamp expressed in seconds, NAN if the input timestamp is unknown
  4361. @item tb
  4362. time base of the input video
  4363. @end table
  4364. @subsection Examples
  4365. @itemize
  4366. @item
  4367. Set the hue to 90 degrees and the saturation to 1.0:
  4368. @example
  4369. hue=h=90:s=1
  4370. @end example
  4371. @item
  4372. Same command but expressing the hue in radians:
  4373. @example
  4374. hue=H=PI/2:s=1
  4375. @end example
  4376. @item
  4377. Rotate hue and make the saturation swing between 0
  4378. and 2 over a period of 1 second:
  4379. @example
  4380. hue="H=2*PI*t: s=sin(2*PI*t)+1"
  4381. @end example
  4382. @item
  4383. Apply a 3 seconds saturation fade-in effect starting at 0:
  4384. @example
  4385. hue="s=min(t/3\,1)"
  4386. @end example
  4387. The general fade-in expression can be written as:
  4388. @example
  4389. hue="s=min(0\, max((t-START)/DURATION\, 1))"
  4390. @end example
  4391. @item
  4392. Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
  4393. @example
  4394. hue="s=max(0\, min(1\, (8-t)/3))"
  4395. @end example
  4396. The general fade-out expression can be written as:
  4397. @example
  4398. hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
  4399. @end example
  4400. @end itemize
  4401. @subsection Commands
  4402. This filter supports the following commands:
  4403. @table @option
  4404. @item b
  4405. @item s
  4406. @item h
  4407. @item H
  4408. Modify the hue and/or the saturation and/or brightness of the input video.
  4409. The command accepts the same syntax of the corresponding option.
  4410. If the specified expression is not valid, it is kept at its current
  4411. value.
  4412. @end table
  4413. @section idet
  4414. Detect video interlacing type.
  4415. This filter tries to detect if the input frames as interlaced, progressive,
  4416. top or bottom field first. It will also try and detect fields that are
  4417. repeated between adjacent frames (a sign of telecine).
  4418. Single frame detection considers only immediately adjacent frames when classifying each frame.
  4419. Multiple frame detection incorporates the classification history of previous frames.
  4420. The filter will log these metadata values:
  4421. @table @option
  4422. @item single.current_frame
  4423. Detected type of current frame using single-frame detection. One of:
  4424. ``tff'' (top field first), ``bff'' (bottom field first),
  4425. ``progressive'', or ``undetermined''
  4426. @item single.tff
  4427. Cumulative number of frames detected as top field first using single-frame detection.
  4428. @item multiple.tff
  4429. Cumulative number of frames detected as top field first using multiple-frame detection.
  4430. @item single.bff
  4431. Cumulative number of frames detected as bottom field first using single-frame detection.
  4432. @item multiple.current_frame
  4433. Detected type of current frame using multiple-frame detection. One of:
  4434. ``tff'' (top field first), ``bff'' (bottom field first),
  4435. ``progressive'', or ``undetermined''
  4436. @item multiple.bff
  4437. Cumulative number of frames detected as bottom field first using multiple-frame detection.
  4438. @item single.progressive
  4439. Cumulative number of frames detected as progressive using single-frame detection.
  4440. @item multiple.progressive
  4441. Cumulative number of frames detected as progressive using multiple-frame detection.
  4442. @item single.undetermined
  4443. Cumulative number of frames that could not be classified using single-frame detection.
  4444. @item multiple.undetermined
  4445. Cumulative number of frames that could not be classified using multiple-frame detection.
  4446. @item repeated.current_frame
  4447. Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
  4448. @item repeated.neither
  4449. Cumulative number of frames with no repeated field.
  4450. @item repeated.top
  4451. Cumulative number of frames with the top field repeated from the previous frame's top field.
  4452. @item repeated.bottom
  4453. Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
  4454. @end table
  4455. The filter accepts the following options:
  4456. @table @option
  4457. @item intl_thres
  4458. Set interlacing threshold.
  4459. @item prog_thres
  4460. Set progressive threshold.
  4461. @item repeat_thres
  4462. Threshold for repeated field detection.
  4463. @item half_life
  4464. Number of frames after which a given frame's contribution to the
  4465. statistics is halved (i.e., it contributes only 0.5 to it's
  4466. classification). The default of 0 means that all frames seen are given
  4467. full weight of 1.0 forever.
  4468. @item analyze_interlaced_flag
  4469. When this is not 0 then idet will use the specified number of frames to determine
  4470. if the interlaced flag is accurate, it will not count undetermined frames.
  4471. If the flag is found to be accurate it will be used without any further
  4472. computations, if it is found to be inaccuarte it will be cleared without any
  4473. further computations. This allows inserting the idet filter as a low computational
  4474. method to clean up the interlaced flag
  4475. @end table
  4476. @section il
  4477. Deinterleave or interleave fields.
  4478. This filter allows one to process interlaced images fields without
  4479. deinterlacing them. Deinterleaving splits the input frame into 2
  4480. fields (so called half pictures). Odd lines are moved to the top
  4481. half of the output image, even lines to the bottom half.
  4482. You can process (filter) them independently and then re-interleave them.
  4483. The filter accepts the following options:
  4484. @table @option
  4485. @item luma_mode, l
  4486. @item chroma_mode, c
  4487. @item alpha_mode, a
  4488. Available values for @var{luma_mode}, @var{chroma_mode} and
  4489. @var{alpha_mode} are:
  4490. @table @samp
  4491. @item none
  4492. Do nothing.
  4493. @item deinterleave, d
  4494. Deinterleave fields, placing one above the other.
  4495. @item interleave, i
  4496. Interleave fields. Reverse the effect of deinterleaving.
  4497. @end table
  4498. Default value is @code{none}.
  4499. @item luma_swap, ls
  4500. @item chroma_swap, cs
  4501. @item alpha_swap, as
  4502. Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
  4503. @end table
  4504. @section interlace
  4505. Simple interlacing filter from progressive contents. This interleaves upper (or
  4506. lower) lines from odd frames with lower (or upper) lines from even frames,
  4507. halving the frame rate and preserving image height.
  4508. @example
  4509. Original Original New Frame
  4510. Frame 'j' Frame 'j+1' (tff)
  4511. ========== =========== ==================
  4512. Line 0 --------------------> Frame 'j' Line 0
  4513. Line 1 Line 1 ----> Frame 'j+1' Line 1
  4514. Line 2 ---------------------> Frame 'j' Line 2
  4515. Line 3 Line 3 ----> Frame 'j+1' Line 3
  4516. ... ... ...
  4517. New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
  4518. @end example
  4519. It accepts the following optional parameters:
  4520. @table @option
  4521. @item scan
  4522. This determines whether the interlaced frame is taken from the even
  4523. (tff - default) or odd (bff) lines of the progressive frame.
  4524. @item lowpass
  4525. Enable (default) or disable the vertical lowpass filter to avoid twitter
  4526. interlacing and reduce moire patterns.
  4527. @end table
  4528. @section kerndeint
  4529. Deinterlace input video by applying Donald Graft's adaptive kernel
  4530. deinterling. Work on interlaced parts of a video to produce
  4531. progressive frames.
  4532. The description of the accepted parameters follows.
  4533. @table @option
  4534. @item thresh
  4535. Set the threshold which affects the filter's tolerance when
  4536. determining if a pixel line must be processed. It must be an integer
  4537. in the range [0,255] and defaults to 10. A value of 0 will result in
  4538. applying the process on every pixels.
  4539. @item map
  4540. Paint pixels exceeding the threshold value to white if set to 1.
  4541. Default is 0.
  4542. @item order
  4543. Set the fields order. Swap fields if set to 1, leave fields alone if
  4544. 0. Default is 0.
  4545. @item sharp
  4546. Enable additional sharpening if set to 1. Default is 0.
  4547. @item twoway
  4548. Enable twoway sharpening if set to 1. Default is 0.
  4549. @end table
  4550. @subsection Examples
  4551. @itemize
  4552. @item
  4553. Apply default values:
  4554. @example
  4555. kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
  4556. @end example
  4557. @item
  4558. Enable additional sharpening:
  4559. @example
  4560. kerndeint=sharp=1
  4561. @end example
  4562. @item
  4563. Paint processed pixels in white:
  4564. @example
  4565. kerndeint=map=1
  4566. @end example
  4567. @end itemize
  4568. @section lenscorrection
  4569. Correct radial lens distortion
  4570. This filter can be used to correct for radial distortion as can result from the use
  4571. of wide angle lenses, and thereby re-rectify the image. To find the right parameters
  4572. one can use tools available for example as part of opencv or simply trial-and-error.
  4573. To use opencv use the calibration sample (under samples/cpp) from the opencv sources
  4574. and extract the k1 and k2 coefficients from the resulting matrix.
  4575. Note that effectively the same filter is available in the open-source tools Krita and
  4576. Digikam from the KDE project.
  4577. In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
  4578. this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
  4579. brightness distribution, so you may want to use both filters together in certain
  4580. cases, though you will have to take care of ordering, i.e. whether vignetting should
  4581. be applied before or after lens correction.
  4582. @subsection Options
  4583. The filter accepts the following options:
  4584. @table @option
  4585. @item cx
  4586. Relative x-coordinate of the focal point of the image, and thereby the center of the
  4587. distortion. This value has a range [0,1] and is expressed as fractions of the image
  4588. width.
  4589. @item cy
  4590. Relative y-coordinate of the focal point of the image, and thereby the center of the
  4591. distortion. This value has a range [0,1] and is expressed as fractions of the image
  4592. height.
  4593. @item k1
  4594. Coefficient of the quadratic correction term. 0.5 means no correction.
  4595. @item k2
  4596. Coefficient of the double quadratic correction term. 0.5 means no correction.
  4597. @end table
  4598. The formula that generates the correction is:
  4599. @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)
  4600. where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
  4601. distances from the focal point in the source and target images, respectively.
  4602. @anchor{lut3d}
  4603. @section lut3d
  4604. Apply a 3D LUT to an input video.
  4605. The filter accepts the following options:
  4606. @table @option
  4607. @item file
  4608. Set the 3D LUT file name.
  4609. Currently supported formats:
  4610. @table @samp
  4611. @item 3dl
  4612. AfterEffects
  4613. @item cube
  4614. Iridas
  4615. @item dat
  4616. DaVinci
  4617. @item m3d
  4618. Pandora
  4619. @end table
  4620. @item interp
  4621. Select interpolation mode.
  4622. Available values are:
  4623. @table @samp
  4624. @item nearest
  4625. Use values from the nearest defined point.
  4626. @item trilinear
  4627. Interpolate values using the 8 points defining a cube.
  4628. @item tetrahedral
  4629. Interpolate values using a tetrahedron.
  4630. @end table
  4631. @end table
  4632. @section lut, lutrgb, lutyuv
  4633. Compute a look-up table for binding each pixel component input value
  4634. to an output value, and apply it to the input video.
  4635. @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
  4636. to an RGB input video.
  4637. These filters accept the following parameters:
  4638. @table @option
  4639. @item c0
  4640. set first pixel component expression
  4641. @item c1
  4642. set second pixel component expression
  4643. @item c2
  4644. set third pixel component expression
  4645. @item c3
  4646. set fourth pixel component expression, corresponds to the alpha component
  4647. @item r
  4648. set red component expression
  4649. @item g
  4650. set green component expression
  4651. @item b
  4652. set blue component expression
  4653. @item a
  4654. alpha component expression
  4655. @item y
  4656. set Y/luminance component expression
  4657. @item u
  4658. set U/Cb component expression
  4659. @item v
  4660. set V/Cr component expression
  4661. @end table
  4662. Each of them specifies the expression to use for computing the lookup table for
  4663. the corresponding pixel component values.
  4664. The exact component associated to each of the @var{c*} options depends on the
  4665. format in input.
  4666. The @var{lut} filter requires either YUV or RGB pixel formats in input,
  4667. @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
  4668. The expressions can contain the following constants and functions:
  4669. @table @option
  4670. @item w
  4671. @item h
  4672. The input width and height.
  4673. @item val
  4674. The input value for the pixel component.
  4675. @item clipval
  4676. The input value, clipped to the @var{minval}-@var{maxval} range.
  4677. @item maxval
  4678. The maximum value for the pixel component.
  4679. @item minval
  4680. The minimum value for the pixel component.
  4681. @item negval
  4682. The negated value for the pixel component value, clipped to the
  4683. @var{minval}-@var{maxval} range; it corresponds to the expression
  4684. "maxval-clipval+minval".
  4685. @item clip(val)
  4686. The computed value in @var{val}, clipped to the
  4687. @var{minval}-@var{maxval} range.
  4688. @item gammaval(gamma)
  4689. The computed gamma correction value of the pixel component value,
  4690. clipped to the @var{minval}-@var{maxval} range. It corresponds to the
  4691. expression
  4692. "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
  4693. @end table
  4694. All expressions default to "val".
  4695. @subsection Examples
  4696. @itemize
  4697. @item
  4698. Negate input video:
  4699. @example
  4700. lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
  4701. lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
  4702. @end example
  4703. The above is the same as:
  4704. @example
  4705. lutrgb="r=negval:g=negval:b=negval"
  4706. lutyuv="y=negval:u=negval:v=negval"
  4707. @end example
  4708. @item
  4709. Negate luminance:
  4710. @example
  4711. lutyuv=y=negval
  4712. @end example
  4713. @item
  4714. Remove chroma components, turning the video into a graytone image:
  4715. @example
  4716. lutyuv="u=128:v=128"
  4717. @end example
  4718. @item
  4719. Apply a luma burning effect:
  4720. @example
  4721. lutyuv="y=2*val"
  4722. @end example
  4723. @item
  4724. Remove green and blue components:
  4725. @example
  4726. lutrgb="g=0:b=0"
  4727. @end example
  4728. @item
  4729. Set a constant alpha channel value on input:
  4730. @example
  4731. format=rgba,lutrgb=a="maxval-minval/2"
  4732. @end example
  4733. @item
  4734. Correct luminance gamma by a factor of 0.5:
  4735. @example
  4736. lutyuv=y=gammaval(0.5)
  4737. @end example
  4738. @item
  4739. Discard least significant bits of luma:
  4740. @example
  4741. lutyuv=y='bitand(val, 128+64+32)'
  4742. @end example
  4743. @end itemize
  4744. @section mergeplanes
  4745. Merge color channel components from several video streams.
  4746. The filter accepts up to 4 input streams, and merge selected input
  4747. planes to the output video.
  4748. This filter accepts the following options:
  4749. @table @option
  4750. @item mapping
  4751. Set input to output plane mapping. Default is @code{0}.
  4752. The mappings is specified as a bitmap. It should be specified as a
  4753. hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
  4754. mapping for the first plane of the output stream. 'A' sets the number of
  4755. the input stream to use (from 0 to 3), and 'a' the plane number of the
  4756. corresponding input to use (from 0 to 3). The rest of the mappings is
  4757. similar, 'Bb' describes the mapping for the output stream second
  4758. plane, 'Cc' describes the mapping for the output stream third plane and
  4759. 'Dd' describes the mapping for the output stream fourth plane.
  4760. @item format
  4761. Set output pixel format. Default is @code{yuva444p}.
  4762. @end table
  4763. @subsection Examples
  4764. @itemize
  4765. @item
  4766. Merge three gray video streams of same width and height into single video stream:
  4767. @example
  4768. [a0][a1][a2]mergeplanes=0x001020:yuv444p
  4769. @end example
  4770. @item
  4771. Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
  4772. @example
  4773. [a0][a1]mergeplanes=0x00010210:yuva444p
  4774. @end example
  4775. @item
  4776. Swap Y and A plane in yuva444p stream:
  4777. @example
  4778. format=yuva444p,mergeplanes=0x03010200:yuva444p
  4779. @end example
  4780. @item
  4781. Swap U and V plane in yuv420p stream:
  4782. @example
  4783. format=yuv420p,mergeplanes=0x000201:yuv420p
  4784. @end example
  4785. @item
  4786. Cast a rgb24 clip to yuv444p:
  4787. @example
  4788. format=rgb24,mergeplanes=0x000102:yuv444p
  4789. @end example
  4790. @end itemize
  4791. @section mcdeint
  4792. Apply motion-compensation deinterlacing.
  4793. It needs one field per frame as input and must thus be used together
  4794. with yadif=1/3 or equivalent.
  4795. This filter accepts the following options:
  4796. @table @option
  4797. @item mode
  4798. Set the deinterlacing mode.
  4799. It accepts one of the following values:
  4800. @table @samp
  4801. @item fast
  4802. @item medium
  4803. @item slow
  4804. use iterative motion estimation
  4805. @item extra_slow
  4806. like @samp{slow}, but use multiple reference frames.
  4807. @end table
  4808. Default value is @samp{fast}.
  4809. @item parity
  4810. Set the picture field parity assumed for the input video. It must be
  4811. one of the following values:
  4812. @table @samp
  4813. @item 0, tff
  4814. assume top field first
  4815. @item 1, bff
  4816. assume bottom field first
  4817. @end table
  4818. Default value is @samp{bff}.
  4819. @item qp
  4820. Set per-block quantization parameter (QP) used by the internal
  4821. encoder.
  4822. Higher values should result in a smoother motion vector field but less
  4823. optimal individual vectors. Default value is 1.
  4824. @end table
  4825. @section mpdecimate
  4826. Drop frames that do not differ greatly from the previous frame in
  4827. order to reduce frame rate.
  4828. The main use of this filter is for very-low-bitrate encoding
  4829. (e.g. streaming over dialup modem), but it could in theory be used for
  4830. fixing movies that were inverse-telecined incorrectly.
  4831. A description of the accepted options follows.
  4832. @table @option
  4833. @item max
  4834. Set the maximum number of consecutive frames which can be dropped (if
  4835. positive), or the minimum interval between dropped frames (if
  4836. negative). If the value is 0, the frame is dropped unregarding the
  4837. number of previous sequentially dropped frames.
  4838. Default value is 0.
  4839. @item hi
  4840. @item lo
  4841. @item frac
  4842. Set the dropping threshold values.
  4843. Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
  4844. represent actual pixel value differences, so a threshold of 64
  4845. corresponds to 1 unit of difference for each pixel, or the same spread
  4846. out differently over the block.
  4847. A frame is a candidate for dropping if no 8x8 blocks differ by more
  4848. than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
  4849. meaning the whole image) differ by more than a threshold of @option{lo}.
  4850. Default value for @option{hi} is 64*12, default value for @option{lo} is
  4851. 64*5, and default value for @option{frac} is 0.33.
  4852. @end table
  4853. @section negate
  4854. Negate input video.
  4855. It accepts an integer in input; if non-zero it negates the
  4856. alpha component (if available). The default value in input is 0.
  4857. @section noformat
  4858. Force libavfilter not to use any of the specified pixel formats for the
  4859. input to the next filter.
  4860. It accepts the following parameters:
  4861. @table @option
  4862. @item pix_fmts
  4863. A '|'-separated list of pixel format names, such as
  4864. apix_fmts=yuv420p|monow|rgb24".
  4865. @end table
  4866. @subsection Examples
  4867. @itemize
  4868. @item
  4869. Force libavfilter to use a format different from @var{yuv420p} for the
  4870. input to the vflip filter:
  4871. @example
  4872. noformat=pix_fmts=yuv420p,vflip
  4873. @end example
  4874. @item
  4875. Convert the input video to any of the formats not contained in the list:
  4876. @example
  4877. noformat=yuv420p|yuv444p|yuv410p
  4878. @end example
  4879. @end itemize
  4880. @section noise
  4881. Add noise on video input frame.
  4882. The filter accepts the following options:
  4883. @table @option
  4884. @item all_seed
  4885. @item c0_seed
  4886. @item c1_seed
  4887. @item c2_seed
  4888. @item c3_seed
  4889. Set noise seed for specific pixel component or all pixel components in case
  4890. of @var{all_seed}. Default value is @code{123457}.
  4891. @item all_strength, alls
  4892. @item c0_strength, c0s
  4893. @item c1_strength, c1s
  4894. @item c2_strength, c2s
  4895. @item c3_strength, c3s
  4896. Set noise strength for specific pixel component or all pixel components in case
  4897. @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
  4898. @item all_flags, allf
  4899. @item c0_flags, c0f
  4900. @item c1_flags, c1f
  4901. @item c2_flags, c2f
  4902. @item c3_flags, c3f
  4903. Set pixel component flags or set flags for all components if @var{all_flags}.
  4904. Available values for component flags are:
  4905. @table @samp
  4906. @item a
  4907. averaged temporal noise (smoother)
  4908. @item p
  4909. mix random noise with a (semi)regular pattern
  4910. @item t
  4911. temporal noise (noise pattern changes between frames)
  4912. @item u
  4913. uniform noise (gaussian otherwise)
  4914. @end table
  4915. @end table
  4916. @subsection Examples
  4917. Add temporal and uniform noise to input video:
  4918. @example
  4919. noise=alls=20:allf=t+u
  4920. @end example
  4921. @section null
  4922. Pass the video source unchanged to the output.
  4923. @section ocv
  4924. Apply a video transform using libopencv.
  4925. To enable this filter, install the libopencv library and headers and
  4926. configure FFmpeg with @code{--enable-libopencv}.
  4927. It accepts the following parameters:
  4928. @table @option
  4929. @item filter_name
  4930. The name of the libopencv filter to apply.
  4931. @item filter_params
  4932. The parameters to pass to the libopencv filter. If not specified, the default
  4933. values are assumed.
  4934. @end table
  4935. Refer to the official libopencv documentation for more precise
  4936. information:
  4937. @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
  4938. Several libopencv filters are supported; see the following subsections.
  4939. @anchor{dilate}
  4940. @subsection dilate
  4941. Dilate an image by using a specific structuring element.
  4942. It corresponds to the libopencv function @code{cvDilate}.
  4943. It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
  4944. @var{struct_el} represents a structuring element, and has the syntax:
  4945. @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
  4946. @var{cols} and @var{rows} represent the number of columns and rows of
  4947. the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
  4948. point, and @var{shape} the shape for the structuring element. @var{shape}
  4949. must be "rect", "cross", "ellipse", or "custom".
  4950. If the value for @var{shape} is "custom", it must be followed by a
  4951. string of the form "=@var{filename}". The file with name
  4952. @var{filename} is assumed to represent a binary image, with each
  4953. printable character corresponding to a bright pixel. When a custom
  4954. @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
  4955. or columns and rows of the read file are assumed instead.
  4956. The default value for @var{struct_el} is "3x3+0x0/rect".
  4957. @var{nb_iterations} specifies the number of times the transform is
  4958. applied to the image, and defaults to 1.
  4959. Some examples:
  4960. @example
  4961. # Use the default values
  4962. ocv=dilate
  4963. # Dilate using a structuring element with a 5x5 cross, iterating two times
  4964. ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
  4965. # Read the shape from the file diamond.shape, iterating two times.
  4966. # The file diamond.shape may contain a pattern of characters like this
  4967. # *
  4968. # ***
  4969. # *****
  4970. # ***
  4971. # *
  4972. # The specified columns and rows are ignored
  4973. # but the anchor point coordinates are not
  4974. ocv=dilate:0x0+2x2/custom=diamond.shape|2
  4975. @end example
  4976. @subsection erode
  4977. Erode an image by using a specific structuring element.
  4978. It corresponds to the libopencv function @code{cvErode}.
  4979. It accepts the parameters: @var{struct_el}:@var{nb_iterations},
  4980. with the same syntax and semantics as the @ref{dilate} filter.
  4981. @subsection smooth
  4982. Smooth the input video.
  4983. The filter takes the following parameters:
  4984. @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
  4985. @var{type} is the type of smooth filter to apply, and must be one of
  4986. the following values: "blur", "blur_no_scale", "median", "gaussian",
  4987. or "bilateral". The default value is "gaussian".
  4988. The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
  4989. depend on the smooth type. @var{param1} and
  4990. @var{param2} accept integer positive values or 0. @var{param3} and
  4991. @var{param4} accept floating point values.
  4992. The default value for @var{param1} is 3. The default value for the
  4993. other parameters is 0.
  4994. These parameters correspond to the parameters assigned to the
  4995. libopencv function @code{cvSmooth}.
  4996. @anchor{overlay}
  4997. @section overlay
  4998. Overlay one video on top of another.
  4999. It takes two inputs and has one output. The first input is the "main"
  5000. video on which the second input is overlaid.
  5001. It accepts the following parameters:
  5002. A description of the accepted options follows.
  5003. @table @option
  5004. @item x
  5005. @item y
  5006. Set the expression for the x and y coordinates of the overlaid video
  5007. on the main video. Default value is "0" for both expressions. In case
  5008. the expression is invalid, it is set to a huge value (meaning that the
  5009. overlay will not be displayed within the output visible area).
  5010. @item eof_action
  5011. The action to take when EOF is encountered on the secondary input; it accepts
  5012. one of the following values:
  5013. @table @option
  5014. @item repeat
  5015. Repeat the last frame (the default).
  5016. @item endall
  5017. End both streams.
  5018. @item pass
  5019. Pass the main input through.
  5020. @end table
  5021. @item eval
  5022. Set when the expressions for @option{x}, and @option{y} are evaluated.
  5023. It accepts the following values:
  5024. @table @samp
  5025. @item init
  5026. only evaluate expressions once during the filter initialization or
  5027. when a command is processed
  5028. @item frame
  5029. evaluate expressions for each incoming frame
  5030. @end table
  5031. Default value is @samp{frame}.
  5032. @item shortest
  5033. If set to 1, force the output to terminate when the shortest input
  5034. terminates. Default value is 0.
  5035. @item format
  5036. Set the format for the output video.
  5037. It accepts the following values:
  5038. @table @samp
  5039. @item yuv420
  5040. force YUV420 output
  5041. @item yuv422
  5042. force YUV422 output
  5043. @item yuv444
  5044. force YUV444 output
  5045. @item rgb
  5046. force RGB output
  5047. @end table
  5048. Default value is @samp{yuv420}.
  5049. @item rgb @emph{(deprecated)}
  5050. If set to 1, force the filter to accept inputs in the RGB
  5051. color space. Default value is 0. This option is deprecated, use
  5052. @option{format} instead.
  5053. @item repeatlast
  5054. If set to 1, force the filter to draw the last overlay frame over the
  5055. main input until the end of the stream. A value of 0 disables this
  5056. behavior. Default value is 1.
  5057. @end table
  5058. The @option{x}, and @option{y} expressions can contain the following
  5059. parameters.
  5060. @table @option
  5061. @item main_w, W
  5062. @item main_h, H
  5063. The main input width and height.
  5064. @item overlay_w, w
  5065. @item overlay_h, h
  5066. The overlay input width and height.
  5067. @item x
  5068. @item y
  5069. The computed values for @var{x} and @var{y}. They are evaluated for
  5070. each new frame.
  5071. @item hsub
  5072. @item vsub
  5073. horizontal and vertical chroma subsample values of the output
  5074. format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
  5075. @var{vsub} is 1.
  5076. @item n
  5077. the number of input frame, starting from 0
  5078. @item pos
  5079. the position in the file of the input frame, NAN if unknown
  5080. @item t
  5081. The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
  5082. @end table
  5083. Note that the @var{n}, @var{pos}, @var{t} variables are available only
  5084. when evaluation is done @emph{per frame}, and will evaluate to NAN
  5085. when @option{eval} is set to @samp{init}.
  5086. Be aware that frames are taken from each input video in timestamp
  5087. order, hence, if their initial timestamps differ, it is a good idea
  5088. to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
  5089. have them begin in the same zero timestamp, as the example for
  5090. the @var{movie} filter does.
  5091. You can chain together more overlays but you should test the
  5092. efficiency of such approach.
  5093. @subsection Commands
  5094. This filter supports the following commands:
  5095. @table @option
  5096. @item x
  5097. @item y
  5098. Modify the x and y of the overlay input.
  5099. The command accepts the same syntax of the corresponding option.
  5100. If the specified expression is not valid, it is kept at its current
  5101. value.
  5102. @end table
  5103. @subsection Examples
  5104. @itemize
  5105. @item
  5106. Draw the overlay at 10 pixels from the bottom right corner of the main
  5107. video:
  5108. @example
  5109. overlay=main_w-overlay_w-10:main_h-overlay_h-10
  5110. @end example
  5111. Using named options the example above becomes:
  5112. @example
  5113. overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
  5114. @end example
  5115. @item
  5116. Insert a transparent PNG logo in the bottom left corner of the input,
  5117. using the @command{ffmpeg} tool with the @code{-filter_complex} option:
  5118. @example
  5119. ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
  5120. @end example
  5121. @item
  5122. Insert 2 different transparent PNG logos (second logo on bottom
  5123. right corner) using the @command{ffmpeg} tool:
  5124. @example
  5125. 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
  5126. @end example
  5127. @item
  5128. Add a transparent color layer on top of the main video; @code{WxH}
  5129. must specify the size of the main input to the overlay filter:
  5130. @example
  5131. color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
  5132. @end example
  5133. @item
  5134. Play an original video and a filtered version (here with the deshake
  5135. filter) side by side using the @command{ffplay} tool:
  5136. @example
  5137. ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
  5138. @end example
  5139. The above command is the same as:
  5140. @example
  5141. ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
  5142. @end example
  5143. @item
  5144. Make a sliding overlay appearing from the left to the right top part of the
  5145. screen starting since time 2:
  5146. @example
  5147. overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
  5148. @end example
  5149. @item
  5150. Compose output by putting two input videos side to side:
  5151. @example
  5152. ffmpeg -i left.avi -i right.avi -filter_complex "
  5153. nullsrc=size=200x100 [background];
  5154. [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
  5155. [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
  5156. [background][left] overlay=shortest=1 [background+left];
  5157. [background+left][right] overlay=shortest=1:x=100 [left+right]
  5158. "
  5159. @end example
  5160. @item
  5161. Mask 10-20 seconds of a video by applying the delogo filter to a section
  5162. @example
  5163. ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
  5164. -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]'
  5165. masked.avi
  5166. @end example
  5167. @item
  5168. Chain several overlays in cascade:
  5169. @example
  5170. nullsrc=s=200x200 [bg];
  5171. testsrc=s=100x100, split=4 [in0][in1][in2][in3];
  5172. [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
  5173. [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
  5174. [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
  5175. [in3] null, [mid2] overlay=100:100 [out0]
  5176. @end example
  5177. @end itemize
  5178. @section owdenoise
  5179. Apply Overcomplete Wavelet denoiser.
  5180. The filter accepts the following options:
  5181. @table @option
  5182. @item depth
  5183. Set depth.
  5184. Larger depth values will denoise lower frequency components more, but
  5185. slow down filtering.
  5186. Must be an int in the range 8-16, default is @code{8}.
  5187. @item luma_strength, ls
  5188. Set luma strength.
  5189. Must be a double value in the range 0-1000, default is @code{1.0}.
  5190. @item chroma_strength, cs
  5191. Set chroma strength.
  5192. Must be a double value in the range 0-1000, default is @code{1.0}.
  5193. @end table
  5194. @section pad
  5195. Add paddings to the input image, and place the original input at the
  5196. provided @var{x}, @var{y} coordinates.
  5197. It accepts the following parameters:
  5198. @table @option
  5199. @item width, w
  5200. @item height, h
  5201. Specify an expression for the size of the output image with the
  5202. paddings added. If the value for @var{width} or @var{height} is 0, the
  5203. corresponding input size is used for the output.
  5204. The @var{width} expression can reference the value set by the
  5205. @var{height} expression, and vice versa.
  5206. The default value of @var{width} and @var{height} is 0.
  5207. @item x
  5208. @item y
  5209. Specify the offsets to place the input image at within the padded area,
  5210. with respect to the top/left border of the output image.
  5211. The @var{x} expression can reference the value set by the @var{y}
  5212. expression, and vice versa.
  5213. The default value of @var{x} and @var{y} is 0.
  5214. @item color
  5215. Specify the color of the padded area. For the syntax of this option,
  5216. check the "Color" section in the ffmpeg-utils manual.
  5217. The default value of @var{color} is "black".
  5218. @end table
  5219. The value for the @var{width}, @var{height}, @var{x}, and @var{y}
  5220. options are expressions containing the following constants:
  5221. @table @option
  5222. @item in_w
  5223. @item in_h
  5224. The input video width and height.
  5225. @item iw
  5226. @item ih
  5227. These are the same as @var{in_w} and @var{in_h}.
  5228. @item out_w
  5229. @item out_h
  5230. The output width and height (the size of the padded area), as
  5231. specified by the @var{width} and @var{height} expressions.
  5232. @item ow
  5233. @item oh
  5234. These are the same as @var{out_w} and @var{out_h}.
  5235. @item x
  5236. @item y
  5237. The x and y offsets as specified by the @var{x} and @var{y}
  5238. expressions, or NAN if not yet specified.
  5239. @item a
  5240. same as @var{iw} / @var{ih}
  5241. @item sar
  5242. input sample aspect ratio
  5243. @item dar
  5244. input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
  5245. @item hsub
  5246. @item vsub
  5247. The horizontal and vertical chroma subsample values. For example for the
  5248. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5249. @end table
  5250. @subsection Examples
  5251. @itemize
  5252. @item
  5253. Add paddings with the color "violet" to the input video. The output video
  5254. size is 640x480, and the top-left corner of the input video is placed at
  5255. column 0, row 40
  5256. @example
  5257. pad=640:480:0:40:violet
  5258. @end example
  5259. The example above is equivalent to the following command:
  5260. @example
  5261. pad=width=640:height=480:x=0:y=40:color=violet
  5262. @end example
  5263. @item
  5264. Pad the input to get an output with dimensions increased by 3/2,
  5265. and put the input video at the center of the padded area:
  5266. @example
  5267. pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
  5268. @end example
  5269. @item
  5270. Pad the input to get a squared output with size equal to the maximum
  5271. value between the input width and height, and put the input video at
  5272. the center of the padded area:
  5273. @example
  5274. pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
  5275. @end example
  5276. @item
  5277. Pad the input to get a final w/h ratio of 16:9:
  5278. @example
  5279. pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
  5280. @end example
  5281. @item
  5282. In case of anamorphic video, in order to set the output display aspect
  5283. correctly, it is necessary to use @var{sar} in the expression,
  5284. according to the relation:
  5285. @example
  5286. (ih * X / ih) * sar = output_dar
  5287. X = output_dar / sar
  5288. @end example
  5289. Thus the previous example needs to be modified to:
  5290. @example
  5291. pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
  5292. @end example
  5293. @item
  5294. Double the output size and put the input video in the bottom-right
  5295. corner of the output padded area:
  5296. @example
  5297. pad="2*iw:2*ih:ow-iw:oh-ih"
  5298. @end example
  5299. @end itemize
  5300. @anchor{palettegen}
  5301. @section palettegen
  5302. Generate one palette for a whole video stream.
  5303. It accepts the following options:
  5304. @table @option
  5305. @item max_colors
  5306. Set the maximum number of colors to quantize in the palette.
  5307. Note: the palette will still contain 256 colors; the unused palette entries
  5308. will be black.
  5309. @item reserve_transparent
  5310. Create a palette of 255 colors maximum and reserve the last one for
  5311. transparency. Reserving the transparency color is useful for GIF optimization.
  5312. If not set, the maximum of colors in the palette will be 256. You probably want
  5313. to disable this option for a standalone image.
  5314. Set by default.
  5315. @item stats_mode
  5316. Set statistics mode.
  5317. It accepts the following values:
  5318. @table @samp
  5319. @item full
  5320. Compute full frame histograms.
  5321. @item diff
  5322. Compute histograms only for the part that differs from previous frame. This
  5323. might be relevant to give more importance to the moving part of your input if
  5324. the background is static.
  5325. @end table
  5326. Default value is @var{full}.
  5327. @end table
  5328. @subsection Examples
  5329. @itemize
  5330. @item
  5331. Generate a representative palette of a given video using @command{ffmpeg}:
  5332. @example
  5333. ffmpeg -i input.mkv -vf palettegen palette.png
  5334. @end example
  5335. @end itemize
  5336. @section paletteuse
  5337. Use a palette to downsample an input video stream.
  5338. The filter takes two inputs: one video stream and a palette. The palette must
  5339. be a 256 pixels image.
  5340. It accepts the following options:
  5341. @table @option
  5342. @item dither
  5343. Select dithering mode. Available algorithms are:
  5344. @table @samp
  5345. @item bayer
  5346. Ordered 8x8 bayer dithering (deterministic)
  5347. @item heckbert
  5348. Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
  5349. Note: this dithering is sometimes considered "wrong" and is included as a
  5350. reference.
  5351. @item floyd_steinberg
  5352. Floyd and Steingberg dithering (error diffusion)
  5353. @item sierra2
  5354. Frankie Sierra dithering v2 (error diffusion)
  5355. @item sierra2_4a
  5356. Frankie Sierra dithering v2 "Lite" (error diffusion)
  5357. @end table
  5358. Default is @var{sierra2_4a}.
  5359. @item bayer_scale
  5360. When @var{bayer} dithering is selected, this option defines the scale of the
  5361. pattern (how much the crosshatch pattern is visible). A low value means more
  5362. visible pattern for less banding, and higher value means less visible pattern
  5363. at the cost of more banding.
  5364. The option must be an integer value in the range [0,5]. Default is @var{2}.
  5365. @end table
  5366. @subsection Examples
  5367. @itemize
  5368. @item
  5369. Use a palette (generated for example with @ref{palettegen}) to encode a GIF
  5370. using @command{ffmpeg}:
  5371. @example
  5372. ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
  5373. @end example
  5374. @end itemize
  5375. @section perspective
  5376. Correct perspective of video not recorded perpendicular to the screen.
  5377. A description of the accepted parameters follows.
  5378. @table @option
  5379. @item x0
  5380. @item y0
  5381. @item x1
  5382. @item y1
  5383. @item x2
  5384. @item y2
  5385. @item x3
  5386. @item y3
  5387. Set coordinates expression for top left, top right, bottom left and bottom right corners.
  5388. Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
  5389. If the @code{sense} option is set to @code{source}, then the specified points will be sent
  5390. to the corners of the destination. If the @code{sense} option is set to @code{destination},
  5391. then the corners of the source will be sent to the specified coordinates.
  5392. The expressions can use the following variables:
  5393. @table @option
  5394. @item W
  5395. @item H
  5396. the width and height of video frame.
  5397. @end table
  5398. @item interpolation
  5399. Set interpolation for perspective correction.
  5400. It accepts the following values:
  5401. @table @samp
  5402. @item linear
  5403. @item cubic
  5404. @end table
  5405. Default value is @samp{linear}.
  5406. @item sense
  5407. Set interpretation of coordinate options.
  5408. It accepts the following values:
  5409. @table @samp
  5410. @item 0, source
  5411. Send point in the source specified by the given coordinates to
  5412. the corners of the destination.
  5413. @item 1, destination
  5414. Send the corners of the source to the point in the destination specified
  5415. by the given coordinates.
  5416. Default value is @samp{source}.
  5417. @end table
  5418. @end table
  5419. @section phase
  5420. Delay interlaced video by one field time so that the field order changes.
  5421. The intended use is to fix PAL movies that have been captured with the
  5422. opposite field order to the film-to-video transfer.
  5423. A description of the accepted parameters follows.
  5424. @table @option
  5425. @item mode
  5426. Set phase mode.
  5427. It accepts the following values:
  5428. @table @samp
  5429. @item t
  5430. Capture field order top-first, transfer bottom-first.
  5431. Filter will delay the bottom field.
  5432. @item b
  5433. Capture field order bottom-first, transfer top-first.
  5434. Filter will delay the top field.
  5435. @item p
  5436. Capture and transfer with the same field order. This mode only exists
  5437. for the documentation of the other options to refer to, but if you
  5438. actually select it, the filter will faithfully do nothing.
  5439. @item a
  5440. Capture field order determined automatically by field flags, transfer
  5441. opposite.
  5442. Filter selects among @samp{t} and @samp{b} modes on a frame by frame
  5443. basis using field flags. If no field information is available,
  5444. then this works just like @samp{u}.
  5445. @item u
  5446. Capture unknown or varying, transfer opposite.
  5447. Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
  5448. analyzing the images and selecting the alternative that produces best
  5449. match between the fields.
  5450. @item T
  5451. Capture top-first, transfer unknown or varying.
  5452. Filter selects among @samp{t} and @samp{p} using image analysis.
  5453. @item B
  5454. Capture bottom-first, transfer unknown or varying.
  5455. Filter selects among @samp{b} and @samp{p} using image analysis.
  5456. @item A
  5457. Capture determined by field flags, transfer unknown or varying.
  5458. Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
  5459. image analysis. If no field information is available, then this works just
  5460. like @samp{U}. This is the default mode.
  5461. @item U
  5462. Both capture and transfer unknown or varying.
  5463. Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
  5464. @end table
  5465. @end table
  5466. @section pixdesctest
  5467. Pixel format descriptor test filter, mainly useful for internal
  5468. testing. The output video should be equal to the input video.
  5469. For example:
  5470. @example
  5471. format=monow, pixdesctest
  5472. @end example
  5473. can be used to test the monowhite pixel format descriptor definition.
  5474. @section pp
  5475. Enable the specified chain of postprocessing subfilters using libpostproc. This
  5476. library should be automatically selected with a GPL build (@code{--enable-gpl}).
  5477. Subfilters must be separated by '/' and can be disabled by prepending a '-'.
  5478. Each subfilter and some options have a short and a long name that can be used
  5479. interchangeably, i.e. dr/dering are the same.
  5480. The filters accept the following options:
  5481. @table @option
  5482. @item subfilters
  5483. Set postprocessing subfilters string.
  5484. @end table
  5485. All subfilters share common options to determine their scope:
  5486. @table @option
  5487. @item a/autoq
  5488. Honor the quality commands for this subfilter.
  5489. @item c/chrom
  5490. Do chrominance filtering, too (default).
  5491. @item y/nochrom
  5492. Do luminance filtering only (no chrominance).
  5493. @item n/noluma
  5494. Do chrominance filtering only (no luminance).
  5495. @end table
  5496. These options can be appended after the subfilter name, separated by a '|'.
  5497. Available subfilters are:
  5498. @table @option
  5499. @item hb/hdeblock[|difference[|flatness]]
  5500. Horizontal deblocking filter
  5501. @table @option
  5502. @item difference
  5503. Difference factor where higher values mean more deblocking (default: @code{32}).
  5504. @item flatness
  5505. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  5506. @end table
  5507. @item vb/vdeblock[|difference[|flatness]]
  5508. Vertical deblocking filter
  5509. @table @option
  5510. @item difference
  5511. Difference factor where higher values mean more deblocking (default: @code{32}).
  5512. @item flatness
  5513. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  5514. @end table
  5515. @item ha/hadeblock[|difference[|flatness]]
  5516. Accurate horizontal deblocking filter
  5517. @table @option
  5518. @item difference
  5519. Difference factor where higher values mean more deblocking (default: @code{32}).
  5520. @item flatness
  5521. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  5522. @end table
  5523. @item va/vadeblock[|difference[|flatness]]
  5524. Accurate vertical deblocking filter
  5525. @table @option
  5526. @item difference
  5527. Difference factor where higher values mean more deblocking (default: @code{32}).
  5528. @item flatness
  5529. Flatness threshold where lower values mean more deblocking (default: @code{39}).
  5530. @end table
  5531. @end table
  5532. The horizontal and vertical deblocking filters share the difference and
  5533. flatness values so you cannot set different horizontal and vertical
  5534. thresholds.
  5535. @table @option
  5536. @item h1/x1hdeblock
  5537. Experimental horizontal deblocking filter
  5538. @item v1/x1vdeblock
  5539. Experimental vertical deblocking filter
  5540. @item dr/dering
  5541. Deringing filter
  5542. @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
  5543. @table @option
  5544. @item threshold1
  5545. larger -> stronger filtering
  5546. @item threshold2
  5547. larger -> stronger filtering
  5548. @item threshold3
  5549. larger -> stronger filtering
  5550. @end table
  5551. @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
  5552. @table @option
  5553. @item f/fullyrange
  5554. Stretch luminance to @code{0-255}.
  5555. @end table
  5556. @item lb/linblenddeint
  5557. Linear blend deinterlacing filter that deinterlaces the given block by
  5558. filtering all lines with a @code{(1 2 1)} filter.
  5559. @item li/linipoldeint
  5560. Linear interpolating deinterlacing filter that deinterlaces the given block by
  5561. linearly interpolating every second line.
  5562. @item ci/cubicipoldeint
  5563. Cubic interpolating deinterlacing filter deinterlaces the given block by
  5564. cubically interpolating every second line.
  5565. @item md/mediandeint
  5566. Median deinterlacing filter that deinterlaces the given block by applying a
  5567. median filter to every second line.
  5568. @item fd/ffmpegdeint
  5569. FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
  5570. second line with a @code{(-1 4 2 4 -1)} filter.
  5571. @item l5/lowpass5
  5572. Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
  5573. block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
  5574. @item fq/forceQuant[|quantizer]
  5575. Overrides the quantizer table from the input with the constant quantizer you
  5576. specify.
  5577. @table @option
  5578. @item quantizer
  5579. Quantizer to use
  5580. @end table
  5581. @item de/default
  5582. Default pp filter combination (@code{hb|a,vb|a,dr|a})
  5583. @item fa/fast
  5584. Fast pp filter combination (@code{h1|a,v1|a,dr|a})
  5585. @item ac
  5586. High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
  5587. @end table
  5588. @subsection Examples
  5589. @itemize
  5590. @item
  5591. Apply horizontal and vertical deblocking, deringing and automatic
  5592. brightness/contrast:
  5593. @example
  5594. pp=hb/vb/dr/al
  5595. @end example
  5596. @item
  5597. Apply default filters without brightness/contrast correction:
  5598. @example
  5599. pp=de/-al
  5600. @end example
  5601. @item
  5602. Apply default filters and temporal denoiser:
  5603. @example
  5604. pp=default/tmpnoise|1|2|3
  5605. @end example
  5606. @item
  5607. Apply deblocking on luminance only, and switch vertical deblocking on or off
  5608. automatically depending on available CPU time:
  5609. @example
  5610. pp=hb|y/vb|a
  5611. @end example
  5612. @end itemize
  5613. @section pp7
  5614. Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
  5615. similar to spp = 6 with 7 point DCT, where only the center sample is
  5616. used after IDCT.
  5617. The filter accepts the following options:
  5618. @table @option
  5619. @item qp
  5620. Force a constant quantization parameter. It accepts an integer in range
  5621. 0 to 63. If not set, the filter will use the QP from the video stream
  5622. (if available).
  5623. @item mode
  5624. Set thresholding mode. Available modes are:
  5625. @table @samp
  5626. @item hard
  5627. Set hard thresholding.
  5628. @item soft
  5629. Set soft thresholding (better de-ringing effect, but likely blurrier).
  5630. @item medium
  5631. Set medium thresholding (good results, default).
  5632. @end table
  5633. @end table
  5634. @section psnr
  5635. Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
  5636. Ratio) between two input videos.
  5637. This filter takes in input two input videos, the first input is
  5638. considered the "main" source and is passed unchanged to the
  5639. output. The second input is used as a "reference" video for computing
  5640. the PSNR.
  5641. Both video inputs must have the same resolution and pixel format for
  5642. this filter to work correctly. Also it assumes that both inputs
  5643. have the same number of frames, which are compared one by one.
  5644. The obtained average PSNR is printed through the logging system.
  5645. The filter stores the accumulated MSE (mean squared error) of each
  5646. frame, and at the end of the processing it is averaged across all frames
  5647. equally, and the following formula is applied to obtain the PSNR:
  5648. @example
  5649. PSNR = 10*log10(MAX^2/MSE)
  5650. @end example
  5651. Where MAX is the average of the maximum values of each component of the
  5652. image.
  5653. The description of the accepted parameters follows.
  5654. @table @option
  5655. @item stats_file, f
  5656. If specified the filter will use the named file to save the PSNR of
  5657. each individual frame.
  5658. @end table
  5659. The file printed if @var{stats_file} is selected, contains a sequence of
  5660. key/value pairs of the form @var{key}:@var{value} for each compared
  5661. couple of frames.
  5662. A description of each shown parameter follows:
  5663. @table @option
  5664. @item n
  5665. sequential number of the input frame, starting from 1
  5666. @item mse_avg
  5667. Mean Square Error pixel-by-pixel average difference of the compared
  5668. frames, averaged over all the image components.
  5669. @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a
  5670. Mean Square Error pixel-by-pixel average difference of the compared
  5671. frames for the component specified by the suffix.
  5672. @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
  5673. Peak Signal to Noise ratio of the compared frames for the component
  5674. specified by the suffix.
  5675. @end table
  5676. For example:
  5677. @example
  5678. movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
  5679. [main][ref] psnr="stats_file=stats.log" [out]
  5680. @end example
  5681. On this example the input file being processed is compared with the
  5682. reference file @file{ref_movie.mpg}. The PSNR of each individual frame
  5683. is stored in @file{stats.log}.
  5684. @anchor{pullup}
  5685. @section pullup
  5686. Pulldown reversal (inverse telecine) filter, capable of handling mixed
  5687. hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
  5688. content.
  5689. The pullup filter is designed to take advantage of future context in making
  5690. its decisions. This filter is stateless in the sense that it does not lock
  5691. onto a pattern to follow, but it instead looks forward to the following
  5692. fields in order to identify matches and rebuild progressive frames.
  5693. To produce content with an even framerate, insert the fps filter after
  5694. pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
  5695. @code{fps=24} for 30fps and the (rare) telecined 25fps input.
  5696. The filter accepts the following options:
  5697. @table @option
  5698. @item jl
  5699. @item jr
  5700. @item jt
  5701. @item jb
  5702. These options set the amount of "junk" to ignore at the left, right, top, and
  5703. bottom of the image, respectively. Left and right are in units of 8 pixels,
  5704. while top and bottom are in units of 2 lines.
  5705. The default is 8 pixels on each side.
  5706. @item sb
  5707. Set the strict breaks. Setting this option to 1 will reduce the chances of
  5708. filter generating an occasional mismatched frame, but it may also cause an
  5709. excessive number of frames to be dropped during high motion sequences.
  5710. Conversely, setting it to -1 will make filter match fields more easily.
  5711. This may help processing of video where there is slight blurring between
  5712. the fields, but may also cause there to be interlaced frames in the output.
  5713. Default value is @code{0}.
  5714. @item mp
  5715. Set the metric plane to use. It accepts the following values:
  5716. @table @samp
  5717. @item l
  5718. Use luma plane.
  5719. @item u
  5720. Use chroma blue plane.
  5721. @item v
  5722. Use chroma red plane.
  5723. @end table
  5724. This option may be set to use chroma plane instead of the default luma plane
  5725. for doing filter's computations. This may improve accuracy on very clean
  5726. source material, but more likely will decrease accuracy, especially if there
  5727. is chroma noise (rainbow effect) or any grayscale video.
  5728. The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
  5729. load and make pullup usable in realtime on slow machines.
  5730. @end table
  5731. For best results (without duplicated frames in the output file) it is
  5732. necessary to change the output frame rate. For example, to inverse
  5733. telecine NTSC input:
  5734. @example
  5735. ffmpeg -i input -vf pullup -r 24000/1001 ...
  5736. @end example
  5737. @section qp
  5738. Change video quantization parameters (QP).
  5739. The filter accepts the following option:
  5740. @table @option
  5741. @item qp
  5742. Set expression for quantization parameter.
  5743. @end table
  5744. The expression is evaluated through the eval API and can contain, among others,
  5745. the following constants:
  5746. @table @var
  5747. @item known
  5748. 1 if index is not 129, 0 otherwise.
  5749. @item qp
  5750. Sequentional index starting from -129 to 128.
  5751. @end table
  5752. @subsection Examples
  5753. @itemize
  5754. @item
  5755. Some equation like:
  5756. @example
  5757. qp=2+2*sin(PI*qp)
  5758. @end example
  5759. @end itemize
  5760. @section removelogo
  5761. Suppress a TV station logo, using an image file to determine which
  5762. pixels comprise the logo. It works by filling in the pixels that
  5763. comprise the logo with neighboring pixels.
  5764. The filter accepts the following options:
  5765. @table @option
  5766. @item filename, f
  5767. Set the filter bitmap file, which can be any image format supported by
  5768. libavformat. The width and height of the image file must match those of the
  5769. video stream being processed.
  5770. @end table
  5771. Pixels in the provided bitmap image with a value of zero are not
  5772. considered part of the logo, non-zero pixels are considered part of
  5773. the logo. If you use white (255) for the logo and black (0) for the
  5774. rest, you will be safe. For making the filter bitmap, it is
  5775. recommended to take a screen capture of a black frame with the logo
  5776. visible, and then using a threshold filter followed by the erode
  5777. filter once or twice.
  5778. If needed, little splotches can be fixed manually. Remember that if
  5779. logo pixels are not covered, the filter quality will be much
  5780. reduced. Marking too many pixels as part of the logo does not hurt as
  5781. much, but it will increase the amount of blurring needed to cover over
  5782. the image and will destroy more information than necessary, and extra
  5783. pixels will slow things down on a large logo.
  5784. @section repeatfields
  5785. This filter uses the repeat_field flag from the Video ES headers and hard repeats
  5786. fields based on its value.
  5787. @section rotate
  5788. Rotate video by an arbitrary angle expressed in radians.
  5789. The filter accepts the following options:
  5790. A description of the optional parameters follows.
  5791. @table @option
  5792. @item angle, a
  5793. Set an expression for the angle by which to rotate the input video
  5794. clockwise, expressed as a number of radians. A negative value will
  5795. result in a counter-clockwise rotation. By default it is set to "0".
  5796. This expression is evaluated for each frame.
  5797. @item out_w, ow
  5798. Set the output width expression, default value is "iw".
  5799. This expression is evaluated just once during configuration.
  5800. @item out_h, oh
  5801. Set the output height expression, default value is "ih".
  5802. This expression is evaluated just once during configuration.
  5803. @item bilinear
  5804. Enable bilinear interpolation if set to 1, a value of 0 disables
  5805. it. Default value is 1.
  5806. @item fillcolor, c
  5807. Set the color used to fill the output area not covered by the rotated
  5808. image. For the general syntax of this option, check the "Color" section in the
  5809. ffmpeg-utils manual. If the special value "none" is selected then no
  5810. background is printed (useful for example if the background is never shown).
  5811. Default value is "black".
  5812. @end table
  5813. The expressions for the angle and the output size can contain the
  5814. following constants and functions:
  5815. @table @option
  5816. @item n
  5817. sequential number of the input frame, starting from 0. It is always NAN
  5818. before the first frame is filtered.
  5819. @item t
  5820. time in seconds of the input frame, it is set to 0 when the filter is
  5821. configured. It is always NAN before the first frame is filtered.
  5822. @item hsub
  5823. @item vsub
  5824. horizontal and vertical chroma subsample values. For example for the
  5825. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  5826. @item in_w, iw
  5827. @item in_h, ih
  5828. the input video width and height
  5829. @item out_w, ow
  5830. @item out_h, oh
  5831. the output width and height, that is the size of the padded area as
  5832. specified by the @var{width} and @var{height} expressions
  5833. @item rotw(a)
  5834. @item roth(a)
  5835. the minimal width/height required for completely containing the input
  5836. video rotated by @var{a} radians.
  5837. These are only available when computing the @option{out_w} and
  5838. @option{out_h} expressions.
  5839. @end table
  5840. @subsection Examples
  5841. @itemize
  5842. @item
  5843. Rotate the input by PI/6 radians clockwise:
  5844. @example
  5845. rotate=PI/6
  5846. @end example
  5847. @item
  5848. Rotate the input by PI/6 radians counter-clockwise:
  5849. @example
  5850. rotate=-PI/6
  5851. @end example
  5852. @item
  5853. Rotate the input by 45 degrees clockwise:
  5854. @example
  5855. rotate=45*PI/180
  5856. @end example
  5857. @item
  5858. Apply a constant rotation with period T, starting from an angle of PI/3:
  5859. @example
  5860. rotate=PI/3+2*PI*t/T
  5861. @end example
  5862. @item
  5863. Make the input video rotation oscillating with a period of T
  5864. seconds and an amplitude of A radians:
  5865. @example
  5866. rotate=A*sin(2*PI/T*t)
  5867. @end example
  5868. @item
  5869. Rotate the video, output size is chosen so that the whole rotating
  5870. input video is always completely contained in the output:
  5871. @example
  5872. rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
  5873. @end example
  5874. @item
  5875. Rotate the video, reduce the output size so that no background is ever
  5876. shown:
  5877. @example
  5878. rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
  5879. @end example
  5880. @end itemize
  5881. @subsection Commands
  5882. The filter supports the following commands:
  5883. @table @option
  5884. @item a, angle
  5885. Set the angle expression.
  5886. The command accepts the same syntax of the corresponding option.
  5887. If the specified expression is not valid, it is kept at its current
  5888. value.
  5889. @end table
  5890. @section sab
  5891. Apply Shape Adaptive Blur.
  5892. The filter accepts the following options:
  5893. @table @option
  5894. @item luma_radius, lr
  5895. Set luma blur filter strength, must be a value in range 0.1-4.0, default
  5896. value is 1.0. A greater value will result in a more blurred image, and
  5897. in slower processing.
  5898. @item luma_pre_filter_radius, lpfr
  5899. Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
  5900. value is 1.0.
  5901. @item luma_strength, ls
  5902. Set luma maximum difference between pixels to still be considered, must
  5903. be a value in the 0.1-100.0 range, default value is 1.0.
  5904. @item chroma_radius, cr
  5905. Set chroma blur filter strength, must be a value in range 0.1-4.0. A
  5906. greater value will result in a more blurred image, and in slower
  5907. processing.
  5908. @item chroma_pre_filter_radius, cpfr
  5909. Set chroma pre-filter radius, must be a value in the 0.1-2.0 range.
  5910. @item chroma_strength, cs
  5911. Set chroma maximum difference between pixels to still be considered,
  5912. must be a value in the 0.1-100.0 range.
  5913. @end table
  5914. Each chroma option value, if not explicitly specified, is set to the
  5915. corresponding luma option value.
  5916. @anchor{scale}
  5917. @section scale
  5918. Scale (resize) the input video, using the libswscale library.
  5919. The scale filter forces the output display aspect ratio to be the same
  5920. of the input, by changing the output sample aspect ratio.
  5921. If the input image format is different from the format requested by
  5922. the next filter, the scale filter will convert the input to the
  5923. requested format.
  5924. @subsection Options
  5925. The filter accepts the following options, or any of the options
  5926. supported by the libswscale scaler.
  5927. See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
  5928. the complete list of scaler options.
  5929. @table @option
  5930. @item width, w
  5931. @item height, h
  5932. Set the output video dimension expression. Default value is the input
  5933. dimension.
  5934. If the value is 0, the input width is used for the output.
  5935. If one of the values is -1, the scale filter will use a value that
  5936. maintains the aspect ratio of the input image, calculated from the
  5937. other specified dimension. If both of them are -1, the input size is
  5938. used
  5939. If one of the values is -n with n > 1, the scale filter will also use a value
  5940. that maintains the aspect ratio of the input image, calculated from the other
  5941. specified dimension. After that it will, however, make sure that the calculated
  5942. dimension is divisible by n and adjust the value if necessary.
  5943. See below for the list of accepted constants for use in the dimension
  5944. expression.
  5945. @item interl
  5946. Set the interlacing mode. It accepts the following values:
  5947. @table @samp
  5948. @item 1
  5949. Force interlaced aware scaling.
  5950. @item 0
  5951. Do not apply interlaced scaling.
  5952. @item -1
  5953. Select interlaced aware scaling depending on whether the source frames
  5954. are flagged as interlaced or not.
  5955. @end table
  5956. Default value is @samp{0}.
  5957. @item flags
  5958. Set libswscale scaling flags. See
  5959. @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
  5960. complete list of values. If not explicitly specified the filter applies
  5961. the default flags.
  5962. @item size, s
  5963. Set the video size. For the syntax of this option, check the "Video size"
  5964. section in the ffmpeg-utils manual.
  5965. @item in_color_matrix
  5966. @item out_color_matrix
  5967. Set in/output YCbCr color space type.
  5968. This allows the autodetected value to be overridden as well as allows forcing
  5969. a specific value used for the output and encoder.
  5970. If not specified, the color space type depends on the pixel format.
  5971. Possible values:
  5972. @table @samp
  5973. @item auto
  5974. Choose automatically.
  5975. @item bt709
  5976. Format conforming to International Telecommunication Union (ITU)
  5977. Recommendation BT.709.
  5978. @item fcc
  5979. Set color space conforming to the United States Federal Communications
  5980. Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
  5981. @item bt601
  5982. Set color space conforming to:
  5983. @itemize
  5984. @item
  5985. ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
  5986. @item
  5987. ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
  5988. @item
  5989. Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
  5990. @end itemize
  5991. @item smpte240m
  5992. Set color space conforming to SMPTE ST 240:1999.
  5993. @end table
  5994. @item in_range
  5995. @item out_range
  5996. Set in/output YCbCr sample range.
  5997. This allows the autodetected value to be overridden as well as allows forcing
  5998. a specific value used for the output and encoder. If not specified, the
  5999. range depends on the pixel format. Possible values:
  6000. @table @samp
  6001. @item auto
  6002. Choose automatically.
  6003. @item jpeg/full/pc
  6004. Set full range (0-255 in case of 8-bit luma).
  6005. @item mpeg/tv
  6006. Set "MPEG" range (16-235 in case of 8-bit luma).
  6007. @end table
  6008. @item force_original_aspect_ratio
  6009. Enable decreasing or increasing output video width or height if necessary to
  6010. keep the original aspect ratio. Possible values:
  6011. @table @samp
  6012. @item disable
  6013. Scale the video as specified and disable this feature.
  6014. @item decrease
  6015. The output video dimensions will automatically be decreased if needed.
  6016. @item increase
  6017. The output video dimensions will automatically be increased if needed.
  6018. @end table
  6019. One useful instance of this option is that when you know a specific device's
  6020. maximum allowed resolution, you can use this to limit the output video to
  6021. that, while retaining the aspect ratio. For example, device A allows
  6022. 1280x720 playback, and your video is 1920x800. Using this option (set it to
  6023. decrease) and specifying 1280x720 to the command line makes the output
  6024. 1280x533.
  6025. Please note that this is a different thing than specifying -1 for @option{w}
  6026. or @option{h}, you still need to specify the output resolution for this option
  6027. to work.
  6028. @end table
  6029. The values of the @option{w} and @option{h} options are expressions
  6030. containing the following constants:
  6031. @table @var
  6032. @item in_w
  6033. @item in_h
  6034. The input width and height
  6035. @item iw
  6036. @item ih
  6037. These are the same as @var{in_w} and @var{in_h}.
  6038. @item out_w
  6039. @item out_h
  6040. The output (scaled) width and height
  6041. @item ow
  6042. @item oh
  6043. These are the same as @var{out_w} and @var{out_h}
  6044. @item a
  6045. The same as @var{iw} / @var{ih}
  6046. @item sar
  6047. input sample aspect ratio
  6048. @item dar
  6049. The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
  6050. @item hsub
  6051. @item vsub
  6052. horizontal and vertical input chroma subsample values. For example for the
  6053. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6054. @item ohsub
  6055. @item ovsub
  6056. horizontal and vertical output chroma subsample values. For example for the
  6057. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6058. @end table
  6059. @subsection Examples
  6060. @itemize
  6061. @item
  6062. Scale the input video to a size of 200x100
  6063. @example
  6064. scale=w=200:h=100
  6065. @end example
  6066. This is equivalent to:
  6067. @example
  6068. scale=200:100
  6069. @end example
  6070. or:
  6071. @example
  6072. scale=200x100
  6073. @end example
  6074. @item
  6075. Specify a size abbreviation for the output size:
  6076. @example
  6077. scale=qcif
  6078. @end example
  6079. which can also be written as:
  6080. @example
  6081. scale=size=qcif
  6082. @end example
  6083. @item
  6084. Scale the input to 2x:
  6085. @example
  6086. scale=w=2*iw:h=2*ih
  6087. @end example
  6088. @item
  6089. The above is the same as:
  6090. @example
  6091. scale=2*in_w:2*in_h
  6092. @end example
  6093. @item
  6094. Scale the input to 2x with forced interlaced scaling:
  6095. @example
  6096. scale=2*iw:2*ih:interl=1
  6097. @end example
  6098. @item
  6099. Scale the input to half size:
  6100. @example
  6101. scale=w=iw/2:h=ih/2
  6102. @end example
  6103. @item
  6104. Increase the width, and set the height to the same size:
  6105. @example
  6106. scale=3/2*iw:ow
  6107. @end example
  6108. @item
  6109. Seek Greek harmony:
  6110. @example
  6111. scale=iw:1/PHI*iw
  6112. scale=ih*PHI:ih
  6113. @end example
  6114. @item
  6115. Increase the height, and set the width to 3/2 of the height:
  6116. @example
  6117. scale=w=3/2*oh:h=3/5*ih
  6118. @end example
  6119. @item
  6120. Increase the size, making the size a multiple of the chroma
  6121. subsample values:
  6122. @example
  6123. scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
  6124. @end example
  6125. @item
  6126. Increase the width to a maximum of 500 pixels,
  6127. keeping the same aspect ratio as the input:
  6128. @example
  6129. scale=w='min(500\, iw*3/2):h=-1'
  6130. @end example
  6131. @end itemize
  6132. @section separatefields
  6133. The @code{separatefields} takes a frame-based video input and splits
  6134. each frame into its components fields, producing a new half height clip
  6135. with twice the frame rate and twice the frame count.
  6136. This filter use field-dominance information in frame to decide which
  6137. of each pair of fields to place first in the output.
  6138. If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
  6139. @section setdar, setsar
  6140. The @code{setdar} filter sets the Display Aspect Ratio for the filter
  6141. output video.
  6142. This is done by changing the specified Sample (aka Pixel) Aspect
  6143. Ratio, according to the following equation:
  6144. @example
  6145. @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
  6146. @end example
  6147. Keep in mind that the @code{setdar} filter does not modify the pixel
  6148. dimensions of the video frame. Also, the display aspect ratio set by
  6149. this filter may be changed by later filters in the filterchain,
  6150. e.g. in case of scaling or if another "setdar" or a "setsar" filter is
  6151. applied.
  6152. The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
  6153. the filter output video.
  6154. Note that as a consequence of the application of this filter, the
  6155. output display aspect ratio will change according to the equation
  6156. above.
  6157. Keep in mind that the sample aspect ratio set by the @code{setsar}
  6158. filter may be changed by later filters in the filterchain, e.g. if
  6159. another "setsar" or a "setdar" filter is applied.
  6160. It accepts the following parameters:
  6161. @table @option
  6162. @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
  6163. Set the aspect ratio used by the filter.
  6164. The parameter can be a floating point number string, an expression, or
  6165. a string of the form @var{num}:@var{den}, where @var{num} and
  6166. @var{den} are the numerator and denominator of the aspect ratio. If
  6167. the parameter is not specified, it is assumed the value "0".
  6168. In case the form "@var{num}:@var{den}" is used, the @code{:} character
  6169. should be escaped.
  6170. @item max
  6171. Set the maximum integer value to use for expressing numerator and
  6172. denominator when reducing the expressed aspect ratio to a rational.
  6173. Default value is @code{100}.
  6174. @end table
  6175. The parameter @var{sar} is an expression containing
  6176. the following constants:
  6177. @table @option
  6178. @item E, PI, PHI
  6179. These are approximated values for the mathematical constants e
  6180. (Euler's number), pi (Greek pi), and phi (the golden ratio).
  6181. @item w, h
  6182. The input width and height.
  6183. @item a
  6184. These are the same as @var{w} / @var{h}.
  6185. @item sar
  6186. The input sample aspect ratio.
  6187. @item dar
  6188. The input display aspect ratio. It is the same as
  6189. (@var{w} / @var{h}) * @var{sar}.
  6190. @item hsub, vsub
  6191. Horizontal and vertical chroma subsample values. For example, for the
  6192. pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
  6193. @end table
  6194. @subsection Examples
  6195. @itemize
  6196. @item
  6197. To change the display aspect ratio to 16:9, specify one of the following:
  6198. @example
  6199. setdar=dar=1.77777
  6200. setdar=dar=16/9
  6201. setdar=dar=1.77777
  6202. @end example
  6203. @item
  6204. To change the sample aspect ratio to 10:11, specify:
  6205. @example
  6206. setsar=sar=10/11
  6207. @end example
  6208. @item
  6209. To set a display aspect ratio of 16:9, and specify a maximum integer value of
  6210. 1000 in the aspect ratio reduction, use the command:
  6211. @example
  6212. setdar=ratio=16/9:max=1000
  6213. @end example
  6214. @end itemize
  6215. @anchor{setfield}
  6216. @section setfield
  6217. Force field for the output video frame.
  6218. The @code{setfield} filter marks the interlace type field for the
  6219. output frames. It does not change the input frame, but only sets the
  6220. corresponding property, which affects how the frame is treated by
  6221. following filters (e.g. @code{fieldorder} or @code{yadif}).
  6222. The filter accepts the following options:
  6223. @table @option
  6224. @item mode
  6225. Available values are:
  6226. @table @samp
  6227. @item auto
  6228. Keep the same field property.
  6229. @item bff
  6230. Mark the frame as bottom-field-first.
  6231. @item tff
  6232. Mark the frame as top-field-first.
  6233. @item prog
  6234. Mark the frame as progressive.
  6235. @end table
  6236. @end table
  6237. @section showinfo
  6238. Show a line containing various information for each input video frame.
  6239. The input video is not modified.
  6240. The shown line contains a sequence of key/value pairs of the form
  6241. @var{key}:@var{value}.
  6242. The following values are shown in the output:
  6243. @table @option
  6244. @item n
  6245. The (sequential) number of the input frame, starting from 0.
  6246. @item pts
  6247. The Presentation TimeStamp of the input frame, expressed as a number of
  6248. time base units. The time base unit depends on the filter input pad.
  6249. @item pts_time
  6250. The Presentation TimeStamp of the input frame, expressed as a number of
  6251. seconds.
  6252. @item pos
  6253. The position of the frame in the input stream, or -1 if this information is
  6254. unavailable and/or meaningless (for example in case of synthetic video).
  6255. @item fmt
  6256. The pixel format name.
  6257. @item sar
  6258. The sample aspect ratio of the input frame, expressed in the form
  6259. @var{num}/@var{den}.
  6260. @item s
  6261. The size of the input frame. For the syntax of this option, check the "Video size"
  6262. section in the ffmpeg-utils manual.
  6263. @item i
  6264. The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
  6265. for bottom field first).
  6266. @item iskey
  6267. This is 1 if the frame is a key frame, 0 otherwise.
  6268. @item type
  6269. The picture type of the input frame ("I" for an I-frame, "P" for a
  6270. P-frame, "B" for a B-frame, or "?" for an unknown type).
  6271. Also refer to the documentation of the @code{AVPictureType} enum and of
  6272. the @code{av_get_picture_type_char} function defined in
  6273. @file{libavutil/avutil.h}.
  6274. @item checksum
  6275. The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
  6276. @item plane_checksum
  6277. The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
  6278. expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
  6279. @end table
  6280. @section showpalette
  6281. Displays the 256 colors palette of each frame. This filter is only relevant for
  6282. @var{pal8} pixel format frames.
  6283. It accepts the following option:
  6284. @table @option
  6285. @item s
  6286. Set the size of the box used to represent one palette color entry. Default is
  6287. @code{30} (for a @code{30x30} pixel box).
  6288. @end table
  6289. @section shuffleplanes
  6290. Reorder and/or duplicate video planes.
  6291. It accepts the following parameters:
  6292. @table @option
  6293. @item map0
  6294. The index of the input plane to be used as the first output plane.
  6295. @item map1
  6296. The index of the input plane to be used as the second output plane.
  6297. @item map2
  6298. The index of the input plane to be used as the third output plane.
  6299. @item map3
  6300. The index of the input plane to be used as the fourth output plane.
  6301. @end table
  6302. The first plane has the index 0. The default is to keep the input unchanged.
  6303. Swap the second and third planes of the input:
  6304. @example
  6305. ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
  6306. @end example
  6307. @section signalstats
  6308. Evaluate various visual metrics that assist in determining issues associated
  6309. with the digitization of analog video media.
  6310. By default the filter will log these metadata values:
  6311. @table @option
  6312. @item YMIN
  6313. Display the minimal Y value contained within the input frame. Expressed in
  6314. range of [0-255].
  6315. @item YLOW
  6316. Display the Y value at the 10% percentile within the input frame. Expressed in
  6317. range of [0-255].
  6318. @item YAVG
  6319. Display the average Y value within the input frame. Expressed in range of
  6320. [0-255].
  6321. @item YHIGH
  6322. Display the Y value at the 90% percentile within the input frame. Expressed in
  6323. range of [0-255].
  6324. @item YMAX
  6325. Display the maximum Y value contained within the input frame. Expressed in
  6326. range of [0-255].
  6327. @item UMIN
  6328. Display the minimal U value contained within the input frame. Expressed in
  6329. range of [0-255].
  6330. @item ULOW
  6331. Display the U value at the 10% percentile within the input frame. Expressed in
  6332. range of [0-255].
  6333. @item UAVG
  6334. Display the average U value within the input frame. Expressed in range of
  6335. [0-255].
  6336. @item UHIGH
  6337. Display the U value at the 90% percentile within the input frame. Expressed in
  6338. range of [0-255].
  6339. @item UMAX
  6340. Display the maximum U value contained within the input frame. Expressed in
  6341. range of [0-255].
  6342. @item VMIN
  6343. Display the minimal V value contained within the input frame. Expressed in
  6344. range of [0-255].
  6345. @item VLOW
  6346. Display the V value at the 10% percentile within the input frame. Expressed in
  6347. range of [0-255].
  6348. @item VAVG
  6349. Display the average V value within the input frame. Expressed in range of
  6350. [0-255].
  6351. @item VHIGH
  6352. Display the V value at the 90% percentile within the input frame. Expressed in
  6353. range of [0-255].
  6354. @item VMAX
  6355. Display the maximum V value contained within the input frame. Expressed in
  6356. range of [0-255].
  6357. @item SATMIN
  6358. Display the minimal saturation value contained within the input frame.
  6359. Expressed in range of [0-~181.02].
  6360. @item SATLOW
  6361. Display the saturation value at the 10% percentile within the input frame.
  6362. Expressed in range of [0-~181.02].
  6363. @item SATAVG
  6364. Display the average saturation value within the input frame. Expressed in range
  6365. of [0-~181.02].
  6366. @item SATHIGH
  6367. Display the saturation value at the 90% percentile within the input frame.
  6368. Expressed in range of [0-~181.02].
  6369. @item SATMAX
  6370. Display the maximum saturation value contained within the input frame.
  6371. Expressed in range of [0-~181.02].
  6372. @item HUEMED
  6373. Display the median value for hue within the input frame. Expressed in range of
  6374. [0-360].
  6375. @item HUEAVG
  6376. Display the average value for hue within the input frame. Expressed in range of
  6377. [0-360].
  6378. @item YDIF
  6379. Display the average of sample value difference between all values of the Y
  6380. plane in the current frame and corresponding values of the previous input frame.
  6381. Expressed in range of [0-255].
  6382. @item UDIF
  6383. Display the average of sample value difference between all values of the U
  6384. plane in the current frame and corresponding values of the previous input frame.
  6385. Expressed in range of [0-255].
  6386. @item VDIF
  6387. Display the average of sample value difference between all values of the V
  6388. plane in the current frame and corresponding values of the previous input frame.
  6389. Expressed in range of [0-255].
  6390. @end table
  6391. The filter accepts the following options:
  6392. @table @option
  6393. @item stat
  6394. @item out
  6395. @option{stat} specify an additional form of image analysis.
  6396. @option{out} output video with the specified type of pixel highlighted.
  6397. Both options accept the following values:
  6398. @table @samp
  6399. @item tout
  6400. Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
  6401. unlike the neighboring pixels of the same field. Examples of temporal outliers
  6402. include the results of video dropouts, head clogs, or tape tracking issues.
  6403. @item vrep
  6404. Identify @var{vertical line repetition}. Vertical line repetition includes
  6405. similar rows of pixels within a frame. In born-digital video vertical line
  6406. repetition is common, but this pattern is uncommon in video digitized from an
  6407. analog source. When it occurs in video that results from the digitization of an
  6408. analog source it can indicate concealment from a dropout compensator.
  6409. @item brng
  6410. Identify pixels that fall outside of legal broadcast range.
  6411. @end table
  6412. @item color, c
  6413. Set the highlight color for the @option{out} option. The default color is
  6414. yellow.
  6415. @end table
  6416. @subsection Examples
  6417. @itemize
  6418. @item
  6419. Output data of various video metrics:
  6420. @example
  6421. ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
  6422. @end example
  6423. @item
  6424. Output specific data about the minimum and maximum values of the Y plane per frame:
  6425. @example
  6426. ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
  6427. @end example
  6428. @item
  6429. Playback video while highlighting pixels that are outside of broadcast range in red.
  6430. @example
  6431. ffplay example.mov -vf signalstats="out=brng:color=red"
  6432. @end example
  6433. @item
  6434. Playback video with signalstats metadata drawn over the frame.
  6435. @example
  6436. ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
  6437. @end example
  6438. The contents of signalstat_drawtext.txt used in the command are:
  6439. @example
  6440. time %@{pts:hms@}
  6441. Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
  6442. U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
  6443. V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
  6444. saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
  6445. @end example
  6446. @end itemize
  6447. @anchor{smartblur}
  6448. @section smartblur
  6449. Blur the input video without impacting the outlines.
  6450. It accepts the following options:
  6451. @table @option
  6452. @item luma_radius, lr
  6453. Set the luma radius. The option value must be a float number in
  6454. the range [0.1,5.0] that specifies the variance of the gaussian filter
  6455. used to blur the image (slower if larger). Default value is 1.0.
  6456. @item luma_strength, ls
  6457. Set the luma strength. The option value must be a float number
  6458. in the range [-1.0,1.0] that configures the blurring. A value included
  6459. in [0.0,1.0] will blur the image whereas a value included in
  6460. [-1.0,0.0] will sharpen the image. Default value is 1.0.
  6461. @item luma_threshold, lt
  6462. Set the luma threshold used as a coefficient to determine
  6463. whether a pixel should be blurred or not. The option value must be an
  6464. integer in the range [-30,30]. A value of 0 will filter all the image,
  6465. a value included in [0,30] will filter flat areas and a value included
  6466. in [-30,0] will filter edges. Default value is 0.
  6467. @item chroma_radius, cr
  6468. Set the chroma radius. The option value must be a float number in
  6469. the range [0.1,5.0] that specifies the variance of the gaussian filter
  6470. used to blur the image (slower if larger). Default value is 1.0.
  6471. @item chroma_strength, cs
  6472. Set the chroma strength. The option value must be a float number
  6473. in the range [-1.0,1.0] that configures the blurring. A value included
  6474. in [0.0,1.0] will blur the image whereas a value included in
  6475. [-1.0,0.0] will sharpen the image. Default value is 1.0.
  6476. @item chroma_threshold, ct
  6477. Set the chroma threshold used as a coefficient to determine
  6478. whether a pixel should be blurred or not. The option value must be an
  6479. integer in the range [-30,30]. A value of 0 will filter all the image,
  6480. a value included in [0,30] will filter flat areas and a value included
  6481. in [-30,0] will filter edges. Default value is 0.
  6482. @end table
  6483. If a chroma option is not explicitly set, the corresponding luma value
  6484. is set.
  6485. @section stereo3d
  6486. Convert between different stereoscopic image formats.
  6487. The filters accept the following options:
  6488. @table @option
  6489. @item in
  6490. Set stereoscopic image format of input.
  6491. Available values for input image formats are:
  6492. @table @samp
  6493. @item sbsl
  6494. side by side parallel (left eye left, right eye right)
  6495. @item sbsr
  6496. side by side crosseye (right eye left, left eye right)
  6497. @item sbs2l
  6498. side by side parallel with half width resolution
  6499. (left eye left, right eye right)
  6500. @item sbs2r
  6501. side by side crosseye with half width resolution
  6502. (right eye left, left eye right)
  6503. @item abl
  6504. above-below (left eye above, right eye below)
  6505. @item abr
  6506. above-below (right eye above, left eye below)
  6507. @item ab2l
  6508. above-below with half height resolution
  6509. (left eye above, right eye below)
  6510. @item ab2r
  6511. above-below with half height resolution
  6512. (right eye above, left eye below)
  6513. @item al
  6514. alternating frames (left eye first, right eye second)
  6515. @item ar
  6516. alternating frames (right eye first, left eye second)
  6517. Default value is @samp{sbsl}.
  6518. @end table
  6519. @item out
  6520. Set stereoscopic image format of output.
  6521. Available values for output image formats are all the input formats as well as:
  6522. @table @samp
  6523. @item arbg
  6524. anaglyph red/blue gray
  6525. (red filter on left eye, blue filter on right eye)
  6526. @item argg
  6527. anaglyph red/green gray
  6528. (red filter on left eye, green filter on right eye)
  6529. @item arcg
  6530. anaglyph red/cyan gray
  6531. (red filter on left eye, cyan filter on right eye)
  6532. @item arch
  6533. anaglyph red/cyan half colored
  6534. (red filter on left eye, cyan filter on right eye)
  6535. @item arcc
  6536. anaglyph red/cyan color
  6537. (red filter on left eye, cyan filter on right eye)
  6538. @item arcd
  6539. anaglyph red/cyan color optimized with the least squares projection of dubois
  6540. (red filter on left eye, cyan filter on right eye)
  6541. @item agmg
  6542. anaglyph green/magenta gray
  6543. (green filter on left eye, magenta filter on right eye)
  6544. @item agmh
  6545. anaglyph green/magenta half colored
  6546. (green filter on left eye, magenta filter on right eye)
  6547. @item agmc
  6548. anaglyph green/magenta colored
  6549. (green filter on left eye, magenta filter on right eye)
  6550. @item agmd
  6551. anaglyph green/magenta color optimized with the least squares projection of dubois
  6552. (green filter on left eye, magenta filter on right eye)
  6553. @item aybg
  6554. anaglyph yellow/blue gray
  6555. (yellow filter on left eye, blue filter on right eye)
  6556. @item aybh
  6557. anaglyph yellow/blue half colored
  6558. (yellow filter on left eye, blue filter on right eye)
  6559. @item aybc
  6560. anaglyph yellow/blue colored
  6561. (yellow filter on left eye, blue filter on right eye)
  6562. @item aybd
  6563. anaglyph yellow/blue color optimized with the least squares projection of dubois
  6564. (yellow filter on left eye, blue filter on right eye)
  6565. @item irl
  6566. interleaved rows (left eye has top row, right eye starts on next row)
  6567. @item irr
  6568. interleaved rows (right eye has top row, left eye starts on next row)
  6569. @item ml
  6570. mono output (left eye only)
  6571. @item mr
  6572. mono output (right eye only)
  6573. @end table
  6574. Default value is @samp{arcd}.
  6575. @end table
  6576. @subsection Examples
  6577. @itemize
  6578. @item
  6579. Convert input video from side by side parallel to anaglyph yellow/blue dubois:
  6580. @example
  6581. stereo3d=sbsl:aybd
  6582. @end example
  6583. @item
  6584. Convert input video from above bellow (left eye above, right eye below) to side by side crosseye.
  6585. @example
  6586. stereo3d=abl:sbsr
  6587. @end example
  6588. @end itemize
  6589. @anchor{spp}
  6590. @section spp
  6591. Apply a simple postprocessing filter that compresses and decompresses the image
  6592. at several (or - in the case of @option{quality} level @code{6} - all) shifts
  6593. and average the results.
  6594. The filter accepts the following options:
  6595. @table @option
  6596. @item quality
  6597. Set quality. This option defines the number of levels for averaging. It accepts
  6598. an integer in the range 0-6. If set to @code{0}, the filter will have no
  6599. effect. A value of @code{6} means the higher quality. For each increment of
  6600. that value the speed drops by a factor of approximately 2. Default value is
  6601. @code{3}.
  6602. @item qp
  6603. Force a constant quantization parameter. If not set, the filter will use the QP
  6604. from the video stream (if available).
  6605. @item mode
  6606. Set thresholding mode. Available modes are:
  6607. @table @samp
  6608. @item hard
  6609. Set hard thresholding (default).
  6610. @item soft
  6611. Set soft thresholding (better de-ringing effect, but likely blurrier).
  6612. @end table
  6613. @item use_bframe_qp
  6614. Enable the use of the QP from the B-Frames if set to @code{1}. Using this
  6615. option may cause flicker since the B-Frames have often larger QP. Default is
  6616. @code{0} (not enabled).
  6617. @end table
  6618. @anchor{subtitles}
  6619. @section subtitles
  6620. Draw subtitles on top of input video using the libass library.
  6621. To enable compilation of this filter you need to configure FFmpeg with
  6622. @code{--enable-libass}. This filter also requires a build with libavcodec and
  6623. libavformat to convert the passed subtitles file to ASS (Advanced Substation
  6624. Alpha) subtitles format.
  6625. The filter accepts the following options:
  6626. @table @option
  6627. @item filename, f
  6628. Set the filename of the subtitle file to read. It must be specified.
  6629. @item original_size
  6630. Specify the size of the original video, the video for which the ASS file
  6631. was composed. For the syntax of this option, check the "Video size" section in
  6632. the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic,
  6633. this is necessary to correctly scale the fonts if the aspect ratio has been
  6634. changed.
  6635. @item charenc
  6636. Set subtitles input character encoding. @code{subtitles} filter only. Only
  6637. useful if not UTF-8.
  6638. @item stream_index, si
  6639. Set subtitles stream index. @code{subtitles} filter only.
  6640. @item force_style
  6641. Override default style or script info parameters of the subtitles. It accepts a
  6642. string containing ASS style format @code{KEY=VALUE} couples separated by ",".
  6643. @end table
  6644. If the first key is not specified, it is assumed that the first value
  6645. specifies the @option{filename}.
  6646. For example, to render the file @file{sub.srt} on top of the input
  6647. video, use the command:
  6648. @example
  6649. subtitles=sub.srt
  6650. @end example
  6651. which is equivalent to:
  6652. @example
  6653. subtitles=filename=sub.srt
  6654. @end example
  6655. To render the default subtitles stream from file @file{video.mkv}, use:
  6656. @example
  6657. subtitles=video.mkv
  6658. @end example
  6659. To render the second subtitles stream from that file, use:
  6660. @example
  6661. subtitles=video.mkv:si=1
  6662. @end example
  6663. To make the subtitles stream from @file{sub.srt} appear in transparent green
  6664. @code{DejaVu Serif}, use:
  6665. @example
  6666. subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HAA00FF00'
  6667. @end example
  6668. @section super2xsai
  6669. Scale the input by 2x and smooth using the Super2xSaI (Scale and
  6670. Interpolate) pixel art scaling algorithm.
  6671. Useful for enlarging pixel art images without reducing sharpness.
  6672. @section swapuv
  6673. Swap U & V plane.
  6674. @section telecine
  6675. Apply telecine process to the video.
  6676. This filter accepts the following options:
  6677. @table @option
  6678. @item first_field
  6679. @table @samp
  6680. @item top, t
  6681. top field first
  6682. @item bottom, b
  6683. bottom field first
  6684. The default value is @code{top}.
  6685. @end table
  6686. @item pattern
  6687. A string of numbers representing the pulldown pattern you wish to apply.
  6688. The default value is @code{23}.
  6689. @end table
  6690. @example
  6691. Some typical patterns:
  6692. NTSC output (30i):
  6693. 27.5p: 32222
  6694. 24p: 23 (classic)
  6695. 24p: 2332 (preferred)
  6696. 20p: 33
  6697. 18p: 334
  6698. 16p: 3444
  6699. PAL output (25i):
  6700. 27.5p: 12222
  6701. 24p: 222222222223 ("Euro pulldown")
  6702. 16.67p: 33
  6703. 16p: 33333334
  6704. @end example
  6705. @section thumbnail
  6706. Select the most representative frame in a given sequence of consecutive frames.
  6707. The filter accepts the following options:
  6708. @table @option
  6709. @item n
  6710. Set the frames batch size to analyze; in a set of @var{n} frames, the filter
  6711. will pick one of them, and then handle the next batch of @var{n} frames until
  6712. the end. Default is @code{100}.
  6713. @end table
  6714. Since the filter keeps track of the whole frames sequence, a bigger @var{n}
  6715. value will result in a higher memory usage, so a high value is not recommended.
  6716. @subsection Examples
  6717. @itemize
  6718. @item
  6719. Extract one picture each 50 frames:
  6720. @example
  6721. thumbnail=50
  6722. @end example
  6723. @item
  6724. Complete example of a thumbnail creation with @command{ffmpeg}:
  6725. @example
  6726. ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
  6727. @end example
  6728. @end itemize
  6729. @section tile
  6730. Tile several successive frames together.
  6731. The filter accepts the following options:
  6732. @table @option
  6733. @item layout
  6734. Set the grid size (i.e. the number of lines and columns). For the syntax of
  6735. this option, check the "Video size" section in the ffmpeg-utils manual.
  6736. @item nb_frames
  6737. Set the maximum number of frames to render in the given area. It must be less
  6738. than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
  6739. the area will be used.
  6740. @item margin
  6741. Set the outer border margin in pixels.
  6742. @item padding
  6743. Set the inner border thickness (i.e. the number of pixels between frames). For
  6744. more advanced padding options (such as having different values for the edges),
  6745. refer to the pad video filter.
  6746. @item color
  6747. Specify the color of the unused area. For the syntax of this option, check the
  6748. "Color" section in the ffmpeg-utils manual. The default value of @var{color}
  6749. is "black".
  6750. @end table
  6751. @subsection Examples
  6752. @itemize
  6753. @item
  6754. Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
  6755. @example
  6756. ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
  6757. @end example
  6758. The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
  6759. duplicating each output frame to accommodate the originally detected frame
  6760. rate.
  6761. @item
  6762. Display @code{5} pictures in an area of @code{3x2} frames,
  6763. with @code{7} pixels between them, and @code{2} pixels of initial margin, using
  6764. mixed flat and named options:
  6765. @example
  6766. tile=3x2:nb_frames=5:padding=7:margin=2
  6767. @end example
  6768. @end itemize
  6769. @section tinterlace
  6770. Perform various types of temporal field interlacing.
  6771. Frames are counted starting from 1, so the first input frame is
  6772. considered odd.
  6773. The filter accepts the following options:
  6774. @table @option
  6775. @item mode
  6776. Specify the mode of the interlacing. This option can also be specified
  6777. as a value alone. See below for a list of values for this option.
  6778. Available values are:
  6779. @table @samp
  6780. @item merge, 0
  6781. Move odd frames into the upper field, even into the lower field,
  6782. generating a double height frame at half frame rate.
  6783. @example
  6784. ------> time
  6785. Input:
  6786. Frame 1 Frame 2 Frame 3 Frame 4
  6787. 11111 22222 33333 44444
  6788. 11111 22222 33333 44444
  6789. 11111 22222 33333 44444
  6790. 11111 22222 33333 44444
  6791. Output:
  6792. 11111 33333
  6793. 22222 44444
  6794. 11111 33333
  6795. 22222 44444
  6796. 11111 33333
  6797. 22222 44444
  6798. 11111 33333
  6799. 22222 44444
  6800. @end example
  6801. @item drop_odd, 1
  6802. Only output even frames, odd frames are dropped, generating a frame with
  6803. unchanged height at half frame rate.
  6804. @example
  6805. ------> time
  6806. Input:
  6807. Frame 1 Frame 2 Frame 3 Frame 4
  6808. 11111 22222 33333 44444
  6809. 11111 22222 33333 44444
  6810. 11111 22222 33333 44444
  6811. 11111 22222 33333 44444
  6812. Output:
  6813. 22222 44444
  6814. 22222 44444
  6815. 22222 44444
  6816. 22222 44444
  6817. @end example
  6818. @item drop_even, 2
  6819. Only output odd frames, even frames are dropped, generating a frame with
  6820. unchanged height at half frame rate.
  6821. @example
  6822. ------> time
  6823. Input:
  6824. Frame 1 Frame 2 Frame 3 Frame 4
  6825. 11111 22222 33333 44444
  6826. 11111 22222 33333 44444
  6827. 11111 22222 33333 44444
  6828. 11111 22222 33333 44444
  6829. Output:
  6830. 11111 33333
  6831. 11111 33333
  6832. 11111 33333
  6833. 11111 33333
  6834. @end example
  6835. @item pad, 3
  6836. Expand each frame to full height, but pad alternate lines with black,
  6837. generating a frame with double height at the same input frame rate.
  6838. @example
  6839. ------> time
  6840. Input:
  6841. Frame 1 Frame 2 Frame 3 Frame 4
  6842. 11111 22222 33333 44444
  6843. 11111 22222 33333 44444
  6844. 11111 22222 33333 44444
  6845. 11111 22222 33333 44444
  6846. Output:
  6847. 11111 ..... 33333 .....
  6848. ..... 22222 ..... 44444
  6849. 11111 ..... 33333 .....
  6850. ..... 22222 ..... 44444
  6851. 11111 ..... 33333 .....
  6852. ..... 22222 ..... 44444
  6853. 11111 ..... 33333 .....
  6854. ..... 22222 ..... 44444
  6855. @end example
  6856. @item interleave_top, 4
  6857. Interleave the upper field from odd frames with the lower field from
  6858. even frames, generating a frame with unchanged height at half frame rate.
  6859. @example
  6860. ------> time
  6861. Input:
  6862. Frame 1 Frame 2 Frame 3 Frame 4
  6863. 11111<- 22222 33333<- 44444
  6864. 11111 22222<- 33333 44444<-
  6865. 11111<- 22222 33333<- 44444
  6866. 11111 22222<- 33333 44444<-
  6867. Output:
  6868. 11111 33333
  6869. 22222 44444
  6870. 11111 33333
  6871. 22222 44444
  6872. @end example
  6873. @item interleave_bottom, 5
  6874. Interleave the lower field from odd frames with the upper field from
  6875. even frames, generating a frame with unchanged height at half frame rate.
  6876. @example
  6877. ------> time
  6878. Input:
  6879. Frame 1 Frame 2 Frame 3 Frame 4
  6880. 11111 22222<- 33333 44444<-
  6881. 11111<- 22222 33333<- 44444
  6882. 11111 22222<- 33333 44444<-
  6883. 11111<- 22222 33333<- 44444
  6884. Output:
  6885. 22222 44444
  6886. 11111 33333
  6887. 22222 44444
  6888. 11111 33333
  6889. @end example
  6890. @item interlacex2, 6
  6891. Double frame rate with unchanged height. Frames are inserted each
  6892. containing the second temporal field from the previous input frame and
  6893. the first temporal field from the next input frame. This mode relies on
  6894. the top_field_first flag. Useful for interlaced video displays with no
  6895. field synchronisation.
  6896. @example
  6897. ------> time
  6898. Input:
  6899. Frame 1 Frame 2 Frame 3 Frame 4
  6900. 11111 22222 33333 44444
  6901. 11111 22222 33333 44444
  6902. 11111 22222 33333 44444
  6903. 11111 22222 33333 44444
  6904. Output:
  6905. 11111 22222 22222 33333 33333 44444 44444
  6906. 11111 11111 22222 22222 33333 33333 44444
  6907. 11111 22222 22222 33333 33333 44444 44444
  6908. 11111 11111 22222 22222 33333 33333 44444
  6909. @end example
  6910. @end table
  6911. Numeric values are deprecated but are accepted for backward
  6912. compatibility reasons.
  6913. Default mode is @code{merge}.
  6914. @item flags
  6915. Specify flags influencing the filter process.
  6916. Available value for @var{flags} is:
  6917. @table @option
  6918. @item low_pass_filter, vlfp
  6919. Enable vertical low-pass filtering in the filter.
  6920. Vertical low-pass filtering is required when creating an interlaced
  6921. destination from a progressive source which contains high-frequency
  6922. vertical detail. Filtering will reduce interlace 'twitter' and Moire
  6923. patterning.
  6924. Vertical low-pass filtering can only be enabled for @option{mode}
  6925. @var{interleave_top} and @var{interleave_bottom}.
  6926. @end table
  6927. @end table
  6928. @section transpose
  6929. Transpose rows with columns in the input video and optionally flip it.
  6930. It accepts the following parameters:
  6931. @table @option
  6932. @item dir
  6933. Specify the transposition direction.
  6934. Can assume the following values:
  6935. @table @samp
  6936. @item 0, 4, cclock_flip
  6937. Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
  6938. @example
  6939. L.R L.l
  6940. . . -> . .
  6941. l.r R.r
  6942. @end example
  6943. @item 1, 5, clock
  6944. Rotate by 90 degrees clockwise, that is:
  6945. @example
  6946. L.R l.L
  6947. . . -> . .
  6948. l.r r.R
  6949. @end example
  6950. @item 2, 6, cclock
  6951. Rotate by 90 degrees counterclockwise, that is:
  6952. @example
  6953. L.R R.r
  6954. . . -> . .
  6955. l.r L.l
  6956. @end example
  6957. @item 3, 7, clock_flip
  6958. Rotate by 90 degrees clockwise and vertically flip, that is:
  6959. @example
  6960. L.R r.R
  6961. . . -> . .
  6962. l.r l.L
  6963. @end example
  6964. @end table
  6965. For values between 4-7, the transposition is only done if the input
  6966. video geometry is portrait and not landscape. These values are
  6967. deprecated, the @code{passthrough} option should be used instead.
  6968. Numerical values are deprecated, and should be dropped in favor of
  6969. symbolic constants.
  6970. @item passthrough
  6971. Do not apply the transposition if the input geometry matches the one
  6972. specified by the specified value. It accepts the following values:
  6973. @table @samp
  6974. @item none
  6975. Always apply transposition.
  6976. @item portrait
  6977. Preserve portrait geometry (when @var{height} >= @var{width}).
  6978. @item landscape
  6979. Preserve landscape geometry (when @var{width} >= @var{height}).
  6980. @end table
  6981. Default value is @code{none}.
  6982. @end table
  6983. For example to rotate by 90 degrees clockwise and preserve portrait
  6984. layout:
  6985. @example
  6986. transpose=dir=1:passthrough=portrait
  6987. @end example
  6988. The command above can also be specified as:
  6989. @example
  6990. transpose=1:portrait
  6991. @end example
  6992. @section trim
  6993. Trim the input so that the output contains one continuous subpart of the input.
  6994. It accepts the following parameters:
  6995. @table @option
  6996. @item start
  6997. Specify the time of the start of the kept section, i.e. the frame with the
  6998. timestamp @var{start} will be the first frame in the output.
  6999. @item end
  7000. Specify the time of the first frame that will be dropped, i.e. the frame
  7001. immediately preceding the one with the timestamp @var{end} will be the last
  7002. frame in the output.
  7003. @item start_pts
  7004. This is the same as @var{start}, except this option sets the start timestamp
  7005. in timebase units instead of seconds.
  7006. @item end_pts
  7007. This is the same as @var{end}, except this option sets the end timestamp
  7008. in timebase units instead of seconds.
  7009. @item duration
  7010. The maximum duration of the output in seconds.
  7011. @item start_frame
  7012. The number of the first frame that should be passed to the output.
  7013. @item end_frame
  7014. The number of the first frame that should be dropped.
  7015. @end table
  7016. @option{start}, @option{end}, and @option{duration} are expressed as time
  7017. duration specifications; see
  7018. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  7019. for the accepted syntax.
  7020. Note that the first two sets of the start/end options and the @option{duration}
  7021. option look at the frame timestamp, while the _frame variants simply count the
  7022. frames that pass through the filter. Also note that this filter does not modify
  7023. the timestamps. If you wish for the output timestamps to start at zero, insert a
  7024. setpts filter after the trim filter.
  7025. If multiple start or end options are set, this filter tries to be greedy and
  7026. keep all the frames that match at least one of the specified constraints. To keep
  7027. only the part that matches all the constraints at once, chain multiple trim
  7028. filters.
  7029. The defaults are such that all the input is kept. So it is possible to set e.g.
  7030. just the end values to keep everything before the specified time.
  7031. Examples:
  7032. @itemize
  7033. @item
  7034. Drop everything except the second minute of input:
  7035. @example
  7036. ffmpeg -i INPUT -vf trim=60:120
  7037. @end example
  7038. @item
  7039. Keep only the first second:
  7040. @example
  7041. ffmpeg -i INPUT -vf trim=duration=1
  7042. @end example
  7043. @end itemize
  7044. @anchor{unsharp}
  7045. @section unsharp
  7046. Sharpen or blur the input video.
  7047. It accepts the following parameters:
  7048. @table @option
  7049. @item luma_msize_x, lx
  7050. Set the luma matrix horizontal size. It must be an odd integer between
  7051. 3 and 63. The default value is 5.
  7052. @item luma_msize_y, ly
  7053. Set the luma matrix vertical size. It must be an odd integer between 3
  7054. and 63. The default value is 5.
  7055. @item luma_amount, la
  7056. Set the luma effect strength. It must be a floating point number, reasonable
  7057. values lay between -1.5 and 1.5.
  7058. Negative values will blur the input video, while positive values will
  7059. sharpen it, a value of zero will disable the effect.
  7060. Default value is 1.0.
  7061. @item chroma_msize_x, cx
  7062. Set the chroma matrix horizontal size. It must be an odd integer
  7063. between 3 and 63. The default value is 5.
  7064. @item chroma_msize_y, cy
  7065. Set the chroma matrix vertical size. It must be an odd integer
  7066. between 3 and 63. The default value is 5.
  7067. @item chroma_amount, ca
  7068. Set the chroma effect strength. It must be a floating point number, reasonable
  7069. values lay between -1.5 and 1.5.
  7070. Negative values will blur the input video, while positive values will
  7071. sharpen it, a value of zero will disable the effect.
  7072. Default value is 0.0.
  7073. @item opencl
  7074. If set to 1, specify using OpenCL capabilities, only available if
  7075. FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
  7076. @end table
  7077. All parameters are optional and default to the equivalent of the
  7078. string '5:5:1.0:5:5:0.0'.
  7079. @subsection Examples
  7080. @itemize
  7081. @item
  7082. Apply strong luma sharpen effect:
  7083. @example
  7084. unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
  7085. @end example
  7086. @item
  7087. Apply a strong blur of both luma and chroma parameters:
  7088. @example
  7089. unsharp=7:7:-2:7:7:-2
  7090. @end example
  7091. @end itemize
  7092. @section uspp
  7093. Apply ultra slow/simple postprocessing filter that compresses and decompresses
  7094. the image at several (or - in the case of @option{quality} level @code{8} - all)
  7095. shifts and average the results.
  7096. The way this differs from the behavior of spp is that uspp actually encodes &
  7097. decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
  7098. DCT similar to MJPEG.
  7099. The filter accepts the following options:
  7100. @table @option
  7101. @item quality
  7102. Set quality. This option defines the number of levels for averaging. It accepts
  7103. an integer in the range 0-8. If set to @code{0}, the filter will have no
  7104. effect. A value of @code{8} means the higher quality. For each increment of
  7105. that value the speed drops by a factor of approximately 2. Default value is
  7106. @code{3}.
  7107. @item qp
  7108. Force a constant quantization parameter. If not set, the filter will use the QP
  7109. from the video stream (if available).
  7110. @end table
  7111. @anchor{vidstabdetect}
  7112. @section vidstabdetect
  7113. Analyze video stabilization/deshaking. Perform pass 1 of 2, see
  7114. @ref{vidstabtransform} for pass 2.
  7115. This filter generates a file with relative translation and rotation
  7116. transform information about subsequent frames, which is then used by
  7117. the @ref{vidstabtransform} filter.
  7118. To enable compilation of this filter you need to configure FFmpeg with
  7119. @code{--enable-libvidstab}.
  7120. This filter accepts the following options:
  7121. @table @option
  7122. @item result
  7123. Set the path to the file used to write the transforms information.
  7124. Default value is @file{transforms.trf}.
  7125. @item shakiness
  7126. Set how shaky the video is and how quick the camera is. It accepts an
  7127. integer in the range 1-10, a value of 1 means little shakiness, a
  7128. value of 10 means strong shakiness. Default value is 5.
  7129. @item accuracy
  7130. Set the accuracy of the detection process. It must be a value in the
  7131. range 1-15. A value of 1 means low accuracy, a value of 15 means high
  7132. accuracy. Default value is 15.
  7133. @item stepsize
  7134. Set stepsize of the search process. The region around minimum is
  7135. scanned with 1 pixel resolution. Default value is 6.
  7136. @item mincontrast
  7137. Set minimum contrast. Below this value a local measurement field is
  7138. discarded. Must be a floating point value in the range 0-1. Default
  7139. value is 0.3.
  7140. @item tripod
  7141. Set reference frame number for tripod mode.
  7142. If enabled, the motion of the frames is compared to a reference frame
  7143. in the filtered stream, identified by the specified number. The idea
  7144. is to compensate all movements in a more-or-less static scene and keep
  7145. the camera view absolutely still.
  7146. If set to 0, it is disabled. The frames are counted starting from 1.
  7147. @item show
  7148. Show fields and transforms in the resulting frames. It accepts an
  7149. integer in the range 0-2. Default value is 0, which disables any
  7150. visualization.
  7151. @end table
  7152. @subsection Examples
  7153. @itemize
  7154. @item
  7155. Use default values:
  7156. @example
  7157. vidstabdetect
  7158. @end example
  7159. @item
  7160. Analyze strongly shaky movie and put the results in file
  7161. @file{mytransforms.trf}:
  7162. @example
  7163. vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
  7164. @end example
  7165. @item
  7166. Visualize the result of internal transformations in the resulting
  7167. video:
  7168. @example
  7169. vidstabdetect=show=1
  7170. @end example
  7171. @item
  7172. Analyze a video with medium shakiness using @command{ffmpeg}:
  7173. @example
  7174. ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
  7175. @end example
  7176. @end itemize
  7177. @anchor{vidstabtransform}
  7178. @section vidstabtransform
  7179. Video stabilization/deshaking: pass 2 of 2,
  7180. see @ref{vidstabdetect} for pass 1.
  7181. Read a file with transform information for each frame and
  7182. apply/compensate them. Together with the @ref{vidstabdetect}
  7183. filter this can be used to deshake videos. See also
  7184. @url{http://public.hronopik.de/vid.stab}. It is important to also use
  7185. the @ref{unsharp} filter, see below.
  7186. To enable compilation of this filter you need to configure FFmpeg with
  7187. @code{--enable-libvidstab}.
  7188. @subsection Options
  7189. @table @option
  7190. @item input
  7191. Set path to the file used to read the transforms. Default value is
  7192. @file{transforms.trf}.
  7193. @item smoothing
  7194. Set the number of frames (value*2 + 1) used for lowpass filtering the
  7195. camera movements. Default value is 10.
  7196. For example a number of 10 means that 21 frames are used (10 in the
  7197. past and 10 in the future) to smoothen the motion in the video. A
  7198. larger value leads to a smoother video, but limits the acceleration of
  7199. the camera (pan/tilt movements). 0 is a special case where a static
  7200. camera is simulated.
  7201. @item optalgo
  7202. Set the camera path optimization algorithm.
  7203. Accepted values are:
  7204. @table @samp
  7205. @item gauss
  7206. gaussian kernel low-pass filter on camera motion (default)
  7207. @item avg
  7208. averaging on transformations
  7209. @end table
  7210. @item maxshift
  7211. Set maximal number of pixels to translate frames. Default value is -1,
  7212. meaning no limit.
  7213. @item maxangle
  7214. Set maximal angle in radians (degree*PI/180) to rotate frames. Default
  7215. value is -1, meaning no limit.
  7216. @item crop
  7217. Specify how to deal with borders that may be visible due to movement
  7218. compensation.
  7219. Available values are:
  7220. @table @samp
  7221. @item keep
  7222. keep image information from previous frame (default)
  7223. @item black
  7224. fill the border black
  7225. @end table
  7226. @item invert
  7227. Invert transforms if set to 1. Default value is 0.
  7228. @item relative
  7229. Consider transforms as relative to previous frame if set to 1,
  7230. absolute if set to 0. Default value is 0.
  7231. @item zoom
  7232. Set percentage to zoom. A positive value will result in a zoom-in
  7233. effect, a negative value in a zoom-out effect. Default value is 0 (no
  7234. zoom).
  7235. @item optzoom
  7236. Set optimal zooming to avoid borders.
  7237. Accepted values are:
  7238. @table @samp
  7239. @item 0
  7240. disabled
  7241. @item 1
  7242. optimal static zoom value is determined (only very strong movements
  7243. will lead to visible borders) (default)
  7244. @item 2
  7245. optimal adaptive zoom value is determined (no borders will be
  7246. visible), see @option{zoomspeed}
  7247. @end table
  7248. Note that the value given at zoom is added to the one calculated here.
  7249. @item zoomspeed
  7250. Set percent to zoom maximally each frame (enabled when
  7251. @option{optzoom} is set to 2). Range is from 0 to 5, default value is
  7252. 0.25.
  7253. @item interpol
  7254. Specify type of interpolation.
  7255. Available values are:
  7256. @table @samp
  7257. @item no
  7258. no interpolation
  7259. @item linear
  7260. linear only horizontal
  7261. @item bilinear
  7262. linear in both directions (default)
  7263. @item bicubic
  7264. cubic in both directions (slow)
  7265. @end table
  7266. @item tripod
  7267. Enable virtual tripod mode if set to 1, which is equivalent to
  7268. @code{relative=0:smoothing=0}. Default value is 0.
  7269. Use also @code{tripod} option of @ref{vidstabdetect}.
  7270. @item debug
  7271. Increase log verbosity if set to 1. Also the detected global motions
  7272. are written to the temporary file @file{global_motions.trf}. Default
  7273. value is 0.
  7274. @end table
  7275. @subsection Examples
  7276. @itemize
  7277. @item
  7278. Use @command{ffmpeg} for a typical stabilization with default values:
  7279. @example
  7280. ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
  7281. @end example
  7282. Note the use of the @ref{unsharp} filter which is always recommended.
  7283. @item
  7284. Zoom in a bit more and load transform data from a given file:
  7285. @example
  7286. vidstabtransform=zoom=5:input="mytransforms.trf"
  7287. @end example
  7288. @item
  7289. Smoothen the video even more:
  7290. @example
  7291. vidstabtransform=smoothing=30
  7292. @end example
  7293. @end itemize
  7294. @section vflip
  7295. Flip the input video vertically.
  7296. For example, to vertically flip a video with @command{ffmpeg}:
  7297. @example
  7298. ffmpeg -i in.avi -vf "vflip" out.avi
  7299. @end example
  7300. @anchor{vignette}
  7301. @section vignette
  7302. Make or reverse a natural vignetting effect.
  7303. The filter accepts the following options:
  7304. @table @option
  7305. @item angle, a
  7306. Set lens angle expression as a number of radians.
  7307. The value is clipped in the @code{[0,PI/2]} range.
  7308. Default value: @code{"PI/5"}
  7309. @item x0
  7310. @item y0
  7311. Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
  7312. by default.
  7313. @item mode
  7314. Set forward/backward mode.
  7315. Available modes are:
  7316. @table @samp
  7317. @item forward
  7318. The larger the distance from the central point, the darker the image becomes.
  7319. @item backward
  7320. The larger the distance from the central point, the brighter the image becomes.
  7321. This can be used to reverse a vignette effect, though there is no automatic
  7322. detection to extract the lens @option{angle} and other settings (yet). It can
  7323. also be used to create a burning effect.
  7324. @end table
  7325. Default value is @samp{forward}.
  7326. @item eval
  7327. Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
  7328. It accepts the following values:
  7329. @table @samp
  7330. @item init
  7331. Evaluate expressions only once during the filter initialization.
  7332. @item frame
  7333. Evaluate expressions for each incoming frame. This is way slower than the
  7334. @samp{init} mode since it requires all the scalers to be re-computed, but it
  7335. allows advanced dynamic expressions.
  7336. @end table
  7337. Default value is @samp{init}.
  7338. @item dither
  7339. Set dithering to reduce the circular banding effects. Default is @code{1}
  7340. (enabled).
  7341. @item aspect
  7342. Set vignette aspect. This setting allows one to adjust the shape of the vignette.
  7343. Setting this value to the SAR of the input will make a rectangular vignetting
  7344. following the dimensions of the video.
  7345. Default is @code{1/1}.
  7346. @end table
  7347. @subsection Expressions
  7348. The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
  7349. following parameters.
  7350. @table @option
  7351. @item w
  7352. @item h
  7353. input width and height
  7354. @item n
  7355. the number of input frame, starting from 0
  7356. @item pts
  7357. the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
  7358. @var{TB} units, NAN if undefined
  7359. @item r
  7360. frame rate of the input video, NAN if the input frame rate is unknown
  7361. @item t
  7362. the PTS (Presentation TimeStamp) of the filtered video frame,
  7363. expressed in seconds, NAN if undefined
  7364. @item tb
  7365. time base of the input video
  7366. @end table
  7367. @subsection Examples
  7368. @itemize
  7369. @item
  7370. Apply simple strong vignetting effect:
  7371. @example
  7372. vignette=PI/4
  7373. @end example
  7374. @item
  7375. Make a flickering vignetting:
  7376. @example
  7377. vignette='PI/4+random(1)*PI/50':eval=frame
  7378. @end example
  7379. @end itemize
  7380. @section w3fdif
  7381. Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
  7382. Deinterlacing Filter").
  7383. Based on the process described by Martin Weston for BBC R&D, and
  7384. implemented based on the de-interlace algorithm written by Jim
  7385. Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
  7386. uses filter coefficients calculated by BBC R&D.
  7387. There are two sets of filter coefficients, so called "simple":
  7388. and "complex". Which set of filter coefficients is used can
  7389. be set by passing an optional parameter:
  7390. @table @option
  7391. @item filter
  7392. Set the interlacing filter coefficients. Accepts one of the following values:
  7393. @table @samp
  7394. @item simple
  7395. Simple filter coefficient set.
  7396. @item complex
  7397. More-complex filter coefficient set.
  7398. @end table
  7399. Default value is @samp{complex}.
  7400. @item deint
  7401. Specify which frames to deinterlace. Accept one of the following values:
  7402. @table @samp
  7403. @item all
  7404. Deinterlace all frames,
  7405. @item interlaced
  7406. Only deinterlace frames marked as interlaced.
  7407. @end table
  7408. Default value is @samp{all}.
  7409. @end table
  7410. @section xbr
  7411. Apply the xBR high-quality magnification filter which is designed for pixel
  7412. art. It follows a set of edge-detection rules, see
  7413. @url{http://www.libretro.com/forums/viewtopic.php?f=6&t=134}.
  7414. It accepts the following option:
  7415. @table @option
  7416. @item n
  7417. Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
  7418. @code{3xBR} and @code{4} for @code{4xBR}.
  7419. Default is @code{3}.
  7420. @end table
  7421. @anchor{yadif}
  7422. @section yadif
  7423. Deinterlace the input video ("yadif" means "yet another deinterlacing
  7424. filter").
  7425. It accepts the following parameters:
  7426. @table @option
  7427. @item mode
  7428. The interlacing mode to adopt. It accepts one of the following values:
  7429. @table @option
  7430. @item 0, send_frame
  7431. Output one frame for each frame.
  7432. @item 1, send_field
  7433. Output one frame for each field.
  7434. @item 2, send_frame_nospatial
  7435. Like @code{send_frame}, but it skips the spatial interlacing check.
  7436. @item 3, send_field_nospatial
  7437. Like @code{send_field}, but it skips the spatial interlacing check.
  7438. @end table
  7439. The default value is @code{send_frame}.
  7440. @item parity
  7441. The picture field parity assumed for the input interlaced video. It accepts one
  7442. of the following values:
  7443. @table @option
  7444. @item 0, tff
  7445. Assume the top field is first.
  7446. @item 1, bff
  7447. Assume the bottom field is first.
  7448. @item -1, auto
  7449. Enable automatic detection of field parity.
  7450. @end table
  7451. The default value is @code{auto}.
  7452. If the interlacing is unknown or the decoder does not export this information,
  7453. top field first will be assumed.
  7454. @item deint
  7455. Specify which frames to deinterlace. Accept one of the following
  7456. values:
  7457. @table @option
  7458. @item 0, all
  7459. Deinterlace all frames.
  7460. @item 1, interlaced
  7461. Only deinterlace frames marked as interlaced.
  7462. @end table
  7463. The default value is @code{all}.
  7464. @end table
  7465. @section zoompan
  7466. Apply Zoom & Pan effect.
  7467. This filter accepts the following options:
  7468. @table @option
  7469. @item zoom, z
  7470. Set the zoom expression. Default is 1.
  7471. @item x
  7472. @item y
  7473. Set the x and y expression. Default is 0.
  7474. @item d
  7475. Set the duration expression in number of frames.
  7476. This sets for how many number of frames effect will last for
  7477. single input image.
  7478. @item s
  7479. Set the output image size, default is 'hd720'.
  7480. @end table
  7481. Each expression can contain the following constants:
  7482. @table @option
  7483. @item in_w, iw
  7484. Input width.
  7485. @item in_h, ih
  7486. Input height.
  7487. @item out_w, ow
  7488. Output width.
  7489. @item out_h, oh
  7490. Output height.
  7491. @item in
  7492. Input frame count.
  7493. @item on
  7494. Output frame count.
  7495. @item x
  7496. @item y
  7497. Last calculated 'x' and 'y' position from 'x' and 'y' expression
  7498. for current input frame.
  7499. @item px
  7500. @item py
  7501. 'x' and 'y' of last output frame of previous input frame or 0 when there was
  7502. not yet such frame (first input frame).
  7503. @item zoom
  7504. Last calculated zoom from 'z' expression for current input frame.
  7505. @item pzoom
  7506. Last calculated zoom of last output frame of previous input frame.
  7507. @item duration
  7508. Number of output frames for current input frame. Calculated from 'd' expression
  7509. for each input frame.
  7510. @item pduration
  7511. number of output frames created for previous input frame
  7512. @item a
  7513. Rational number: input width / input height
  7514. @item sar
  7515. sample aspect ratio
  7516. @item dar
  7517. display aspect ratio
  7518. @end table
  7519. @subsection Examples
  7520. @itemize
  7521. @item
  7522. Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
  7523. @example
  7524. 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
  7525. @end example
  7526. @end itemize
  7527. @c man end VIDEO FILTERS
  7528. @chapter Video Sources
  7529. @c man begin VIDEO SOURCES
  7530. Below is a description of the currently available video sources.
  7531. @section buffer
  7532. Buffer video frames, and make them available to the filter chain.
  7533. This source is mainly intended for a programmatic use, in particular
  7534. through the interface defined in @file{libavfilter/vsrc_buffer.h}.
  7535. It accepts the following parameters:
  7536. @table @option
  7537. @item video_size
  7538. Specify the size (width and height) of the buffered video frames. For the
  7539. syntax of this option, check the "Video size" section in the ffmpeg-utils
  7540. manual.
  7541. @item width
  7542. The input video width.
  7543. @item height
  7544. The input video height.
  7545. @item pix_fmt
  7546. A string representing the pixel format of the buffered video frames.
  7547. It may be a number corresponding to a pixel format, or a pixel format
  7548. name.
  7549. @item time_base
  7550. Specify the timebase assumed by the timestamps of the buffered frames.
  7551. @item frame_rate
  7552. Specify the frame rate expected for the video stream.
  7553. @item pixel_aspect, sar
  7554. The sample (pixel) aspect ratio of the input video.
  7555. @item sws_param
  7556. Specify the optional parameters to be used for the scale filter which
  7557. is automatically inserted when an input change is detected in the
  7558. input size or format.
  7559. @end table
  7560. For example:
  7561. @example
  7562. buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
  7563. @end example
  7564. will instruct the source to accept video frames with size 320x240 and
  7565. with format "yuv410p", assuming 1/24 as the timestamps timebase and
  7566. square pixels (1:1 sample aspect ratio).
  7567. Since the pixel format with name "yuv410p" corresponds to the number 6
  7568. (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
  7569. this example corresponds to:
  7570. @example
  7571. buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
  7572. @end example
  7573. Alternatively, the options can be specified as a flat string, but this
  7574. syntax is deprecated:
  7575. @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}]
  7576. @section cellauto
  7577. Create a pattern generated by an elementary cellular automaton.
  7578. The initial state of the cellular automaton can be defined through the
  7579. @option{filename}, and @option{pattern} options. If such options are
  7580. not specified an initial state is created randomly.
  7581. At each new frame a new row in the video is filled with the result of
  7582. the cellular automaton next generation. The behavior when the whole
  7583. frame is filled is defined by the @option{scroll} option.
  7584. This source accepts the following options:
  7585. @table @option
  7586. @item filename, f
  7587. Read the initial cellular automaton state, i.e. the starting row, from
  7588. the specified file.
  7589. In the file, each non-whitespace character is considered an alive
  7590. cell, a newline will terminate the row, and further characters in the
  7591. file will be ignored.
  7592. @item pattern, p
  7593. Read the initial cellular automaton state, i.e. the starting row, from
  7594. the specified string.
  7595. Each non-whitespace character in the string is considered an alive
  7596. cell, a newline will terminate the row, and further characters in the
  7597. string will be ignored.
  7598. @item rate, r
  7599. Set the video rate, that is the number of frames generated per second.
  7600. Default is 25.
  7601. @item random_fill_ratio, ratio
  7602. Set the random fill ratio for the initial cellular automaton row. It
  7603. is a floating point number value ranging from 0 to 1, defaults to
  7604. 1/PHI.
  7605. This option is ignored when a file or a pattern is specified.
  7606. @item random_seed, seed
  7607. Set the seed for filling randomly the initial row, must be an integer
  7608. included between 0 and UINT32_MAX. If not specified, or if explicitly
  7609. set to -1, the filter will try to use a good random seed on a best
  7610. effort basis.
  7611. @item rule
  7612. Set the cellular automaton rule, it is a number ranging from 0 to 255.
  7613. Default value is 110.
  7614. @item size, s
  7615. Set the size of the output video. For the syntax of this option, check
  7616. the "Video size" section in the ffmpeg-utils manual.
  7617. If @option{filename} or @option{pattern} is specified, the size is set
  7618. by default to the width of the specified initial state row, and the
  7619. height is set to @var{width} * PHI.
  7620. If @option{size} is set, it must contain the width of the specified
  7621. pattern string, and the specified pattern will be centered in the
  7622. larger row.
  7623. If a filename or a pattern string is not specified, the size value
  7624. defaults to "320x518" (used for a randomly generated initial state).
  7625. @item scroll
  7626. If set to 1, scroll the output upward when all the rows in the output
  7627. have been already filled. If set to 0, the new generated row will be
  7628. written over the top row just after the bottom row is filled.
  7629. Defaults to 1.
  7630. @item start_full, full
  7631. If set to 1, completely fill the output with generated rows before
  7632. outputting the first frame.
  7633. This is the default behavior, for disabling set the value to 0.
  7634. @item stitch
  7635. If set to 1, stitch the left and right row edges together.
  7636. This is the default behavior, for disabling set the value to 0.
  7637. @end table
  7638. @subsection Examples
  7639. @itemize
  7640. @item
  7641. Read the initial state from @file{pattern}, and specify an output of
  7642. size 200x400.
  7643. @example
  7644. cellauto=f=pattern:s=200x400
  7645. @end example
  7646. @item
  7647. Generate a random initial row with a width of 200 cells, with a fill
  7648. ratio of 2/3:
  7649. @example
  7650. cellauto=ratio=2/3:s=200x200
  7651. @end example
  7652. @item
  7653. Create a pattern generated by rule 18 starting by a single alive cell
  7654. centered on an initial row with width 100:
  7655. @example
  7656. cellauto=p=@@:s=100x400:full=0:rule=18
  7657. @end example
  7658. @item
  7659. Specify a more elaborated initial pattern:
  7660. @example
  7661. cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
  7662. @end example
  7663. @end itemize
  7664. @section mandelbrot
  7665. Generate a Mandelbrot set fractal, and progressively zoom towards the
  7666. point specified with @var{start_x} and @var{start_y}.
  7667. This source accepts the following options:
  7668. @table @option
  7669. @item end_pts
  7670. Set the terminal pts value. Default value is 400.
  7671. @item end_scale
  7672. Set the terminal scale value.
  7673. Must be a floating point value. Default value is 0.3.
  7674. @item inner
  7675. Set the inner coloring mode, that is the algorithm used to draw the
  7676. Mandelbrot fractal internal region.
  7677. It shall assume one of the following values:
  7678. @table @option
  7679. @item black
  7680. Set black mode.
  7681. @item convergence
  7682. Show time until convergence.
  7683. @item mincol
  7684. Set color based on point closest to the origin of the iterations.
  7685. @item period
  7686. Set period mode.
  7687. @end table
  7688. Default value is @var{mincol}.
  7689. @item bailout
  7690. Set the bailout value. Default value is 10.0.
  7691. @item maxiter
  7692. Set the maximum of iterations performed by the rendering
  7693. algorithm. Default value is 7189.
  7694. @item outer
  7695. Set outer coloring mode.
  7696. It shall assume one of following values:
  7697. @table @option
  7698. @item iteration_count
  7699. Set iteration cound mode.
  7700. @item normalized_iteration_count
  7701. set normalized iteration count mode.
  7702. @end table
  7703. Default value is @var{normalized_iteration_count}.
  7704. @item rate, r
  7705. Set frame rate, expressed as number of frames per second. Default
  7706. value is "25".
  7707. @item size, s
  7708. Set frame size. For the syntax of this option, check the "Video
  7709. size" section in the ffmpeg-utils manual. Default value is "640x480".
  7710. @item start_scale
  7711. Set the initial scale value. Default value is 3.0.
  7712. @item start_x
  7713. Set the initial x position. Must be a floating point value between
  7714. -100 and 100. Default value is -0.743643887037158704752191506114774.
  7715. @item start_y
  7716. Set the initial y position. Must be a floating point value between
  7717. -100 and 100. Default value is -0.131825904205311970493132056385139.
  7718. @end table
  7719. @section mptestsrc
  7720. Generate various test patterns, as generated by the MPlayer test filter.
  7721. The size of the generated video is fixed, and is 256x256.
  7722. This source is useful in particular for testing encoding features.
  7723. This source accepts the following options:
  7724. @table @option
  7725. @item rate, r
  7726. Specify the frame rate of the sourced video, as the number of frames
  7727. generated per second. It has to be a string in the format
  7728. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  7729. number or a valid video frame rate abbreviation. The default value is
  7730. "25".
  7731. @item duration, d
  7732. Set the duration of the sourced video. See
  7733. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  7734. for the accepted syntax.
  7735. If not specified, or the expressed duration is negative, the video is
  7736. supposed to be generated forever.
  7737. @item test, t
  7738. Set the number or the name of the test to perform. Supported tests are:
  7739. @table @option
  7740. @item dc_luma
  7741. @item dc_chroma
  7742. @item freq_luma
  7743. @item freq_chroma
  7744. @item amp_luma
  7745. @item amp_chroma
  7746. @item cbp
  7747. @item mv
  7748. @item ring1
  7749. @item ring2
  7750. @item all
  7751. @end table
  7752. Default value is "all", which will cycle through the list of all tests.
  7753. @end table
  7754. Some examples:
  7755. @example
  7756. mptestsrc=t=dc_luma
  7757. @end example
  7758. will generate a "dc_luma" test pattern.
  7759. @section frei0r_src
  7760. Provide a frei0r source.
  7761. To enable compilation of this filter you need to install the frei0r
  7762. header and configure FFmpeg with @code{--enable-frei0r}.
  7763. This source accepts the following parameters:
  7764. @table @option
  7765. @item size
  7766. The size of the video to generate. For the syntax of this option, check the
  7767. "Video size" section in the ffmpeg-utils manual.
  7768. @item framerate
  7769. The framerate of the generated video. It may be a string of the form
  7770. @var{num}/@var{den} or a frame rate abbreviation.
  7771. @item filter_name
  7772. The name to the frei0r source to load. For more information regarding frei0r and
  7773. how to set the parameters, read the @ref{frei0r} section in the video filters
  7774. documentation.
  7775. @item filter_params
  7776. A '|'-separated list of parameters to pass to the frei0r source.
  7777. @end table
  7778. For example, to generate a frei0r partik0l source with size 200x200
  7779. and frame rate 10 which is overlaid on the overlay filter main input:
  7780. @example
  7781. frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
  7782. @end example
  7783. @section life
  7784. Generate a life pattern.
  7785. This source is based on a generalization of John Conway's life game.
  7786. The sourced input represents a life grid, each pixel represents a cell
  7787. which can be in one of two possible states, alive or dead. Every cell
  7788. interacts with its eight neighbours, which are the cells that are
  7789. horizontally, vertically, or diagonally adjacent.
  7790. At each interaction the grid evolves according to the adopted rule,
  7791. which specifies the number of neighbor alive cells which will make a
  7792. cell stay alive or born. The @option{rule} option allows one to specify
  7793. the rule to adopt.
  7794. This source accepts the following options:
  7795. @table @option
  7796. @item filename, f
  7797. Set the file from which to read the initial grid state. In the file,
  7798. each non-whitespace character is considered an alive cell, and newline
  7799. is used to delimit the end of each row.
  7800. If this option is not specified, the initial grid is generated
  7801. randomly.
  7802. @item rate, r
  7803. Set the video rate, that is the number of frames generated per second.
  7804. Default is 25.
  7805. @item random_fill_ratio, ratio
  7806. Set the random fill ratio for the initial random grid. It is a
  7807. floating point number value ranging from 0 to 1, defaults to 1/PHI.
  7808. It is ignored when a file is specified.
  7809. @item random_seed, seed
  7810. Set the seed for filling the initial random grid, must be an integer
  7811. included between 0 and UINT32_MAX. If not specified, or if explicitly
  7812. set to -1, the filter will try to use a good random seed on a best
  7813. effort basis.
  7814. @item rule
  7815. Set the life rule.
  7816. A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
  7817. where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
  7818. @var{NS} specifies the number of alive neighbor cells which make a
  7819. live cell stay alive, and @var{NB} the number of alive neighbor cells
  7820. which make a dead cell to become alive (i.e. to "born").
  7821. "s" and "b" can be used in place of "S" and "B", respectively.
  7822. Alternatively a rule can be specified by an 18-bits integer. The 9
  7823. high order bits are used to encode the next cell state if it is alive
  7824. for each number of neighbor alive cells, the low order bits specify
  7825. the rule for "borning" new cells. Higher order bits encode for an
  7826. higher number of neighbor cells.
  7827. For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
  7828. rule of 12 and a born rule of 9, which corresponds to "S23/B03".
  7829. Default value is "S23/B3", which is the original Conway's game of life
  7830. rule, and will keep a cell alive if it has 2 or 3 neighbor alive
  7831. cells, and will born a new cell if there are three alive cells around
  7832. a dead cell.
  7833. @item size, s
  7834. Set the size of the output video. For the syntax of this option, check the
  7835. "Video size" section in the ffmpeg-utils manual.
  7836. If @option{filename} is specified, the size is set by default to the
  7837. same size of the input file. If @option{size} is set, it must contain
  7838. the size specified in the input file, and the initial grid defined in
  7839. that file is centered in the larger resulting area.
  7840. If a filename is not specified, the size value defaults to "320x240"
  7841. (used for a randomly generated initial grid).
  7842. @item stitch
  7843. If set to 1, stitch the left and right grid edges together, and the
  7844. top and bottom edges also. Defaults to 1.
  7845. @item mold
  7846. Set cell mold speed. If set, a dead cell will go from @option{death_color} to
  7847. @option{mold_color} with a step of @option{mold}. @option{mold} can have a
  7848. value from 0 to 255.
  7849. @item life_color
  7850. Set the color of living (or new born) cells.
  7851. @item death_color
  7852. Set the color of dead cells. If @option{mold} is set, this is the first color
  7853. used to represent a dead cell.
  7854. @item mold_color
  7855. Set mold color, for definitely dead and moldy cells.
  7856. For the syntax of these 3 color options, check the "Color" section in the
  7857. ffmpeg-utils manual.
  7858. @end table
  7859. @subsection Examples
  7860. @itemize
  7861. @item
  7862. Read a grid from @file{pattern}, and center it on a grid of size
  7863. 300x300 pixels:
  7864. @example
  7865. life=f=pattern:s=300x300
  7866. @end example
  7867. @item
  7868. Generate a random grid of size 200x200, with a fill ratio of 2/3:
  7869. @example
  7870. life=ratio=2/3:s=200x200
  7871. @end example
  7872. @item
  7873. Specify a custom rule for evolving a randomly generated grid:
  7874. @example
  7875. life=rule=S14/B34
  7876. @end example
  7877. @item
  7878. Full example with slow death effect (mold) using @command{ffplay}:
  7879. @example
  7880. ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
  7881. @end example
  7882. @end itemize
  7883. @anchor{color}
  7884. @anchor{haldclutsrc}
  7885. @anchor{nullsrc}
  7886. @anchor{rgbtestsrc}
  7887. @anchor{smptebars}
  7888. @anchor{smptehdbars}
  7889. @anchor{testsrc}
  7890. @section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc
  7891. The @code{color} source provides an uniformly colored input.
  7892. The @code{haldclutsrc} source provides an identity Hald CLUT. See also
  7893. @ref{haldclut} filter.
  7894. The @code{nullsrc} source returns unprocessed video frames. It is
  7895. mainly useful to be employed in analysis / debugging tools, or as the
  7896. source for filters which ignore the input data.
  7897. The @code{rgbtestsrc} source generates an RGB test pattern useful for
  7898. detecting RGB vs BGR issues. You should see a red, green and blue
  7899. stripe from top to bottom.
  7900. The @code{smptebars} source generates a color bars pattern, based on
  7901. the SMPTE Engineering Guideline EG 1-1990.
  7902. The @code{smptehdbars} source generates a color bars pattern, based on
  7903. the SMPTE RP 219-2002.
  7904. The @code{testsrc} source generates a test video pattern, showing a
  7905. color pattern, a scrolling gradient and a timestamp. This is mainly
  7906. intended for testing purposes.
  7907. The sources accept the following parameters:
  7908. @table @option
  7909. @item color, c
  7910. Specify the color of the source, only available in the @code{color}
  7911. source. For the syntax of this option, check the "Color" section in the
  7912. ffmpeg-utils manual.
  7913. @item level
  7914. Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
  7915. source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
  7916. pixels to be used as identity matrix for 3D lookup tables. Each component is
  7917. coded on a @code{1/(N*N)} scale.
  7918. @item size, s
  7919. Specify the size of the sourced video. For the syntax of this option, check the
  7920. "Video size" section in the ffmpeg-utils manual. The default value is
  7921. "320x240".
  7922. This option is not available with the @code{haldclutsrc} filter.
  7923. @item rate, r
  7924. Specify the frame rate of the sourced video, as the number of frames
  7925. generated per second. It has to be a string in the format
  7926. @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
  7927. number or a valid video frame rate abbreviation. The default value is
  7928. "25".
  7929. @item sar
  7930. Set the sample aspect ratio of the sourced video.
  7931. @item duration, d
  7932. Set the duration of the sourced video. See
  7933. @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
  7934. for the accepted syntax.
  7935. If not specified, or the expressed duration is negative, the video is
  7936. supposed to be generated forever.
  7937. @item decimals, n
  7938. Set the number of decimals to show in the timestamp, only available in the
  7939. @code{testsrc} source.
  7940. The displayed timestamp value will correspond to the original
  7941. timestamp value multiplied by the power of 10 of the specified
  7942. value. Default value is 0.
  7943. @end table
  7944. For example the following:
  7945. @example
  7946. testsrc=duration=5.3:size=qcif:rate=10
  7947. @end example
  7948. will generate a video with a duration of 5.3 seconds, with size
  7949. 176x144 and a frame rate of 10 frames per second.
  7950. The following graph description will generate a red source
  7951. with an opacity of 0.2, with size "qcif" and a frame rate of 10
  7952. frames per second.
  7953. @example
  7954. color=c=red@@0.2:s=qcif:r=10
  7955. @end example
  7956. If the input content is to be ignored, @code{nullsrc} can be used. The
  7957. following command generates noise in the luminance plane by employing
  7958. the @code{geq} filter:
  7959. @example
  7960. nullsrc=s=256x256, geq=random(1)*255:128:128
  7961. @end example
  7962. @subsection Commands
  7963. The @code{color} source supports the following commands:
  7964. @table @option
  7965. @item c, color
  7966. Set the color of the created image. Accepts the same syntax of the
  7967. corresponding @option{color} option.
  7968. @end table
  7969. @c man end VIDEO SOURCES
  7970. @chapter Video Sinks
  7971. @c man begin VIDEO SINKS
  7972. Below is a description of the currently available video sinks.
  7973. @section buffersink
  7974. Buffer video frames, and make them available to the end of the filter
  7975. graph.
  7976. This sink is mainly intended for programmatic use, in particular
  7977. through the interface defined in @file{libavfilter/buffersink.h}
  7978. or the options system.
  7979. It accepts a pointer to an AVBufferSinkContext structure, which
  7980. defines the incoming buffers' formats, to be passed as the opaque
  7981. parameter to @code{avfilter_init_filter} for initialization.
  7982. @section nullsink
  7983. Null video sink: do absolutely nothing with the input video. It is
  7984. mainly useful as a template and for use in analysis / debugging
  7985. tools.
  7986. @c man end VIDEO SINKS
  7987. @chapter Multimedia Filters
  7988. @c man begin MULTIMEDIA FILTERS
  7989. Below is a description of the currently available multimedia filters.
  7990. @section avectorscope
  7991. Convert input audio to a video output, representing the audio vector
  7992. scope.
  7993. The filter is used to measure the difference between channels of stereo
  7994. audio stream. A monoaural signal, consisting of identical left and right
  7995. signal, results in straight vertical line. Any stereo separation is visible
  7996. as a deviation from this line, creating a Lissajous figure.
  7997. If the straight (or deviation from it) but horizontal line appears this
  7998. indicates that the left and right channels are out of phase.
  7999. The filter accepts the following options:
  8000. @table @option
  8001. @item mode, m
  8002. Set the vectorscope mode.
  8003. Available values are:
  8004. @table @samp
  8005. @item lissajous
  8006. Lissajous rotated by 45 degrees.
  8007. @item lissajous_xy
  8008. Same as above but not rotated.
  8009. @end table
  8010. Default value is @samp{lissajous}.
  8011. @item size, s
  8012. Set the video size for the output. For the syntax of this option, check the "Video size"
  8013. section in the ffmpeg-utils manual. Default value is @code{400x400}.
  8014. @item rate, r
  8015. Set the output frame rate. Default value is @code{25}.
  8016. @item rc
  8017. @item gc
  8018. @item bc
  8019. Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}.
  8020. Allowed range is @code{[0, 255]}.
  8021. @item rf
  8022. @item gf
  8023. @item bf
  8024. Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}.
  8025. Allowed range is @code{[0, 255]}.
  8026. @item zoom
  8027. Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}.
  8028. @end table
  8029. @subsection Examples
  8030. @itemize
  8031. @item
  8032. Complete example using @command{ffplay}:
  8033. @example
  8034. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  8035. [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
  8036. @end example
  8037. @end itemize
  8038. @section concat
  8039. Concatenate audio and video streams, joining them together one after the
  8040. other.
  8041. The filter works on segments of synchronized video and audio streams. All
  8042. segments must have the same number of streams of each type, and that will
  8043. also be the number of streams at output.
  8044. The filter accepts the following options:
  8045. @table @option
  8046. @item n
  8047. Set the number of segments. Default is 2.
  8048. @item v
  8049. Set the number of output video streams, that is also the number of video
  8050. streams in each segment. Default is 1.
  8051. @item a
  8052. Set the number of output audio streams, that is also the number of audio
  8053. streams in each segment. Default is 0.
  8054. @item unsafe
  8055. Activate unsafe mode: do not fail if segments have a different format.
  8056. @end table
  8057. The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
  8058. @var{a} audio outputs.
  8059. There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
  8060. segment, in the same order as the outputs, then the inputs for the second
  8061. segment, etc.
  8062. Related streams do not always have exactly the same duration, for various
  8063. reasons including codec frame size or sloppy authoring. For that reason,
  8064. related synchronized streams (e.g. a video and its audio track) should be
  8065. concatenated at once. The concat filter will use the duration of the longest
  8066. stream in each segment (except the last one), and if necessary pad shorter
  8067. audio streams with silence.
  8068. For this filter to work correctly, all segments must start at timestamp 0.
  8069. All corresponding streams must have the same parameters in all segments; the
  8070. filtering system will automatically select a common pixel format for video
  8071. streams, and a common sample format, sample rate and channel layout for
  8072. audio streams, but other settings, such as resolution, must be converted
  8073. explicitly by the user.
  8074. Different frame rates are acceptable but will result in variable frame rate
  8075. at output; be sure to configure the output file to handle it.
  8076. @subsection Examples
  8077. @itemize
  8078. @item
  8079. Concatenate an opening, an episode and an ending, all in bilingual version
  8080. (video in stream 0, audio in streams 1 and 2):
  8081. @example
  8082. ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
  8083. '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
  8084. concat=n=3:v=1:a=2 [v] [a1] [a2]' \
  8085. -map '[v]' -map '[a1]' -map '[a2]' output.mkv
  8086. @end example
  8087. @item
  8088. Concatenate two parts, handling audio and video separately, using the
  8089. (a)movie sources, and adjusting the resolution:
  8090. @example
  8091. movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
  8092. movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
  8093. [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
  8094. @end example
  8095. Note that a desync will happen at the stitch if the audio and video streams
  8096. do not have exactly the same duration in the first file.
  8097. @end itemize
  8098. @section ebur128
  8099. EBU R128 scanner filter. This filter takes an audio stream as input and outputs
  8100. it unchanged. By default, it logs a message at a frequency of 10Hz with the
  8101. Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
  8102. Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
  8103. The filter also has a video output (see the @var{video} option) with a real
  8104. time graph to observe the loudness evolution. The graphic contains the logged
  8105. message mentioned above, so it is not printed anymore when this option is set,
  8106. unless the verbose logging is set. The main graphing area contains the
  8107. short-term loudness (3 seconds of analysis), and the gauge on the right is for
  8108. the momentary loudness (400 milliseconds).
  8109. More information about the Loudness Recommendation EBU R128 on
  8110. @url{http://tech.ebu.ch/loudness}.
  8111. The filter accepts the following options:
  8112. @table @option
  8113. @item video
  8114. Activate the video output. The audio stream is passed unchanged whether this
  8115. option is set or no. The video stream will be the first output stream if
  8116. activated. Default is @code{0}.
  8117. @item size
  8118. Set the video size. This option is for video only. For the syntax of this
  8119. option, check the "Video size" section in the ffmpeg-utils manual. Default
  8120. and minimum resolution is @code{640x480}.
  8121. @item meter
  8122. Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
  8123. @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
  8124. other integer value between this range is allowed.
  8125. @item metadata
  8126. Set metadata injection. If set to @code{1}, the audio input will be segmented
  8127. into 100ms output frames, each of them containing various loudness information
  8128. in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
  8129. Default is @code{0}.
  8130. @item framelog
  8131. Force the frame logging level.
  8132. Available values are:
  8133. @table @samp
  8134. @item info
  8135. information logging level
  8136. @item verbose
  8137. verbose logging level
  8138. @end table
  8139. By default, the logging level is set to @var{info}. If the @option{video} or
  8140. the @option{metadata} options are set, it switches to @var{verbose}.
  8141. @item peak
  8142. Set peak mode(s).
  8143. Available modes can be cumulated (the option is a @code{flag} type). Possible
  8144. values are:
  8145. @table @samp
  8146. @item none
  8147. Disable any peak mode (default).
  8148. @item sample
  8149. Enable sample-peak mode.
  8150. Simple peak mode looking for the higher sample value. It logs a message
  8151. for sample-peak (identified by @code{SPK}).
  8152. @item true
  8153. Enable true-peak mode.
  8154. If enabled, the peak lookup is done on an over-sampled version of the input
  8155. stream for better peak accuracy. It logs a message for true-peak.
  8156. (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
  8157. This mode requires a build with @code{libswresample}.
  8158. @end table
  8159. @end table
  8160. @subsection Examples
  8161. @itemize
  8162. @item
  8163. Real-time graph using @command{ffplay}, with a EBU scale meter +18:
  8164. @example
  8165. ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
  8166. @end example
  8167. @item
  8168. Run an analysis with @command{ffmpeg}:
  8169. @example
  8170. ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
  8171. @end example
  8172. @end itemize
  8173. @section interleave, ainterleave
  8174. Temporally interleave frames from several inputs.
  8175. @code{interleave} works with video inputs, @code{ainterleave} with audio.
  8176. These filters read frames from several inputs and send the oldest
  8177. queued frame to the output.
  8178. Input streams must have a well defined, monotonically increasing frame
  8179. timestamp values.
  8180. In order to submit one frame to output, these filters need to enqueue
  8181. at least one frame for each input, so they cannot work in case one
  8182. input is not yet terminated and will not receive incoming frames.
  8183. For example consider the case when one input is a @code{select} filter
  8184. which always drop input frames. The @code{interleave} filter will keep
  8185. reading from that input, but it will never be able to send new frames
  8186. to output until the input will send an end-of-stream signal.
  8187. Also, depending on inputs synchronization, the filters will drop
  8188. frames in case one input receives more frames than the other ones, and
  8189. the queue is already filled.
  8190. These filters accept the following options:
  8191. @table @option
  8192. @item nb_inputs, n
  8193. Set the number of different inputs, it is 2 by default.
  8194. @end table
  8195. @subsection Examples
  8196. @itemize
  8197. @item
  8198. Interleave frames belonging to different streams using @command{ffmpeg}:
  8199. @example
  8200. ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
  8201. @end example
  8202. @item
  8203. Add flickering blur effect:
  8204. @example
  8205. select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
  8206. @end example
  8207. @end itemize
  8208. @section perms, aperms
  8209. Set read/write permissions for the output frames.
  8210. These filters are mainly aimed at developers to test direct path in the
  8211. following filter in the filtergraph.
  8212. The filters accept the following options:
  8213. @table @option
  8214. @item mode
  8215. Select the permissions mode.
  8216. It accepts the following values:
  8217. @table @samp
  8218. @item none
  8219. Do nothing. This is the default.
  8220. @item ro
  8221. Set all the output frames read-only.
  8222. @item rw
  8223. Set all the output frames directly writable.
  8224. @item toggle
  8225. Make the frame read-only if writable, and writable if read-only.
  8226. @item random
  8227. Set each output frame read-only or writable randomly.
  8228. @end table
  8229. @item seed
  8230. Set the seed for the @var{random} mode, must be an integer included between
  8231. @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
  8232. @code{-1}, the filter will try to use a good random seed on a best effort
  8233. basis.
  8234. @end table
  8235. Note: in case of auto-inserted filter between the permission filter and the
  8236. following one, the permission might not be received as expected in that
  8237. following filter. Inserting a @ref{format} or @ref{aformat} filter before the
  8238. perms/aperms filter can avoid this problem.
  8239. @section select, aselect
  8240. Select frames to pass in output.
  8241. This filter accepts the following options:
  8242. @table @option
  8243. @item expr, e
  8244. Set expression, which is evaluated for each input frame.
  8245. If the expression is evaluated to zero, the frame is discarded.
  8246. If the evaluation result is negative or NaN, the frame is sent to the
  8247. first output; otherwise it is sent to the output with index
  8248. @code{ceil(val)-1}, assuming that the input index starts from 0.
  8249. For example a value of @code{1.2} corresponds to the output with index
  8250. @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
  8251. @item outputs, n
  8252. Set the number of outputs. The output to which to send the selected
  8253. frame is based on the result of the evaluation. Default value is 1.
  8254. @end table
  8255. The expression can contain the following constants:
  8256. @table @option
  8257. @item n
  8258. The (sequential) number of the filtered frame, starting from 0.
  8259. @item selected_n
  8260. The (sequential) number of the selected frame, starting from 0.
  8261. @item prev_selected_n
  8262. The sequential number of the last selected frame. It's NAN if undefined.
  8263. @item TB
  8264. The timebase of the input timestamps.
  8265. @item pts
  8266. The PTS (Presentation TimeStamp) of the filtered video frame,
  8267. expressed in @var{TB} units. It's NAN if undefined.
  8268. @item t
  8269. The PTS of the filtered video frame,
  8270. expressed in seconds. It's NAN if undefined.
  8271. @item prev_pts
  8272. The PTS of the previously filtered video frame. It's NAN if undefined.
  8273. @item prev_selected_pts
  8274. The PTS of the last previously filtered video frame. It's NAN if undefined.
  8275. @item prev_selected_t
  8276. The PTS of the last previously selected video frame. It's NAN if undefined.
  8277. @item start_pts
  8278. The PTS of the first video frame in the video. It's NAN if undefined.
  8279. @item start_t
  8280. The time of the first video frame in the video. It's NAN if undefined.
  8281. @item pict_type @emph{(video only)}
  8282. The type of the filtered frame. It can assume one of the following
  8283. values:
  8284. @table @option
  8285. @item I
  8286. @item P
  8287. @item B
  8288. @item S
  8289. @item SI
  8290. @item SP
  8291. @item BI
  8292. @end table
  8293. @item interlace_type @emph{(video only)}
  8294. The frame interlace type. It can assume one of the following values:
  8295. @table @option
  8296. @item PROGRESSIVE
  8297. The frame is progressive (not interlaced).
  8298. @item TOPFIRST
  8299. The frame is top-field-first.
  8300. @item BOTTOMFIRST
  8301. The frame is bottom-field-first.
  8302. @end table
  8303. @item consumed_sample_n @emph{(audio only)}
  8304. the number of selected samples before the current frame
  8305. @item samples_n @emph{(audio only)}
  8306. the number of samples in the current frame
  8307. @item sample_rate @emph{(audio only)}
  8308. the input sample rate
  8309. @item key
  8310. This is 1 if the filtered frame is a key-frame, 0 otherwise.
  8311. @item pos
  8312. the position in the file of the filtered frame, -1 if the information
  8313. is not available (e.g. for synthetic video)
  8314. @item scene @emph{(video only)}
  8315. value between 0 and 1 to indicate a new scene; a low value reflects a low
  8316. probability for the current frame to introduce a new scene, while a higher
  8317. value means the current frame is more likely to be one (see the example below)
  8318. @end table
  8319. The default value of the select expression is "1".
  8320. @subsection Examples
  8321. @itemize
  8322. @item
  8323. Select all frames in input:
  8324. @example
  8325. select
  8326. @end example
  8327. The example above is the same as:
  8328. @example
  8329. select=1
  8330. @end example
  8331. @item
  8332. Skip all frames:
  8333. @example
  8334. select=0
  8335. @end example
  8336. @item
  8337. Select only I-frames:
  8338. @example
  8339. select='eq(pict_type\,I)'
  8340. @end example
  8341. @item
  8342. Select one frame every 100:
  8343. @example
  8344. select='not(mod(n\,100))'
  8345. @end example
  8346. @item
  8347. Select only frames contained in the 10-20 time interval:
  8348. @example
  8349. select=between(t\,10\,20)
  8350. @end example
  8351. @item
  8352. Select only I frames contained in the 10-20 time interval:
  8353. @example
  8354. select=between(t\,10\,20)*eq(pict_type\,I)
  8355. @end example
  8356. @item
  8357. Select frames with a minimum distance of 10 seconds:
  8358. @example
  8359. select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
  8360. @end example
  8361. @item
  8362. Use aselect to select only audio frames with samples number > 100:
  8363. @example
  8364. aselect='gt(samples_n\,100)'
  8365. @end example
  8366. @item
  8367. Create a mosaic of the first scenes:
  8368. @example
  8369. ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
  8370. @end example
  8371. Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
  8372. choice.
  8373. @item
  8374. Send even and odd frames to separate outputs, and compose them:
  8375. @example
  8376. select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
  8377. @end example
  8378. @end itemize
  8379. @section sendcmd, asendcmd
  8380. Send commands to filters in the filtergraph.
  8381. These filters read commands to be sent to other filters in the
  8382. filtergraph.
  8383. @code{sendcmd} must be inserted between two video filters,
  8384. @code{asendcmd} must be inserted between two audio filters, but apart
  8385. from that they act the same way.
  8386. The specification of commands can be provided in the filter arguments
  8387. with the @var{commands} option, or in a file specified by the
  8388. @var{filename} option.
  8389. These filters accept the following options:
  8390. @table @option
  8391. @item commands, c
  8392. Set the commands to be read and sent to the other filters.
  8393. @item filename, f
  8394. Set the filename of the commands to be read and sent to the other
  8395. filters.
  8396. @end table
  8397. @subsection Commands syntax
  8398. A commands description consists of a sequence of interval
  8399. specifications, comprising a list of commands to be executed when a
  8400. particular event related to that interval occurs. The occurring event
  8401. is typically the current frame time entering or leaving a given time
  8402. interval.
  8403. An interval is specified by the following syntax:
  8404. @example
  8405. @var{START}[-@var{END}] @var{COMMANDS};
  8406. @end example
  8407. The time interval is specified by the @var{START} and @var{END} times.
  8408. @var{END} is optional and defaults to the maximum time.
  8409. The current frame time is considered within the specified interval if
  8410. it is included in the interval [@var{START}, @var{END}), that is when
  8411. the time is greater or equal to @var{START} and is lesser than
  8412. @var{END}.
  8413. @var{COMMANDS} consists of a sequence of one or more command
  8414. specifications, separated by ",", relating to that interval. The
  8415. syntax of a command specification is given by:
  8416. @example
  8417. [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
  8418. @end example
  8419. @var{FLAGS} is optional and specifies the type of events relating to
  8420. the time interval which enable sending the specified command, and must
  8421. be a non-null sequence of identifier flags separated by "+" or "|" and
  8422. enclosed between "[" and "]".
  8423. The following flags are recognized:
  8424. @table @option
  8425. @item enter
  8426. The command is sent when the current frame timestamp enters the
  8427. specified interval. In other words, the command is sent when the
  8428. previous frame timestamp was not in the given interval, and the
  8429. current is.
  8430. @item leave
  8431. The command is sent when the current frame timestamp leaves the
  8432. specified interval. In other words, the command is sent when the
  8433. previous frame timestamp was in the given interval, and the
  8434. current is not.
  8435. @end table
  8436. If @var{FLAGS} is not specified, a default value of @code{[enter]} is
  8437. assumed.
  8438. @var{TARGET} specifies the target of the command, usually the name of
  8439. the filter class or a specific filter instance name.
  8440. @var{COMMAND} specifies the name of the command for the target filter.
  8441. @var{ARG} is optional and specifies the optional list of argument for
  8442. the given @var{COMMAND}.
  8443. Between one interval specification and another, whitespaces, or
  8444. sequences of characters starting with @code{#} until the end of line,
  8445. are ignored and can be used to annotate comments.
  8446. A simplified BNF description of the commands specification syntax
  8447. follows:
  8448. @example
  8449. @var{COMMAND_FLAG} ::= "enter" | "leave"
  8450. @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
  8451. @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
  8452. @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
  8453. @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
  8454. @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
  8455. @end example
  8456. @subsection Examples
  8457. @itemize
  8458. @item
  8459. Specify audio tempo change at second 4:
  8460. @example
  8461. asendcmd=c='4.0 atempo tempo 1.5',atempo
  8462. @end example
  8463. @item
  8464. Specify a list of drawtext and hue commands in a file.
  8465. @example
  8466. # show text in the interval 5-10
  8467. 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
  8468. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
  8469. # desaturate the image in the interval 15-20
  8470. 15.0-20.0 [enter] hue s 0,
  8471. [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
  8472. [leave] hue s 1,
  8473. [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
  8474. # apply an exponential saturation fade-out effect, starting from time 25
  8475. 25 [enter] hue s exp(25-t)
  8476. @end example
  8477. A filtergraph allowing to read and process the above command list
  8478. stored in a file @file{test.cmd}, can be specified with:
  8479. @example
  8480. sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
  8481. @end example
  8482. @end itemize
  8483. @anchor{setpts}
  8484. @section setpts, asetpts
  8485. Change the PTS (presentation timestamp) of the input frames.
  8486. @code{setpts} works on video frames, @code{asetpts} on audio frames.
  8487. This filter accepts the following options:
  8488. @table @option
  8489. @item expr
  8490. The expression which is evaluated for each frame to construct its timestamp.
  8491. @end table
  8492. The expression is evaluated through the eval API and can contain the following
  8493. constants:
  8494. @table @option
  8495. @item FRAME_RATE
  8496. frame rate, only defined for constant frame-rate video
  8497. @item PTS
  8498. The presentation timestamp in input
  8499. @item N
  8500. The count of the input frame for video or the number of consumed samples,
  8501. not including the current frame for audio, starting from 0.
  8502. @item NB_CONSUMED_SAMPLES
  8503. The number of consumed samples, not including the current frame (only
  8504. audio)
  8505. @item NB_SAMPLES, S
  8506. The number of samples in the current frame (only audio)
  8507. @item SAMPLE_RATE, SR
  8508. The audio sample rate.
  8509. @item STARTPTS
  8510. The PTS of the first frame.
  8511. @item STARTT
  8512. the time in seconds of the first frame
  8513. @item INTERLACED
  8514. State whether the current frame is interlaced.
  8515. @item T
  8516. the time in seconds of the current frame
  8517. @item POS
  8518. original position in the file of the frame, or undefined if undefined
  8519. for the current frame
  8520. @item PREV_INPTS
  8521. The previous input PTS.
  8522. @item PREV_INT
  8523. previous input time in seconds
  8524. @item PREV_OUTPTS
  8525. The previous output PTS.
  8526. @item PREV_OUTT
  8527. previous output time in seconds
  8528. @item RTCTIME
  8529. The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
  8530. instead.
  8531. @item RTCSTART
  8532. The wallclock (RTC) time at the start of the movie in microseconds.
  8533. @item TB
  8534. The timebase of the input timestamps.
  8535. @end table
  8536. @subsection Examples
  8537. @itemize
  8538. @item
  8539. Start counting PTS from zero
  8540. @example
  8541. setpts=PTS-STARTPTS
  8542. @end example
  8543. @item
  8544. Apply fast motion effect:
  8545. @example
  8546. setpts=0.5*PTS
  8547. @end example
  8548. @item
  8549. Apply slow motion effect:
  8550. @example
  8551. setpts=2.0*PTS
  8552. @end example
  8553. @item
  8554. Set fixed rate of 25 frames per second:
  8555. @example
  8556. setpts=N/(25*TB)
  8557. @end example
  8558. @item
  8559. Set fixed rate 25 fps with some jitter:
  8560. @example
  8561. setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
  8562. @end example
  8563. @item
  8564. Apply an offset of 10 seconds to the input PTS:
  8565. @example
  8566. setpts=PTS+10/TB
  8567. @end example
  8568. @item
  8569. Generate timestamps from a "live source" and rebase onto the current timebase:
  8570. @example
  8571. setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
  8572. @end example
  8573. @item
  8574. Generate timestamps by counting samples:
  8575. @example
  8576. asetpts=N/SR/TB
  8577. @end example
  8578. @end itemize
  8579. @section settb, asettb
  8580. Set the timebase to use for the output frames timestamps.
  8581. It is mainly useful for testing timebase configuration.
  8582. It accepts the following parameters:
  8583. @table @option
  8584. @item expr, tb
  8585. The expression which is evaluated into the output timebase.
  8586. @end table
  8587. The value for @option{tb} is an arithmetic expression representing a
  8588. rational. The expression can contain the constants "AVTB" (the default
  8589. timebase), "intb" (the input timebase) and "sr" (the sample rate,
  8590. audio only). Default value is "intb".
  8591. @subsection Examples
  8592. @itemize
  8593. @item
  8594. Set the timebase to 1/25:
  8595. @example
  8596. settb=expr=1/25
  8597. @end example
  8598. @item
  8599. Set the timebase to 1/10:
  8600. @example
  8601. settb=expr=0.1
  8602. @end example
  8603. @item
  8604. Set the timebase to 1001/1000:
  8605. @example
  8606. settb=1+0.001
  8607. @end example
  8608. @item
  8609. Set the timebase to 2*intb:
  8610. @example
  8611. settb=2*intb
  8612. @end example
  8613. @item
  8614. Set the default timebase value:
  8615. @example
  8616. settb=AVTB
  8617. @end example
  8618. @end itemize
  8619. @section showcqt
  8620. Convert input audio to a video output representing
  8621. frequency spectrum logarithmically (using constant Q transform with
  8622. Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves).
  8623. The filter accepts the following options:
  8624. @table @option
  8625. @item volume
  8626. Specify transform volume (multiplier) expression. The expression can contain
  8627. variables:
  8628. @table @option
  8629. @item frequency, freq, f
  8630. the frequency where transform is evaluated
  8631. @item timeclamp, tc
  8632. value of timeclamp option
  8633. @end table
  8634. and functions:
  8635. @table @option
  8636. @item a_weighting(f)
  8637. A-weighting of equal loudness
  8638. @item b_weighting(f)
  8639. B-weighting of equal loudness
  8640. @item c_weighting(f)
  8641. C-weighting of equal loudness
  8642. @end table
  8643. Default value is @code{16}.
  8644. @item tlength
  8645. Specify transform length expression. The expression can contain variables:
  8646. @table @option
  8647. @item frequency, freq, f
  8648. the frequency where transform is evaluated
  8649. @item timeclamp, tc
  8650. value of timeclamp option
  8651. @end table
  8652. Default value is @code{384/f*tc/(384/f+tc)}.
  8653. @item timeclamp
  8654. Specify the transform timeclamp. At low frequency, there is trade-off between
  8655. accuracy in time domain and frequency domain. If timeclamp is lower,
  8656. event in time domain is represented more accurately (such as fast bass drum),
  8657. otherwise event in frequency domain is represented more accurately
  8658. (such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}.
  8659. @item coeffclamp
  8660. Specify the transform coeffclamp. If coeffclamp is lower, transform is
  8661. more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0].
  8662. Default value is @code{1.0}.
  8663. @item gamma
  8664. Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma
  8665. makes the spectrum having more range. Acceptable value is [1.0, 7.0].
  8666. Default value is @code{3.0}.
  8667. @item gamma2
  8668. Specify gamma of bargraph. Acceptable value is [1.0, 7.0].
  8669. Default value is @code{1.0}.
  8670. @item fontfile
  8671. Specify font file for use with freetype. If not specified, use embedded font.
  8672. @item fontcolor
  8673. Specify font color expression. This is arithmetic expression that should return
  8674. integer value 0xRRGGBB. The expression can contain variables:
  8675. @table @option
  8676. @item frequency, freq, f
  8677. the frequency where transform is evaluated
  8678. @item timeclamp, tc
  8679. value of timeclamp option
  8680. @end table
  8681. and functions:
  8682. @table @option
  8683. @item midi(f)
  8684. midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
  8685. @item r(x), g(x), b(x)
  8686. red, green, and blue value of intensity x
  8687. @end table
  8688. Default value is @code{st(0, (midi(f)-59.5)/12);
  8689. st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
  8690. r(1-ld(1)) + b(ld(1))}
  8691. @item fullhd
  8692. If set to 1 (the default), the video size is 1920x1080 (full HD),
  8693. if set to 0, the video size is 960x540. Use this option to make CPU usage lower.
  8694. @item fps
  8695. Specify video fps. Default value is @code{25}.
  8696. @item count
  8697. Specify number of transform per frame, so there are fps*count transforms
  8698. per second. Note that audio data rate must be divisible by fps*count.
  8699. Default value is @code{6}.
  8700. @end table
  8701. @subsection Examples
  8702. @itemize
  8703. @item
  8704. Playing audio while showing the spectrum:
  8705. @example
  8706. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
  8707. @end example
  8708. @item
  8709. Same as above, but with frame rate 30 fps:
  8710. @example
  8711. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
  8712. @end example
  8713. @item
  8714. Playing at 960x540 and lower CPU usage:
  8715. @example
  8716. ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]'
  8717. @end example
  8718. @item
  8719. A1 and its harmonics: A1, A2, (near)E3, A3:
  8720. @example
  8721. 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),
  8722. asplit[a][out1]; [a] showcqt [out0]'
  8723. @end example
  8724. @item
  8725. Same as above, but with more accuracy in frequency domain (and slower):
  8726. @example
  8727. 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),
  8728. asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
  8729. @end example
  8730. @item
  8731. B-weighting of equal loudness
  8732. @example
  8733. volume=16*b_weighting(f)
  8734. @end example
  8735. @item
  8736. Lower Q factor
  8737. @example
  8738. tlength=100/f*tc/(100/f+tc)
  8739. @end example
  8740. @item
  8741. Custom fontcolor, C-note is colored green, others are colored blue
  8742. @example
  8743. fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))'
  8744. @end example
  8745. @item
  8746. Custom gamma, now spectrum is linear to the amplitude.
  8747. @example
  8748. gamma=2:gamma2=2
  8749. @end example
  8750. @end itemize
  8751. @section showspectrum
  8752. Convert input audio to a video output, representing the audio frequency
  8753. spectrum.
  8754. The filter accepts the following options:
  8755. @table @option
  8756. @item size, s
  8757. Specify the video size for the output. For the syntax of this option, check
  8758. the "Video size" section in the ffmpeg-utils manual. Default value is
  8759. @code{640x512}.
  8760. @item slide
  8761. Specify how the spectrum should slide along the window.
  8762. It accepts the following values:
  8763. @table @samp
  8764. @item replace
  8765. the samples start again on the left when they reach the right
  8766. @item scroll
  8767. the samples scroll from right to left
  8768. @item fullframe
  8769. frames are only produced when the samples reach the right
  8770. @end table
  8771. Default value is @code{replace}.
  8772. @item mode
  8773. Specify display mode.
  8774. It accepts the following values:
  8775. @table @samp
  8776. @item combined
  8777. all channels are displayed in the same row
  8778. @item separate
  8779. all channels are displayed in separate rows
  8780. @end table
  8781. Default value is @samp{combined}.
  8782. @item color
  8783. Specify display color mode.
  8784. It accepts the following values:
  8785. @table @samp
  8786. @item channel
  8787. each channel is displayed in a separate color
  8788. @item intensity
  8789. each channel is is displayed using the same color scheme
  8790. @end table
  8791. Default value is @samp{channel}.
  8792. @item scale
  8793. Specify scale used for calculating intensity color values.
  8794. It accepts the following values:
  8795. @table @samp
  8796. @item lin
  8797. linear
  8798. @item sqrt
  8799. square root, default
  8800. @item cbrt
  8801. cubic root
  8802. @item log
  8803. logarithmic
  8804. @end table
  8805. Default value is @samp{sqrt}.
  8806. @item saturation
  8807. Set saturation modifier for displayed colors. Negative values provide
  8808. alternative color scheme. @code{0} is no saturation at all.
  8809. Saturation must be in [-10.0, 10.0] range.
  8810. Default value is @code{1}.
  8811. @item win_func
  8812. Set window function.
  8813. It accepts the following values:
  8814. @table @samp
  8815. @item none
  8816. No samples pre-processing (do not expect this to be faster)
  8817. @item hann
  8818. Hann window
  8819. @item hamming
  8820. Hamming window
  8821. @item blackman
  8822. Blackman window
  8823. @end table
  8824. Default value is @code{hann}.
  8825. @end table
  8826. The usage is very similar to the showwaves filter; see the examples in that
  8827. section.
  8828. @subsection Examples
  8829. @itemize
  8830. @item
  8831. Large window with logarithmic color scaling:
  8832. @example
  8833. showspectrum=s=1280x480:scale=log
  8834. @end example
  8835. @item
  8836. Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
  8837. @example
  8838. ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
  8839. [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
  8840. @end example
  8841. @end itemize
  8842. @section showwaves
  8843. Convert input audio to a video output, representing the samples waves.
  8844. The filter accepts the following options:
  8845. @table @option
  8846. @item size, s
  8847. Specify the video size for the output. For the syntax of this option, check
  8848. the "Video size" section in the ffmpeg-utils manual. Default value
  8849. is "600x240".
  8850. @item mode
  8851. Set display mode.
  8852. Available values are:
  8853. @table @samp
  8854. @item point
  8855. Draw a point for each sample.
  8856. @item line
  8857. Draw a vertical line for each sample.
  8858. @item p2p
  8859. Draw a point for each sample and a line between them.
  8860. @item cline
  8861. Draw a centered vertical line for each sample.
  8862. @end table
  8863. Default value is @code{point}.
  8864. @item n
  8865. Set the number of samples which are printed on the same column. A
  8866. larger value will decrease the frame rate. Must be a positive
  8867. integer. This option can be set only if the value for @var{rate}
  8868. is not explicitly specified.
  8869. @item rate, r
  8870. Set the (approximate) output frame rate. This is done by setting the
  8871. option @var{n}. Default value is "25".
  8872. @item split_channels
  8873. Set if channels should be drawn separately or overlap. Default value is 0.
  8874. @end table
  8875. @subsection Examples
  8876. @itemize
  8877. @item
  8878. Output the input file audio and the corresponding video representation
  8879. at the same time:
  8880. @example
  8881. amovie=a.mp3,asplit[out0],showwaves[out1]
  8882. @end example
  8883. @item
  8884. Create a synthetic signal and show it with showwaves, forcing a
  8885. frame rate of 30 frames per second:
  8886. @example
  8887. aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
  8888. @end example
  8889. @end itemize
  8890. @section split, asplit
  8891. Split input into several identical outputs.
  8892. @code{asplit} works with audio input, @code{split} with video.
  8893. The filter accepts a single parameter which specifies the number of outputs. If
  8894. unspecified, it defaults to 2.
  8895. @subsection Examples
  8896. @itemize
  8897. @item
  8898. Create two separate outputs from the same input:
  8899. @example
  8900. [in] split [out0][out1]
  8901. @end example
  8902. @item
  8903. To create 3 or more outputs, you need to specify the number of
  8904. outputs, like in:
  8905. @example
  8906. [in] asplit=3 [out0][out1][out2]
  8907. @end example
  8908. @item
  8909. Create two separate outputs from the same input, one cropped and
  8910. one padded:
  8911. @example
  8912. [in] split [splitout1][splitout2];
  8913. [splitout1] crop=100:100:0:0 [cropout];
  8914. [splitout2] pad=200:200:100:100 [padout];
  8915. @end example
  8916. @item
  8917. Create 5 copies of the input audio with @command{ffmpeg}:
  8918. @example
  8919. ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
  8920. @end example
  8921. @end itemize
  8922. @section zmq, azmq
  8923. Receive commands sent through a libzmq client, and forward them to
  8924. filters in the filtergraph.
  8925. @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
  8926. must be inserted between two video filters, @code{azmq} between two
  8927. audio filters.
  8928. To enable these filters you need to install the libzmq library and
  8929. headers and configure FFmpeg with @code{--enable-libzmq}.
  8930. For more information about libzmq see:
  8931. @url{http://www.zeromq.org/}
  8932. The @code{zmq} and @code{azmq} filters work as a libzmq server, which
  8933. receives messages sent through a network interface defined by the
  8934. @option{bind_address} option.
  8935. The received message must be in the form:
  8936. @example
  8937. @var{TARGET} @var{COMMAND} [@var{ARG}]
  8938. @end example
  8939. @var{TARGET} specifies the target of the command, usually the name of
  8940. the filter class or a specific filter instance name.
  8941. @var{COMMAND} specifies the name of the command for the target filter.
  8942. @var{ARG} is optional and specifies the optional argument list for the
  8943. given @var{COMMAND}.
  8944. Upon reception, the message is processed and the corresponding command
  8945. is injected into the filtergraph. Depending on the result, the filter
  8946. will send a reply to the client, adopting the format:
  8947. @example
  8948. @var{ERROR_CODE} @var{ERROR_REASON}
  8949. @var{MESSAGE}
  8950. @end example
  8951. @var{MESSAGE} is optional.
  8952. @subsection Examples
  8953. Look at @file{tools/zmqsend} for an example of a zmq client which can
  8954. be used to send commands processed by these filters.
  8955. Consider the following filtergraph generated by @command{ffplay}
  8956. @example
  8957. ffplay -dumpgraph 1 -f lavfi "
  8958. color=s=100x100:c=red [l];
  8959. color=s=100x100:c=blue [r];
  8960. nullsrc=s=200x100, zmq [bg];
  8961. [bg][l] overlay [bg+l];
  8962. [bg+l][r] overlay=x=100 "
  8963. @end example
  8964. To change the color of the left side of the video, the following
  8965. command can be used:
  8966. @example
  8967. echo Parsed_color_0 c yellow | tools/zmqsend
  8968. @end example
  8969. To change the right side:
  8970. @example
  8971. echo Parsed_color_1 c pink | tools/zmqsend
  8972. @end example
  8973. @c man end MULTIMEDIA FILTERS
  8974. @chapter Multimedia Sources
  8975. @c man begin MULTIMEDIA SOURCES
  8976. Below is a description of the currently available multimedia sources.
  8977. @section amovie
  8978. This is the same as @ref{movie} source, except it selects an audio
  8979. stream by default.
  8980. @anchor{movie}
  8981. @section movie
  8982. Read audio and/or video stream(s) from a movie container.
  8983. It accepts the following parameters:
  8984. @table @option
  8985. @item filename
  8986. The name of the resource to read (not necessarily a file; it can also be a
  8987. device or a stream accessed through some protocol).
  8988. @item format_name, f
  8989. Specifies the format assumed for the movie to read, and can be either
  8990. the name of a container or an input device. If not specified, the
  8991. format is guessed from @var{movie_name} or by probing.
  8992. @item seek_point, sp
  8993. Specifies the seek point in seconds. The frames will be output
  8994. starting from this seek point. The parameter is evaluated with
  8995. @code{av_strtod}, so the numerical value may be suffixed by an IS
  8996. postfix. The default value is "0".
  8997. @item streams, s
  8998. Specifies the streams to read. Several streams can be specified,
  8999. separated by "+". The source will then have as many outputs, in the
  9000. same order. The syntax is explained in the ``Stream specifiers''
  9001. section in the ffmpeg manual. Two special names, "dv" and "da" specify
  9002. respectively the default (best suited) video and audio stream. Default
  9003. is "dv", or "da" if the filter is called as "amovie".
  9004. @item stream_index, si
  9005. Specifies the index of the video stream to read. If the value is -1,
  9006. the most suitable video stream will be automatically selected. The default
  9007. value is "-1". Deprecated. If the filter is called "amovie", it will select
  9008. audio instead of video.
  9009. @item loop
  9010. Specifies how many times to read the stream in sequence.
  9011. If the value is less than 1, the stream will be read again and again.
  9012. Default value is "1".
  9013. Note that when the movie is looped the source timestamps are not
  9014. changed, so it will generate non monotonically increasing timestamps.
  9015. @end table
  9016. It allows overlaying a second video on top of the main input of
  9017. a filtergraph, as shown in this graph:
  9018. @example
  9019. input -----------> deltapts0 --> overlay --> output
  9020. ^
  9021. |
  9022. movie --> scale--> deltapts1 -------+
  9023. @end example
  9024. @subsection Examples
  9025. @itemize
  9026. @item
  9027. Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
  9028. on top of the input labelled "in":
  9029. @example
  9030. movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
  9031. [in] setpts=PTS-STARTPTS [main];
  9032. [main][over] overlay=16:16 [out]
  9033. @end example
  9034. @item
  9035. Read from a video4linux2 device, and overlay it on top of the input
  9036. labelled "in":
  9037. @example
  9038. movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
  9039. [in] setpts=PTS-STARTPTS [main];
  9040. [main][over] overlay=16:16 [out]
  9041. @end example
  9042. @item
  9043. Read the first video stream and the audio stream with id 0x81 from
  9044. dvd.vob; the video is connected to the pad named "video" and the audio is
  9045. connected to the pad named "audio":
  9046. @example
  9047. movie=dvd.vob:s=v:0+#0x81 [video] [audio]
  9048. @end example
  9049. @end itemize
  9050. @c man end MULTIMEDIA SOURCES