Add custom sound effect Lua API

[griffi-gh]

Proof-of-concept sound effect API

Adds following functions:

• this:create_sfx(sample_array: table, name: string?) -> sfx
  Creates a sound effect. Sample array is an array of samples (floating-point, 2 channels at 44khz)
  Each sample must be a floating point number in range: -1.0..1.0 (out-of-range values are clamped)
  Number of samples must be a multiple of number of channels (2)
  Ordering is as follows: [right ch. sample 1][left ch. sample 1][right ch. sample 2][left ch. sample 2]... and so on
• sfx:play(volume: number?)
sfx:play(volume: number?, x: number, y: number)
  If position is omitted: Play sound effect globally with specified volume (full volume if nil/omitted)
  If position is specified: Plays the sound effect locally at the specified coordinates with the specified volume (full volume if nil)

TODO:

• allow creating sound effects and playing them
• allow setting sound source position and volume (add optional args to sfx:play(...))
• support different source formats (e.g. integer samples or mono channel)
  • float, 2 channels
  • float, 1 channel
  • sint, 2 channels
  • sint, 1 channel
  • uint, 2 channels
  • uint, 1 channel
• extend function to append extra chunks to an existing sfx object
• figure out how and when to properly clean up sound effect objects?
  • __gc gets called randomly?
  • can sound effects be freed while they're playing?

MAYBE:

• create a tool like the image to lua one for converting wav/ogg/mp3/etc files to a list of samples for create_sfx.
• function to get built-in sound effects as SfxMT userdatas? which would allow this api to also play built-in ones
• some sort of "real-time" audio playback feature for longer audio? (with callback for generating audio data)
• support various sample rates? (for simplicity sake, only support integer divisors of 44khz)

[griffi-gh]

(enable sound for this one)

2024-10-20_17-58-39.mp4