[FFmpeg-user] Documentation and feature request

[Michael Koch]

Hi all,

over the last months I've collected a list what's missing in FFmpeg's 
documentation.
At the end of the list there are a few feature requests.

"amplify" filter:
-- Many options are in the [0..65535] range. It's unclear how these 
options must be set for 8-bit videos. Is it [0..255] in this case, or is 
it always [0..65535]? Which range for a 10-bit video, [0..1023] or 
[0..65535]? Please add this info to the documentation.
-- Documentation for "threshold" option: "Any difference greater or 
equal to this value..." I'm not sure if this is correct, or if it should 
read "Any absolute value of the difference greater or equal to this 
value...".  Same question also for "tolerance" option.

"blend" filter:
-- Please add documentation what all the modes do. Some modes are 
self-explaining, but most are not.

"colorconstancy" filter:
-- is mentioned as new in FFmpeg 4.1 here: 
http://www.ffmpeg.org/index.html#news   But I found no documentation at all.

"curves" filter:
-- In the documentation for "preset", please add the coordinates of the 
points for all presets. For example, what does "strong_contrast" mean? 
How strong is it? It would really help to see the coordinates of the points.
-- Documentation of "master" option: Please add an example and explain it.

"eq" filter:
-- Please add documentation in which order brightness, contrast, 
saturation and gamma are handled. Is it the same order as written in the 
command line? Or is it always a fixed order (which one?), regardless of 
the order in the command line? For example, adjusting brightness before 
contrast would not give the same result as contrast before brightness 
(multiplication before addition vs. addition before multiplication).
-- It might be helpful to add a note that multiple eq filters can be 
cascaded, for example if contrast enhancement bigger than 2 is required.
-- It might be helpful to point out that this filter includes a limiter, 
if the result is out of range.
-- A few examples would be helpful.

"geq" filter:
-- Please add to the documentation if there is a limiter for overflow 
handling when the result is out of range. I think there is no limiter, 
but I'm not sure.

"tmix" filter:
-- Undocumented feature missing in documentation: If not specified, all 
weights are 1 by default.
-- Add the most simple example to the documentation: "tmix" works and is 
the same as "tmix=frames=3"
-- The last sentence in the documentation is misleading and should be 
changed to "By default scale is set to 1 / (sum of weights)".

Video filters in documentation:
-- These video filters are difficult to find in the documentation 
because they aren't listed in correct alphabetic order: 
colorchannelmixer, elbg, entropy, fftdnoiz, cover_rect, sobel, spp, sr


Feature request for "curves" filter:
-- Please allow import of curves files from GIMP.
-- Make an option for using straight lines instead of smooth curves. 
This would be a nice workaround for strong linear contrast enhancement.

Feature request for "eq" filter:
-- If possible, please allow bigger values for strong contrast 
enhancement, up to 10. In the documentation the contrast range is 
specified as [-2..+2]. There is no error message if contrast>2, but the 
result isn't as expected.

Feature request:
-- A new video filter similar to the "curves" filter, but faster and 
using a linear (not smooth) curve through four points:  0/0 b/0 w/1 
1/1   where parameter b is the black point and w is the white point.
With other words: A video filter for contrast enhancement by defining 
the black and white points.

Feature request:
-- Decay filter, makes short flashes of light appear longer, with an 
exponential decay curve. Like on an analog oscilloscope screen with long 
persistence time. Could be used for videos of the night sky to make fast 
meteors appear longer. Should work as follows:
For each pixel do:  Multiply the RGB values from the previous output 
frame with a decay constant in the range [0..1], for example 0.95. Use 
these RGB values for the next output frame. But if the RGB value from 
the next input frame is brigher than this, then use the brighter value.

Thanks,
Michael