Zg/add volume control (#302)

Author: zgreathouse

examples/next-app/components/ExampleComponent.tsx

@@ -40,6 +40,8 @@ export const ExampleComponent = () => {
     lastUserMessage,
     lastVoiceMessage,
     isPaused,
+    volume,
+    setVolume,
   } = useVoice();
 
   const [textValue, setTextValue] = useState('');
@@ -56,6 +58,14 @@ export const ExampleComponent = () => {
   }, [isPaused, resumeAssistant, pauseAssistant]);
   const pausedText = isPaused ? 'Resume' : 'Pause';
 
+  const handleVolumeChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const newVolume = parseFloat(event.target.value);
+      setVolume(newVolume);
+    },
+    [setVolume],
+  );
+
   const callDuration = (
     <div>
       <div className={'text-sm font-medium uppercase'}>Call duration</div>
@@ -134,6 +144,25 @@ export const ExampleComponent = () => {
                   {isAudioMuted ? 'Unmute Audio' : 'Mute Audio'}
                 </button>
 
+                <div className="flex flex-col gap-1 pt-2">
+                  <label
+                    htmlFor="volumeSlider"
+                    className="text-sm font-medium uppercase"
+                  >
+                    Volume ({Math.round(volume * 100)}%)
+                  </label>
+                  <input
+                    id="volumeSlider"
+                    type="range"
+                    min="0"
+                    max="1"
+                    step="0.01"
+                    value={volume}
+                    onChange={handleVolumeChange}
+                    disabled={isAudioMuted}
+                  />
+                </div>
+
                 <div className="flex gap-10">
                   <Waveform fft={audioFft} />
                   <Waveform fft={micFft} />

packages/react/README.md

@@ -196,6 +196,10 @@ Mute the assistant audio
 
 Unmute the assistant audio
 
+#### `setVolume`: (level: number) => void
+
+Sets the playback volume for audio generated by the assistant. Input values are clamped between `0.0` (silent) and `1.0` (full volume).
+
 #### `sendSessionSettings`: (message: [SessionSettings](https://github.com/HumeAI/hume-typescript-sdk/blob/ac89e41e45a925f9861eb6d5a1335ab51d5a1c94/src/api/resources/empathicVoice/types/SessionSettings.ts)) => void
 
 Send new session settings to the assistant. This overrides any session settings that were passed as props to the VoiceProvider.
@@ -230,6 +234,10 @@ Boolean that describes whether the microphone is muted.
 
 Boolean that describes whether the assistant audio is muted.
 
+#### `volume`: number
+
+The current playback volume level for the assistant's voice, ranging from `0.0` (silent) to `1.0` (full volume). Defaults to `1.0`.
+
 #### `isPlaying`: boolean
 
 Describes whether the assistant audio is currently playing.

packages/react/src/lib/VoiceProvider.tsx

@@ -87,6 +87,8 @@ export type VoiceContextType = {
   chatMetadata: ChatMetadataMessage | null;
   playerQueueLength: number;
   isPaused: boolean;
+  volume: number;
+  setVolume: (level: number) => void;
 };
 
 const VoiceContext = createContext<VoiceContextType | null>(null);
@@ -521,6 +523,8 @@ export const VoiceProvider: FC<VoiceProviderProps> = ({
         chatMetadata: messageStore.chatMetadata,
         playerQueueLength: player.queueLength,
         isPaused,
+        volume: player.volume,
+        setVolume: player.setVolume,
       }) satisfies VoiceContextType,
     [
       connect,
@@ -556,6 +560,8 @@ export const VoiceProvider: FC<VoiceProviderProps> = ({
       callDurationTimestamp,
       toolStatus.store,
       isPaused,
+      player.volume,
+      player.setVolume,
     ],
   );
 

packages/react/src/lib/useSoundPlayer.test.ts

@@ -0,0 +1,27 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { generateEmptyFft } from './generateEmptyFft';
+import { useSoundPlayer } from './useSoundPlayer';
+
+describe('useSoundPlayer', () => {
+  it('should initialize with correct default state', () => {
+    const mockOnError = vi.fn();
+    const mockOnPlayAudio = vi.fn();
+    const mockOnStopAudio = vi.fn();
+
+    const { result } = renderHook(() =>
+      useSoundPlayer({
+        onError: mockOnError,
+        onPlayAudio: mockOnPlayAudio,
+        onStopAudio: mockOnStopAudio,
+      }),
+    );
+
+    expect(result.current.volume).toBe(1.0); // full volume
+    expect(result.current.isAudioMuted).toBe(false); // not muted
+    expect(result.current.isPlaying).toBe(false); // not playing
+    expect(result.current.queueLength).toBe(0); // empty queue
+    expect(result.current.fft).toEqual(generateEmptyFft()); // empty fft
+  });
+});

packages/react/src/lib/useSoundPlayer.ts

@@ -12,6 +12,7 @@ export const useSoundPlayer = (props: {
 }) => {
   const [isPlaying, setIsPlaying] = useState(false);
   const [isAudioMuted, setIsAudioMuted] = useState(false);
+  const [volume, setVolumeState] = useState<number>(1.0);
   const [fft, setFft] = useState<number[]>(generateEmptyFft());
 
   const audioContext = useRef<AudioContext | null>(null);
@@ -171,6 +172,7 @@ export const useSoundPlayer = (props: {
     isProcessing.current = false;
     setIsPlaying(false);
     setIsAudioMuted(false);
+    setVolumeState(1.0);
 
     if (frequencyDataIntervalId.current) {
       window.clearInterval(frequencyDataIntervalId.current);
@@ -218,6 +220,20 @@ export const useSoundPlayer = (props: {
     setFft(generateEmptyFft());
   }, []);
 
+  const setVolume = useCallback(
+    (newLevel: number) => {
+      const clampedLevel = Math.max(0, Math.min(newLevel, 1.0));
+      setVolumeState(clampedLevel);
+      if (gainNode.current && audioContext.current && !isAudioMuted) {
+        gainNode.current.gain.setValueAtTime(
+          clampedLevel,
+          audioContext.current.currentTime,
+        );
+      }
+    },
+    [isAudioMuted],
+  );
+
   const muteAudio = useCallback(() => {
     if (gainNode.current && audioContext.current) {
       gainNode.current.gain.setValueAtTime(0, audioContext.current.currentTime);
@@ -227,10 +243,13 @@ export const useSoundPlayer = (props: {
 
   const unmuteAudio = useCallback(() => {
     if (gainNode.current && audioContext.current) {
-      gainNode.current.gain.setValueAtTime(1, audioContext.current.currentTime);
+      gainNode.current.gain.setValueAtTime(
+        volume,
+        audioContext.current.currentTime,
+      );
       setIsAudioMuted(false);
     }
-  }, []);
+  }, [volume]);
 
   return {
     addToQueue,
@@ -243,5 +262,7 @@ export const useSoundPlayer = (props: {
     stopAll,
     clearQueue,
     queueLength,
+    volume,
+    setVolume,
   };
 };