From 252b9c0c04d574b2fdb02e30cb0894e558eb02d8 Mon Sep 17 00:00:00 2001
From: Mitchell Foote <mitchellfoote93@gmail.com>
Date: Sat, 16 Sep 2023 21:07:33 -0600
Subject: [PATCH 1/2] feat(Sounds): Added Preserve Audio Channels Capability.

---
 server/classes/sound.js                   | 1 +
 server/typeDefs/clients.ts                | 2 ++
 src/components/client/soundController.tsx | 1 +
 src/components/generic/SoundPlayer.tsx    | 3 ++-
 src/components/macros/playSound.js        | 8 ++++++++
 src/generated/graphql.tsx                 | 2 ++
 src/schema.graphql                        | 2 ++
 7 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/server/classes/sound.js b/server/classes/sound.js
index 6443fb55f..62beab2ec 100644
--- a/server/classes/sound.js
+++ b/server/classes/sound.js
@@ -10,5 +10,6 @@ export default class Sound {
     this.playbackRate = params.playbackRate || 1;
     this.channel = params.channel || [0, 1];
     this.looping = params.looping || false;
+    this.preserveChannels = params.preserveChannels || false;
   }
 }
diff --git a/server/typeDefs/clients.ts b/server/typeDefs/clients.ts
index b451a7e8e..3dd32bc55 100644
--- a/server/typeDefs/clients.ts
+++ b/server/typeDefs/clients.ts
@@ -77,6 +77,7 @@ const schema = gql`
     playbackRate: Float
     channel: [Int]
     looping: Boolean
+    preserveChannels: Boolean
   }
 
   input SoundInput {
@@ -87,6 +88,7 @@ const schema = gql`
     playbackRate: Float
     channel: [Int]
     looping: Boolean
