Audio crossfading and effects

rkevin-arch commented 3 years ago

THIS IS A DRAFT PR. DO NOT MERGE YET.

This PR adds audio crossfading, custom audio filters, OpenAL filters and effects. All of the following would work on BGM, BGS and ME (not SE) unless stated otherwise.

It adds the following APIs to the Audio module:

Audio.bgm_crossfade(filename, time = 2, volume = 100, pitch = 100, pos = -1): acts the same way as Audio.bgm_play, but it crossfades between the currently playing track and the new one over time seconds.
Audio.bgm_add_filter: Adds a custom filter to the currently playing audio. Currently only one type of filter (Rectifier) is supported. Use Audio.bgm_clear_filter to clear all custom filters.
- Note these filters have a delay of around 0.75s between setting the filter and it actually being applied. I'm working on a way to fix it.
- Also, these filters do not persist after changing a track. I'm also working on it.
- To create a rectifier filter, call Audio.bgm_add_filter("Rectifier", intensity). The intensity is between 0 and 1 and behaves the same way as Audacity's rectifier distortion.
- To write your own custom filter, look in this WIP documentation or ask rkevin.
Audio.bgm_set_al_filter: Sets an OpenAL filter to the currently playing audio. There are 3 types, lowpass, highpass and bandpass. I'm not actually sure what this does, I can hear no difference, but OpenAL exposes it. Use Audio.bgm_clear_al_filter to clear it.
- Call Audio.bgm_set_al_filter(0, gain, gainhf) to create a lowpass filter.
- Call Audio.bgm_set_al_filter(1, gain, gainlf) to create a highpass filter.
- Call Audio.bgm_set_al_filter(2, gain, gainlf, gainhf) to create a bandpass filter.
- You can only have one AL filter at a time, and it's unknown what will happen when you set this with an AL effect.
- This also works on SEs.
Audio.bgm_set_al_effect(effect): Sets an OpenAL effect to the currently running audio. For how to construct an effect object, look below. Use Audio.bgm_clear_al_effect to clear it.
- You can only have one AL effect at a time.
- This also works on SEs.

The ALEffect ruby module has been added, and you can create different types of AL effects using it. For example, to construct a EAXReverb effect and set the density attribute, do:

effect = ALEffect::EAXReverb.new
effect.density = 1

For a list of all possible effects and their attributes, check out binding-mri/aleffect-binding.cpp for now. For a list of what the attributes mean, consult the OpenAL Effects Extension Guide (you can ask for a copy in the ModShot discord).

There's also a list of presets for EAXReverb type effects. Check binding-mri/aleffect-binding.cpp for a list of them. To load a preset (such as the dizzy preset), do the following:

effect = ALEffect::EAXReverb.new
effect.load_preset_dizzy
# you may further modify the preset if you wish before using it

The following enhancements are added:

If you use Audio.bgm_play with the pos parameter set, you can start playing from that location even if you are currently playing the same file.
- Setting pos to 0 will start playing from the beginning.
Added fadeInOnOffset parameter to bgm_play (like Audio.bgm_play(filename, volume = 100, pitch = 100, pos = -1, fadeInOnOffset = true). By default, if you set the pos parameter to a nonnegative number, the audio will fade in over 1 second. Set this to false if you don't want this behavior.

Other things that sneaked into this PR:

.vscode is now in the gitignore file
Fixed a race condition for Audio.bgm_playing? introduced in #12.

This PR has a lot of non trivial changes. We should probably test this for a while and see if it causes any issues before actually merging it. Please run ModShot with the ALSOFT_LOGLEVEL=3 environment variable and log any OpenAL errors that may occur.

Astrabit-ST / ModShot-Core

Audio crossfading and effects #23