Sound refactor and improvements

[Desour]

• Big refactor of the client-side sound manager, and other things related to sounds. See below for a list of changes.
• Does this relate to a goal in the roadmap: Most of the PR can be considered internal code refactoring.
• PR contains bugfixes.

PR is based on:

• Pause shader animation timer in singleplayer pause menu #12766 (If we don't pause sounds, the sound queues for streaming sounds will run empty.)
• [nosquash] Devtest: Add jukebox and branding iron #12774

Changes

This PR includes the following changes (list may miss minor changes that I forgot):

• Terminology and Documentation: Definition of "sound groups" (i.e. sound.1.ogg, sound.2.ogg, ...).
• Enhancement: Sounds are loaded lazily. This makes the client connect much faster.
  (fixes Music / large sound files significantly slow down game startup #10603, improves Slow loading times #10316)
• Enhancement: Long sounds (> 3 seconds) (i.e. music) are streamed (not over network, but from file). So, the client doesn't freeze anymore when music from the sound-pack or dynamic media is played.
  (makes Game-provided menu music #8596/Add support for music #7867 possible)
• API feature: time_offset start_time sound param (offset in seconds into file).
  (fixes Start a sound at a specific timestamp #11865; will be needed at some point anyways for players entering max_hear_distance)
  (also fixes Fade and sound playback with gain <= 0 delete the handle (for mute) #4256)
• Fix: Sound is no longer upside-down. (see comment in sound_openal_internal.h about sound-space) (test with hrtf)
• Internal refactor: Got rid of BS in sound manager.
• API change: Sound handles are now userdata. => method syntax; ids are owned and garbage collected
  Edit: Server sound change moved out to Put server sound handles into userdata #12780.
• Enhancement/Fix: Sounds are paused while in pause menu in singleplayer.
• Fix: Shader animation timer is also paused. (Has nothing to do with sounds, but I was already at it.)
  Edit: Moved out to Pause shader animation timer in singleplayer pause menu #12766.
• Fix: Warning in errorstream warningstream for positional stereo sounds, and don't play.
  (fixes Add warning when stereo sounds are loaded #6622)
• Fix: Don't spam (infostream) logs with every file tried in sound-pack.
  (fixes Audio: Error opening file for decoding #10979)
• Documentation: Add correct documentation of sound params, and more details for gain of positional sounds.
  (fixes Incomplete Documentation of 'params' sound parameter table, used by minetest.sound_play() #11414)
• Fix: Enable fade in for positional sounds.
  (fixes minetest.sound_fade [fading in] doesn't work with positional sounds. #6748)
• Fix: Fade correctly for positional sounds. (step is scaled correctly (used to be too slow by a factor of 3). And you can fade to gain>1/3.)
• Fix: Vorbis seek callback now supports SEEK_END (is not optional according to https://www.xiph.org/vorbis/doc/vorbisfile/callbacks.html). (Idk if this has practical relevance.)
• Enhancement: Doppler effect. Edit: Disabled. It should be server-controlled.
  (see: Add Doppler effect #9172)
• Feature: Client-side setting for doppler factor (because you can be very fast in minetest).
• Fix/Enhancement: Footstep sounds of objects are played at feet (found via collisionbox). (Velocity is still 0, btw..)
  Edit: Moved out to [nosquash] Bigfoot and footstep at feet #12768.
• No change: Player footstep sounds are still position-less (sounds bad otherwise, if running with fast).
• Internal refactor: C++ SimpleSoundSpec struct was renamed to SoundSpec, because it's not simple, and to differentiate from modding SimpleSoundSpec.
• Enhancement: Testing devices in devtest: jukebox updated; racecar for doppler
• Internal refactor: OnDemandSoundFetcher was renamed to SoundLocalFallbackPathsGiver, as that describes better what it does.
• Internal refactor: Some smart-ptr-isation here and there.
• Internal refactor / design change: The sound manager API is changed in such a way that the functions could be implemented asynchronously. E.g. soundPlay does not return an id, instead you have to give an id that you allocated before. Moving the sound manager to a different thread would be relatively easy.

Review help

• The client/sound* files contain the most real changes. Everything else is essentially just adjusted to the new interface.
  You can compare behaviour of sound_openal_internal.h/cpp with the old sound_openal.cpp, but idk if it helps.
  Notice that the new interface handles client sound handles differently.
• client/client.h/cpp contains two interesting changes: It creates sound groups based on base names, and m_sounds_client_to_server now owns client-handles.
• game.cpp: GameOnDemandSoundFetcher was moved to client/sound.cpp. Also, sounds are paused here.
• guiEngine.h/cpp: Uses no more raw ptrs (creates some code-change-noise, but not really much). MenuMusicFetcher is simplified, by using base-class functions. GUIEngine::playSound is removed, it's only used by mainmenu scripting.
• clientpackethandler.cpp: Uses ids. And time_offset is added.
• l_sound.h/cpp: Is now l_mainmenu_sound.h/cpp.
• The scripting changes are much code, but very simple. It's mostly copied code and boilerplate code for userdata handles. Otherwise, it just has the SoundSpec renames, and it uses the new id system.
• server.cpp: Sends time_offset.
• src/sound.h: The use_local_fallback is currently unused. But it's passed to the sound manager and should be functional, if the sound wasn't played before.
• Everything else is just trivial renaming (SoundSpec) and smart-ptrs.

To do

This PR is a Ready for Review.

How to test

• Just play and look if there are any warnings or similar.
• Walk to listen to footsteps.
• Punch.
• Press esc (to pause sounds).
• Use the devtest jukebox, e.g. to play a technic track from your sound-pack: https://wiki.minetest.net/Sound_Packs#Technic
• /set sound_doppler_factor Edit: Doppler effect is disabled, and this setting does not exist.
• Drive around in cart.
• To enable hrtf: $ alsoft-config -> HRTF -> HRTF mode: Always on.
• Use the entity spawner item in devtest to spawn a racecar. Give it a name with the branding iron. Play a sound attached to it with the jukebox. Or attach yourself to it with the object attacher devtest tool.

[MisterE123]

I hope this gets merged. I recognized several bugs from the description that I was annoyed at in the game without realizing it.

[appgurueu]

Sounds are loaded lazily. This makes the client connect much faster.

Does this introduce any significant delay in sound playback?

[rubenwardy]

Does this introduce any significant delay in sound playback?

Yeah, sounds shouldn't be lazy loaded. Only music should be. Mods should then choose between music and sound based on what kind of latency then can tolerate

However, I suspect they mean lazy loading from client cache on disk, rather than over the network, which isn't as bad

[sfan5]

I think Minetest should automatically decide whether to pre-load sounds, quoting #10603 (comment):

There's a good reason to preload short sounds, but not music or ambient textures, because that's a ton of decoding work and wasted RAM.

Game engines usually give you both options. Unity for example lets you choose between preloaded ADPCM in memory for short clips, and Vorbis decoded on the fly for longer sounds. We could autodetect this based on the clip length, something like 10 seconds should disqualify a sound from being preloaded.

The first few seconds of streamed clips could still be cached to give the decoder some time to build a buffer.

---

other feedback as already written on IRC:

• at the very least the "I happened to touch this code and made it better" changes (for code unrelated to sound) should be in a separate commit
• also the addition of ServerSoundRef

[Desour]

Sounds are loaded lazily. This makes the client connect much faster.

Does this introduce any significant delay in sound playback?

(The loading I was referring to was just the decoding from ogg vorbis data (from ram, or sound-pack; not from network) to pcm data, and giving that data to OpenAL.)
There's no delay in the sound playback. The client freezes until the sound is loaded (for much less than 1/60 second, if it's not too many new sounds at once).
The sounds are also never de-loaded.
So, the only thing that is worse because of not pre-loaded sounds is that, if you play many different sounds, that the client hasn't ever played yet during the current game session, the client can freeze for a second or so. This is not too likely to happen, and it's not that big of a problem, imo. Therefore, I came to the conclusion that such an option is currently not worth the implementation effort.

---

I'll split the PR and make it more reviewable.

[Desour]

I consider this PR ready for review now.

It would make sense to review and merge the dependencies first though.

[Desour]

Rebased.
And also positional stereo sounds are played now, to keep backwards compatibility. They are still broken (=non-positional) tough. There's a warning.

[Desour]

Rebased.

[Desour]

Rebased.

[ghost]

I hope this gets merged soon. One of the biggest issues that the minetest engine has, is that playing soundtracks is very taxing for some reason.

[Desour]

Rebased (+ 2 commits). (The now missing util/Optional.h would've failed silently FYI. Might be worth re-running CI on some other PRs.)

[sfan5]

I suppose the "just merge it and see" approach is best for this

[Desour]

Looked a last time over it, and removed some trivial changes left over from a rebase. Should be fine.