Command line switch sws_dither doesn't allow "none"

[Videogamer555]

Summary of the bug: When using the -sws_dither command line switch to disable dithering with the value "none", it still behaves as if it was using the default value of "ed" (which is error diffusion dithering).
How to reproduce:

% ffmpeg -i video_in.avi -swf_dither none animation.gif
ffmpeg version is latest nightly Windows build "N-101948-g870bfe16a1-ffmpeg-windows-build-helpers"
built on April 14, 2021

[Videogamer555]

Replying to Videogamer555:

Summary of the bug: When using the -sws_dither command line switch to disable dithering with the value "none", it still behaves as if it was using the default value of "ed" (which is error diffusion dithering).
How to reproduce:

% ffmpeg -i video_in.avi -swf_dither none animation.gif
ffmpeg version is latest nightly Windows build "N-101948-g870bfe16a1-ffmpeg-windows-build-helpers"
built on April 14, 2021

Note that where it says -swf_dither, it SHOULD say -sws_dither. I accidentally typed an "f" where there should be an "s". But I can't edit my original post, so I'm putting the correction here as a comment.

[Carl Eugen Hoyos]

Does -sws_dither 0 work?

[Anton1699]

This is the relevant part of ffmpeg -h filter=scale:

-sws_dither        <int>        E..V....... set dithering algorithm (from 0 to 6) (default auto)
     auto            1            E..V....... leave choice to sws
     bayer           2            E..V....... bayer dither
     ed              3            E..V....... error diffusion
     a_dither        4            E..V....... arithmetic addition dither
     x_dither        5            E..V....... arithmetic xor dither

Looks like none isn't a valid value. I guess you could try -sws_dither 0 instead.

[Videogamer555]

Replying to cehoyos:

Does -sws_dither 0 work?

I tried 0, and it behaves the same as none or ed. It still dither's via error diffusion.

[Videogamer555]

Replying to Anton1699:

This is the relevant part of ffmpeg -h filter=scale:

-sws_dither        <int>        E..V....... set dithering algorithm (from 0 to 6) (default auto)
     auto            1            E..V....... leave choice to sws
     bayer           2            E..V....... bayer dither
     ed              3            E..V....... error diffusion
     a_dither        4            E..V....... arithmetic addition dither
     x_dither        5            E..V....... arithmetic xor dither

Looks like none isn't a valid value. I guess you could try -sws_dither 0 instead.

But "none" is SUPPOSED TO BE a valid value. In the official documentation at https://ffmpeg.org/ffmpeg-scaler.html it says that for the sws_dither command line switch, that "none" is a valid value. Here's a block quote of the relevant section there.

sws_dither

    Set the dithering algorithm. Accepts one of the following values. Default value is ‘auto’.

    ‘auto’
        automatic choice

    ‘none’
        no dithering

    ‘bayer’
        bayer dither

    ‘ed’
        error diffusion dither

    ‘a_dither’
        arithmetic dither, based using addition

    ‘x_dither’
        arithmetic dither, based using xor (more random/less apparent patterning that a_dither).

The bug here is that the software is not behaving as the official documentation states. I can think of several ways this may occur. The software is supposed to behave as the docs say, but the programmers forgot to write the functionality into the code. Or this was part of a beta or experimental feature that never got added, but was mistakenly put in the official documentation. Or was an old feature that has long ago been removed, but the documentation hasn't been updated accordingly. This feature is planned for some future version, but the person writing the documentation mistakenly documented this feature before it was actually in the software.

Whatever the case may be, the mismatch of the documentation and the software's actual features is a bug that needs to be fixed. Either add the feature to the software, or remove the text describing the feature from the official documentation.

[Balling]

The bug here is that the software is not behaving as the official documentation states.

"Accepts one of the following values" is also a lie, BTW. For example, print_info can be combined with other options and so is accurate_rnd that fixes bgr to yuv420p and so is bitexact which fixes some of jpeg scaling (though the last one I am not so sure, D:) ).

Also, this ticket is a duplicate of #4614. Workaround for no dither is also there in that ticket...

[Anton1699]

"Accepts one of the following values" is also a lie, BTW. For example, print_info can be combined with other options and so is accurate_rnd that fixes bgr to yuv420p and so is bitexact which fixes some of jpeg scaling (though the last one I am not so sure, D:) ).

-sws_dither and -sws_flags are two different things though. -sws_flags is supposed to take multiple flags and the documentation clearly says “It accepts the following values”

[Balling]

Well, also see ​https://trac.ffmpeg.org/ticket/3345#comment:1, it says that dithering is expected and cannot be turned off.

[Balling]

Looks like this 75285325500672a806ba93bfc1e0ace9c9e566c1 and this fa1e158ef648cc080c5c46a620d2d6aaad72ea06 make it better but these should be applied I suppose to fix propogation, if there is the same bug in -sws_dither as in -sws_flags. ​https://patchwork.ffmpeg.org/project/ffmpeg/list/?series=4493&state=*

Maybe use -vf scale only.

BTW. Where is none option here??? ​https://github.com/FFmpeg/FFmpeg/blob/870bfe16a12bf09dca3a4ae27ef6f81a2de80c40/libswscale/options.c#L73 If there is no such option there, 50ce2960263daf48227df758df9ade19db7154fa somehow suggests that -sws_dither none should work, but that is just wrong (?), only -sws_dither 0 will work...

I checked ffplay -v debug 10.mp4 -sws_dither 2 -vf scale=in_color_matrix=auto,format=gbrp

Dunno whether that works, I mean there is no difference, but:

[auto_scaler_0 @ 0000011960019600] Setting 'sws_dither' to value '0'

Strange that

[auto_scaler_0 @ 0000011960019600] Setting 'sws_dither' to value 'none'

is good too. While some garbage leads to "Unable to parse option value".

[Balling]

So none always means 0. ​https://github.com/FFmpeg/FFmpeg/blob/fce01276422a0e121d61aec811ee1773f9013b9c/libavutil/opt.c#L300

So there is no bug. If anything

‘none’

no dithering

should be removed from documentation because it shadows global default. 0 would be more correct.

[Niklas Haas <git@haasn.dev>]

In 5ca5bbd4/ffmpeg:

swscale/options: add -sws_dither none alias

While this one was technically supported on account of the generic options
code allowing "none" as a valid alias for 0, not having it listed here meant
it never showed up in e.g. the -h output, and is also inconsistent with other
places in the code that generally add an explicit alias with appropriate
documentation. Reduces user confusion at negligible cost.

Fixes: #9192
Signed-off-by: Niklas Haas <​git@haasn.dev>
Sponsored-by: Sovereign Tech Fund