audio: `audio.Player.SetVolume` should panic with an invalid value

[derat]

Ebitengine Version

v2.9.4

Operating System

• Windows
• macOS
• Linux
• FreeBSD
• OpenBSD
• Android
• iOS
• Nintendo Switch
• PlayStation 5
• Xbox
• Web Browsers

Go Version (go version)

1.25

What steps will reproduce the problem?

The documentation for audio.Player.SetVolume at https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2@v2.9.5/audio#Player.SetVolume says this:

volume must be in between 0 and 1. SetVolume panics otherwise.

As far as I can tell, it's fine to set the volume to a value above 1, though -- I don't see a panic, and the audio is amplified as I'd expect. oto looks like it's just multiplying float32 values here:

https://github.com/ebitengine/oto/blob/fca52fc6a0fcdf8d917e70b68376677bd14efb6c/internal/mux/mux.go#L497-L506

If this is indeed an allowed use, would it be reasonable to update the docs to say something like this?

volume must be 0 or higher. If a volume larger than 1 is passed, clipping may occur.

What is the expected result?

Documentation should match the observed behavior.

What happens instead?

Documentation differs from the observed behavior.

Anything else you feel useful to add?

No response

[derat]

Please don't panic for values greater than 1 unless it's necessary to do so, since passing larger values currently seems to work, and this is useful for amplifying audio files that are too quiet. :-)

[hajimehoshi]

Please don't panic for values greater than 1 unless it's necessary to do so, since passing larger values currently seems to work, and this is useful for amplifying audio files that are too quiet. :-)

Hmm, you have to modify the audio stream itself in this case...