Clarify what happens when setting the audio volume

[hate]

Objective

• Fixes #8835

Solution

• Added a note to the set_volume docstring which explains how volume is interpreted.

[alice-i-cecile]

I think that the suggestion will give nicer formatting, but otherwise this LGTM.

[github-actions]

Example alien_cake_addict failed to run, please try running it locally and check the result.

[github-actions]

Example alien_cake_addict failed to run, please try running it locally and check the result.

[mockersf]

I think I don't agree with the comment. The video is audio at 1.0, then 0.01, then 1.0. for me it's much less than half the volume.

audio-controls.mp4

[alice-i-cecile]

That would be a quarter, based on the comment, but that's still perceived as much less than that to me.

[GitGhillie]

Sound is doubled with every 3dB, so to get half the sound you would need -3dB, or a power of 10^-3/10 ~= 0.5. If we take the square root of 0.5 you get 0.708 which is what you would need to set the volume to in order to halve the sound from the original 1.0 setting. Multiply the volume by 0.708 to halve the sound again etc. See table below:

To make things more complicated:
"an increase of 10 dB roughly corresponds to the perceived volume doubling in intensity"

This means you would have to set the volume to 0.316 to perceive it half as loud as 1.0.
And 0.316 * 0.316 to perceive it 4 times less loud compared to 1.0.

These numbers seem to check out when I try it on the example, as well as the change in dB levels when I check with OBS.
See also my comments on the issue: #8835, I'm not surprised 0.01 is very quiet.

[harudagondi]

I agree with the documentation, but I am wondering if we should have it accept something like

enum Volume {
    Logarithmic(f32),
    Linear(u8), // 255 is the 100%, 128 is 50% of the volume, etc.
}

instead of just f32.