Preserving audio file channel configuration

[mitchell-foote]

Is your feature request related to a problem? Please describe.

Sound files are currently being mixed to two channels inside the downMixBuffer function. The sound player currently has a channel configuration object, but as far as I can tell, that value takes the first two channels of the audio file, and maps them into the channels specified. Essentially overwriting the channel data in the other n-number channels.

Based on the discord conversation, the purpose of this was to allow sound effects to play at different areas of the sim, if you had a sim that was large enough to warrant it. This was an advanced setting, enumerated by the "advanced" modifier on the sound player.

We would like to add the ability to play asset files that have been coded for 5.1 audio and beyond to play without being modified or mixed to stereo format.

Describe the solution you'd like

There are two options that we can go down (that I can think of):

First, we can follow the feature flag pattern, and provide an additional field for users to select that will disable this mixing functionality. This will maintain the asset's channel values, and pipe that directly to the specific sound player or station being used.

Pros: The quick toggle makes the change as lightweight as possible, adding a new optional field, piping that through graphql, and having the sound player respect it. The boolean value also makes it less likely that we have regression issues, should we get some unintended side effects.

Cons: Because the fix is simple, we don't take the opportunity to actually improve any of the functionality of the mixer function. We essentially just turn off the function, instead of adding or modifying it. It also doesn't allow for the two areas to be mixed, you either use the channels array, or you allow the flag to be on. So if you want to do something extra custom, you'll need to make another change to thorium for that to work.

Second, we can go through and modify the downMixBuffer function to respect files that have been coded for more than stereo to respect the channels it's been coded with. This would be a breaking change to the functionality, but would also allow us to work in additional functionality that would open up additional possibilities for larger audio configurations.

Pros: With the larger update, if wanted, we could go through and add additional functionality and configuration to the sound player. Essentially allowing users to customize their audio setup so that could potentially avoid using additional software to achieve their sim needs.

Cons: With a larger development of the sound player, comes a higher chance for regression. Backward compatibility testing would be required to ensure cutover to any larger functionality.

Describe alternatives you've considered

With how prescriptive the downMixBuffer function is, it's currently impossible to play audio files through Thorium using more than 2 channels.

Additional context

Beyond the change, it would be valuable to make some documentation updates surrounding these features, regardless of which path we decide to go down. I would be happy to do that PR as well.