+    preserveChannels: Boolean
   }
 
   extend type Query {
diff --git a/src/components/client/soundController.tsx b/src/components/client/soundController.tsx
index 24f2efbe5..3f37938d0 100644
--- a/src/components/client/soundController.tsx
+++ b/src/components/client/soundController.tsx
@@ -13,6 +13,7 @@ const SOUND_SUB = gql`
       playbackRate
       channel
       looping
+      preserveChannels
     }
   }
 `;
diff --git a/src/components/generic/SoundPlayer.tsx b/src/components/generic/SoundPlayer.tsx
index ab7fcb15c..45c9be32e 100644
--- a/src/components/generic/SoundPlayer.tsx
+++ b/src/components/generic/SoundPlayer.tsx
@@ -94,6 +94,7 @@ interface Sound {
   channel?: number | number[];
   source?: AudioBufferSourceNode;
   gain?: GainNode;
+  preserveChannels?: boolean;
   onFinishedPlaying?: () => void;
 }
 export function playSound(opts: Sound) {
@@ -132,7 +133,7 @@ export function playSound(opts: Sound) {
             const sound = {...opts} || {};
             //Create a new buffer and set it to the specified channel.
             sound.source = audioContext.createBufferSource();
-            sound.source.buffer = downMixBuffer(buffer, channel);
+            sound.preserveChannels ? (sound.source.buffer = buffer) : (sound.source.buffer = downMixBuffer(buffer, channel))
             sound.source.loop = opts.looping || false;
             sound.source.playbackRate.setValueAtTime(playbackRate, 0);
             sound.gain = audioContext.createGain();
diff --git a/src/components/macros/playSound.js b/src/components/macros/playSound.js
index f7eacf1cf..639129a38 100644
--- a/src/components/macros/playSound.js
+++ b/src/components/macros/playSound.js
@@ -97,6 +97,14 @@ function PlaySound({updateArgs, args, stations, clients, playSound}) {
           value={sound.channel}
           onChange={e => updateSound("channel", e.target.value.split(","))}
         />
+        <div style={{ display: "flex", gap: '1rem', padding: '20px' }}>
+          <Label>Preserve Audio Channels <small>Advanced</small> </Label>
+          <Input
+            type="checkbox"
+            checked={sound.preserveChannels}
+            onChange={e => updateSound("preserveChannels", e.target.checked)}
+          />
+        </div>
         <Label>Looping</Label>
         <Input
           type="checkbox"
diff --git a/src/generated/graphql.tsx b/src/generated/graphql.tsx
index f80bc0c8a..c071cbec2 100644
--- a/src/generated/graphql.tsx
+++ b/src/generated/graphql.tsx
@@ -7393,6 +7393,7 @@ export type Sound = {
   playbackRate?: Maybe<Scalars['Float']>;
   channel?: Maybe<Array<Maybe<Scalars['Int']>>>;
   looping?: Maybe<Scalars['Boolean']>;
+  preserveChannels?: Maybe<Scalars['Boolean']>;
 };
 
 export type SoundInput = {
@@ -7403,6 +7404,7 @@ export type SoundInput = {
   playbackRate?: Maybe<Scalars['Float']>;
   channel?: Maybe<Array<Maybe<Scalars['Int']>>>;
   looping?: Maybe<Scalars['Boolean']>;
+  preserveChannels?: Maybe<Scalars['Boolean']>;
 };
 
 export type CommandLine = {
diff --git a/src/schema.graphql b/src/schema.graphql
index 04ce2a44a..7bbf76bca 100644
--- a/src/schema.graphql
+++ b/src/schema.graphql
@@ -1646,6 +1646,7 @@ type Sound {
   playbackRate: Float
   channel: [Int]
   looping: Boolean
+  preserveChannels: Boolean
 }
 
 input SoundInput {
@@ -1656,6 +1657,7 @@ input SoundInput {
   playbackRate: Float
   channel: [Int]
   looping: Boolean
+  preserveChannels: Boolean
 }
 
 type CommandLine {

From f93270b44bfa6c6a2f8e4e58255006c4d6c89367 Mon Sep 17 00:00:00 2001
From: Mitchell Foote <mitchellfoote93@gmail.com>
Date: Wed, 4 Oct 2023 11:40:42 -0600
Subject: [PATCH 2/2] added PR review comments and helpful tooltips

---
 server/classes/sound.js            |  2 +-
 src/components/macros/playSound.js | 74 ++++++++++++++++++++++++------
 2 files changed, 61 insertions(+), 15 deletions(-)

diff --git a/server/classes/sound.js b/server/classes/sound.js
index 62beab2ec..3e4227c11 100644
--- a/server/classes/sound.js
+++ b/server/classes/sound.js
@@ -10,6 +10,6 @@ export default class Sound {
     this.playbackRate = params.playbackRate || 1;
     this.channel = params.channel || [0, 1];
     this.looping = params.looping || false;
-    this.preserveChannels = params.preserveChannels || false;
+    this.preserveChannels = params.preserveChannels === false ? false : true;
   }
 }
diff --git a/src/components/macros/playSound.js b/src/components/macros/playSound.js
index 639129a38..588ff59ac 100644
--- a/src/components/macros/playSound.js
+++ b/src/components/macros/playSound.js
@@ -1,12 +1,17 @@
 import React from "react";
-import {FormGroup, Label, Input, Button} from "helpers/reactstrap";
+import { FormGroup, Label, Input, Button, Popover, PopoverHeader, PopoverBody } from "helpers/reactstrap";
 import SoundPicker from "helpers/soundPicker";
 import playSoundHOC from "components/generic/SoundPlayer";
 
-function PlaySound({updateArgs, args, stations, clients, playSound}) {
+function PlaySound({ updateArgs, args, stations, clients, playSound }) {
+  let [showChannelPopover, setShowChannelPopover] = React.useState(false);
+  let [showOverridesPopover, setShowOverridesPopover] = React.useState(false);
+  const toggleChannelPopover = () => setShowChannelPopover(!showChannelPopover);
+  const toggleOverridesPopover = () => setShowOverridesPopover(!showOverridesPopover);
+
   const sound = args.sound || {};
   const updateSound = (which, val) => {
-    updateArgs("sound", {...sound, [which]: val});
+    updateArgs("sound", { ...sound, [which]: val });
   };
   React.useEffect(() => {
     if (!args.station) {
@@ -66,9 +71,9 @@ function PlaySound({updateArgs, args, stations, clients, playSound}) {
         </Input>
 
         <Label>Volume</Label>
-        <div style={{display: "flex"}}>
+        <div style={{ display: "flex" }}>
           <Input
-            style={{flex: 1}}
+            style={{ flex: 1 }}
             type="range"
             min={0}
             step={0.01}
@@ -88,23 +93,64 @@ function PlaySound({updateArgs, args, stations, clients, playSound}) {
           value={sound.playbackRate}
           onChange={e => updateSound("playbackRate", e.target.value)}
         />
+        <div style={{ display: "flex", gap: '1rem', padding: '20px', alignItems: 'center' }}>
+          <Label style={{ marginBottom: '0px' }}>
+            <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+              Preserve Surround Channels <small>Advanced</small>
+              <div>
+                <Button id="preserve-surround-channels" onClick={toggleChannelPopover} size="sm" color={'link'}>
+                  <small>Help</small>
+                </Button>
+                <Popover placement={'right'} isOpen={showChannelPopover} target={'preserve-surround-channels'} toggle={toggleChannelPopover}>
+                  <PopoverHeader>Preserve Surround Channels</PopoverHeader>
+                  <PopoverBody>
+                    With this option selected, the audio files will play all channels that they have been built with.
+                    This allows you to use audio files coded for 5.1 and beyond to be played through the sound player. This is the default functionality of the sound player.
+                    <div style={{ marginTop: '0.75rem' }}>
+                      <i>
+                        Note: If this is not selected, Thorium will mix your audio file into a stereo format by using the data from the first 2 channels in your file.
+                        If you are using 5.1 or above files, audio information will be lost.
+                      </i>
+                    </div>
+                  </PopoverBody>
+                </Popover>
+              </div>
+            </div>
+          </Label>
+          <Input
+            style={{ marginBottom: '4px' }}
+            type="checkbox"
+            checked={sound.preserveChannels}
+            onChange={e => updateSound("preserveChannels", e.target.checked)}
+          />
+        </div>
         <Label>
-          Channels <small>Advanced</small>
+          <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+            Channel Mapping Overrides <small>Advanced</small>
+            <div>
+              <Button id="channel-mapping-overrides" onClick={toggleOverridesPopover} size="sm" color={'link'}>
+                <small>Help</small>
+              </Button>
+              <Popover placement={'right'} isOpen={showOverridesPopover} target={'channel-mapping-overrides'} toggle={toggleOverridesPopover}>
+                <PopoverHeader>Channel Mapping Overrides</PopoverHeader>
+                <PopoverBody>
+                  If you choose not to preserve the surround channels, you can use this option to fix to the stereo format, and then map the audio channels to different speakers in your sim.
+                  This can be useful if you have a sound that you want to play through a specific speaker, but the audio file is not coded for that speaker.
+                  Example: If you have a different room for an engineering bay, and you want to play a sound just to that area. You can use this field to specify it.
+                </PopoverBody>
+              </Popover>
+            </div>
+          </div>
+
         </Label>
         <Input
           type="text"
+          disabled={sound.preserveChannels}
           placeholder="0,1"
           value={sound.channel}
           onChange={e => updateSound("channel", e.target.value.split(","))}
         />
-        <div style={{ display: "flex", gap: '1rem', padding: '20px' }}>
-          <Label>Preserve Audio Channels <small>Advanced</small> </Label>
-          <Input
-            type="checkbox"
-            checked={sound.preserveChannels}
-            onChange={e => updateSound("preserveChannels", e.target.checked)}
-          />
-        </div>
+
         <Label>Looping</Label>
         <Input
           type="checkbox"