feat: add audio output level controls

packages/client/src/Call.ts

@@ -1167,6 +1167,27 @@ export class Call {
     });
   };
 
+  /**
+   * Updates the audio output level for a given sessionId (participant session)
+   * or for all the participants in an active call
+   * of the default call audio output level outside the active call scenarion (e.g. lobby).
+   * @param level
+   * @param sessionId
+   */
+  setAudioOutputLevel(level: number, sessionId?: string) {
+    if (level < 0 || level > 1) {
+      throw new Error(`Audio output level must be in the [0-1] range`);
+    }
+
+    if (sessionId) {
+      this.state.updateParticipant(sessionId, {
+        audioOutputLevel: level,
+      });
+    } else {
+      this.state.setMasterAudioOutputLevel(level);
+    }
+  }
+
   /**
    * Sets the `audioDeviceId` property of the [`localParticipant$`](./StreamVideoClient.md/#readonlystatestore)).
    *

packages/client/src/store/CallState.ts

@@ -82,6 +82,10 @@ export enum CallingState {
  * @react You don't have to use this class directly, as we are exposing the state through Hooks.
  */
 export class CallState {
+  /**
+   * The speaker volume level that is set, if `StreamVideoParticipant.audioOutputLevel` is undefined.
+   */
+  private masterAudioOutputLevelSubject = new BehaviorSubject<number>(1);
   /**
    * The raw call metadata object, as defined on the backend.
    *
@@ -165,8 +169,13 @@ export class CallState {
    */
   private callRecordingListSubject = new BehaviorSubject<CallRecording[]>([]);
 
-  // Derived state
+  /**
+   * Emits the default audio output level value in form of decimal number in range of 0-1.
+   * The default value is assigned to each newly joined StreamVideoParticipant's audioOutputLevel property.
+   */
+  masterAudioOutputLevel$: Observable<number>;
 
+  // Derived state
   /**
    * The time the call session actually started.
    * Useful for displaying the call duration.
@@ -303,6 +312,8 @@ export class CallState {
       distinctUntilChanged(),
     );
 
+    this.masterAudioOutputLevel$ =
+      this.masterAudioOutputLevelSubject.asObservable();
     this.startedAt$ = this.startedAtSubject.asObservable();
     this.participantCount$ = this.participantCountSubject.asObservable();
     this.anonymousParticipantCount$ =
@@ -473,6 +484,27 @@ export class CallState {
     return this.setCurrentValue(this.callingStateSubject, state);
   };
 
+  /**
+   * Retrieves the current value of the default audio output level.
+   *
+   * @internal
+   */
+  get masterAudioOutputLevel() {
+    return this.getCurrentValue(this.masterAudioOutputLevel$);
+  }
+
+  /**
+   * Sets the current value of the default audio output level.
+   *
+   * @internal
+   */
+  setMasterAudioOutputLevel = (level: number) => {
+    if (level < 0 || level > 1) {
+      throw new Error(`Audio output level must be in the [0-1] range`);
+    }
+    return this.setCurrentValue(this.masterAudioOutputLevelSubject, level);
+  };
+
   /**
    * The list of call recordings.
    */

packages/client/src/types.ts

@@ -34,7 +34,13 @@ export enum DebounceType {
 
 export interface StreamVideoParticipant extends Participant {
   /**
-   * The participant's audio stream, if they are publishing audio and
+   * The speaker volume in range 0 - 1 set by the participant.
+   * If not set, then CallState.masterAudioOutputLevel should be reflected.
+   */
+  audioOutputLevel?: number;
+
+  /**
+   * The participant's audio stream, if they are publishing audio, and
    * we have subscribed to it.
    */
   audioStream?: MediaStream;

packages/react-bindings/src/hooks/call.ts

@@ -131,3 +131,14 @@ export const useCallStartedAt = () => {
   const { startedAt$ } = useCallState();
   return useObservableValue(startedAt$);
 };
+
+/**
+ * Utility hook providing the default audio output level in a given call
+ * Should be used to determine audio output level if the call is not joined yet.
+ *
+ * @category Call State
+ */
+export const useMasterAudioOutputLevel = () => {
+  const { masterAudioOutputLevel$ } = useCallState();
+  return useObservableValue(masterAudioOutputLevel$);
+};

packages/react-sdk/src/components/CallControls/AudioOutputLevelSlider.tsx

@@ -0,0 +1,60 @@
+import clsx from 'clsx';
+import {
+  useCall,
+  useMasterAudioOutputLevel,
+} from '@stream-io/video-react-bindings';
+import { MouseEventHandler, useCallback } from 'react';
+import { Icon } from '../Icon';
+import { StreamVideoParticipant } from '@stream-io/video-client';
+
+export type AudioLevelControlProps = {
+  participant?: StreamVideoParticipant;
+};
+
+export const AudioOutputLevelSlider = ({
+  participant,
+}: AudioLevelControlProps) => {
+  const call = useCall();
+  const masterAudioOutputLevel = useMasterAudioOutputLevel();
+
+  const audioLevel = participant?.audioOutputLevel ?? masterAudioOutputLevel;
+
+  const handleClick: MouseEventHandler = useCallback(
+    (event) => {
+      const { width, x } = event.currentTarget.getBoundingClientRect();
+
+      const volume = +((event.clientX - x) / width).toFixed(2);
+      const validatedVolume = volume < 0 ? 0 : volume > 1 ? 1 : volume;
+      call?.setAudioOutputLevel(validatedVolume, participant?.sessionId);
+    },
+    [call, participant],
+  );
+
+  return (
+    <div
+      className={clsx('str-video__audio-level-slider', {
+        'str-video__audio-level-slider--mute': !audioLevel,
+      })}
+    >
+      <span
+        onClick={() =>
+          call?.setAudioOutputLevel(
+            !audioLevel ? masterAudioOutputLevel : 0,
+            participant?.sessionId,
+          )
+        }
+      >
+        <Icon icon={audioLevel ? 'speaker' : 'speaker-off'} />
+      </span>
+      <div
+        className="str-video__audio-level-slider__track"
+        onClick={handleClick}
+      >
+        <div
+          className="str-video__audio-level-slider__level"
+          style={{ transform: `scaleX(${audioLevel})` }}
+        />
+      </div>
+    </div>
+  );
+};

packages/react-sdk/src/components/CallControls/ToggleAudioOutputButton.tsx

@@ -1,6 +1,11 @@
 import { CompositeButton, IconButton } from '../Button';
 import { DeviceSelectorAudioOutput } from '../DeviceSettings';
-import { useI18n } from '@stream-io/video-react-bindings';
+import {
+  useCall,
+  useMasterAudioOutputLevel,
+  useI18n,
+  useLocalParticipant,
+} from '@stream-io/video-react-bindings';
 import { ComponentType } from 'react';
 
 export type ToggleAudioOutputButtonProps = {
@@ -11,12 +16,20 @@ export type ToggleAudioOutputButtonProps = {
 export const ToggleAudioOutputButton = (
   props: ToggleAudioOutputButtonProps,
 ) => {
+  const call = useCall();
+  const masterAudioOutputLevel = useMasterAudioOutputLevel();
+  const localParticipant = useLocalParticipant();
   const { t } = useI18n();
   const { caption = t('Speakers'), Menu = DeviceSelectorAudioOutput } = props;
+  const enabled =
+    (localParticipant?.audioOutputLevel ?? masterAudioOutputLevel) > 0;
 
   return (
-    <CompositeButton Menu={Menu} active caption={caption}>
-      <IconButton icon="speaker" />
+    <CompositeButton Menu={Menu} active={!enabled} caption={caption}>
+      <IconButton
+        icon={enabled ? 'speaker' : 'speaker-off'}
+        onClick={() => call?.setAudioOutputLevel(enabled ? 0 : 1)}
+      />
     </CompositeButton>
   );
 };

packages/react-sdk/src/components/CallControls/index.ts

@@ -1,3 +1,4 @@
+export * from './AudioOutputLevelSlider';
 export * from './AcceptCallButton';
 export * from './CallControls';
 export * from './CallStatsButton';

packages/react-sdk/src/components/CallParticipantsList/CallParticipantListingItem.tsx

@@ -16,6 +16,7 @@ import {
   SfuModels,
   StreamVideoParticipant,
 } from '@stream-io/video-client';
+import { AudioOutputLevelSlider } from '../CallControls';
 import { IconButton } from '../Button';
 import {
   GenericMenu,
@@ -25,6 +26,7 @@ import {
 } from '../Menu';
 import { WithTooltip } from '../Tooltip';
 import { Icon } from '../Icon';
+import { useMediaDevices } from '../../core';
 
 type CallParticipantListingItemProps = {
   /** Participant object be rendered */
@@ -139,6 +141,7 @@ export const ParticipantActionsContextMenu = ({
     document.pictureInPictureElement,
   );
   const activeCall = useCall();
+  const { isAudioOutputChangeSupported } = useMediaDevices();
 
   const blockUser = () => {
     activeCall?.blockUser(participant.userId);
@@ -235,7 +238,7 @@ export const ParticipantActionsContextMenu = ({
   };
 
   return (
-    <GenericMenu>
+    <GenericMenu className="str-video__participant-actions-context-menu">
       <GenericMenuButtonItem onClick={toggleParticipantPinnedAt}>
         <Icon icon="pin" />
         {participant.pinnedAt ? 'Unpin' : 'Pin'}
@@ -276,7 +279,7 @@ export const ParticipantActionsContextMenu = ({
           }
           onClick={muteAudio}
         >
-          <Icon icon="no-audio" />
+          <Icon icon="mic-off" />
           Mute audio
         </GenericMenuButtonItem>
       </Restricted>
@@ -324,6 +327,9 @@ export const ParticipantActionsContextMenu = ({
           Disable screen sharing
         </GenericMenuButtonItem>
       </Restricted>
+      {isAudioOutputChangeSupported && (
+        <AudioOutputLevelSlider participant={participant} />
+      )}
     </GenericMenu>
   );
 };

packages/react-sdk/src/components/Menu/GenericMenu.tsx

@@ -1,7 +1,17 @@
 import { ComponentProps, PropsWithChildren } from 'react';
+import clsx from 'clsx';
 
-export const GenericMenu = ({ children }: PropsWithChildren) => {
-  return <ul className="str-video__generic-menu">{children}</ul>;
+export type GenericMenuProps = {
+  className?: string;
+};
+
+export const GenericMenu = ({
+  className,
+  children,
+}: PropsWithChildren<GenericMenuProps>) => {
+  return (
+    <ul className={clsx('str-video__generic-menu', className)}>{children}</ul>
+  );
 };
 
 export const GenericMenuButtonItem = ({

packages/react-sdk/src/core/components/Audio/Audio.tsx

@@ -12,10 +12,14 @@ export type AudioProps = DetailedHTMLProps<
 > &
   Pick<StreamVideoParticipant, 'audioStream'> & {
     sinkId?: string;
+    /**
+     * Value applied to underlying audio element to control the audio output level.
+     */
+    volume?: number;
   };
 
 // TODO: rename to BaseAudio
-export const Audio = ({ audioStream, sinkId, ...rest }: AudioProps) => {
+export const Audio = ({ audioStream, sinkId, volume, ...rest }: AudioProps) => {
   const audioRef = useRef<HTMLAudioElement>(null);
   useEffect(() => {
     const $el = audioRef.current;
@@ -31,10 +35,16 @@ export const Audio = ({ audioStream, sinkId, ...rest }: AudioProps) => {
     const $el = audioRef.current;
     if (!$el || !sinkId) return;
 
+    // HTMLMediaElement neither HTMLAudioElement in Typescript have prop setSinkId
     if (($el as any).setSinkId) {
       ($el as any).setSinkId(sinkId);
     }
   }, [sinkId]);
 
+  useEffect(() => {
+    if (typeof volume !== 'number' || !audioRef.current) return;
+    audioRef.current.volume = volume;
+  }, [audioRef, volume]);
+
   return <audio autoPlay ref={audioRef} {...rest} />;
 };

packages/react-sdk/src/core/components/CallLayout/PaginatedGridLayout.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import {
   useCall,
+  useMasterAudioOutputLevel,
   useLocalParticipant,
   useParticipants,
   useRemoteParticipants,
@@ -89,6 +90,7 @@ export const PaginatedGridLayout = ({
   // used to render audio elements
   const remoteParticipants = useRemoteParticipants();
   const localParticipant = useLocalParticipant();
+  const masterAudioOutputLevel = useMasterAudioOutputLevel();
 
   // only used to render video elements
   const participantGroups = useMemo(
@@ -121,6 +123,7 @@ export const PaginatedGridLayout = ({
           sinkId={localParticipant?.audioOutputDeviceId}
           key={participant.sessionId}
           audioStream={participant.audioStream}
+          volume={participant?.audioOutputLevel ?? masterAudioOutputLevel}
         />
       ))}
       <div className="str-video__paginated-grid-layout__wrapper">

packages/react-sdk/src/core/components/ParticipantView/ParticipantView.tsx

@@ -13,13 +13,16 @@ import {
   StreamVideoLocalParticipant,
   StreamVideoParticipant,
 } from '@stream-io/video-client';
+import {
+  useMasterAudioOutputLevel,
+  useLocalParticipant,
+} from '@stream-io/video-react-bindings';
 
 import { Audio } from '../Audio';
 import { Video, VideoProps } from '../Video';
 import { useTrackElementVisibility } from '../../hooks';
 import { DefaultParticipantViewUI } from './DefaultParticipantViewUI';
 import { applyElementToRef, isComponentType } from '../../../utilities';
-import { useLocalParticipant } from '@stream-io/video-react-bindings';
 
 export type ParticipantViewContextValue = Required<
   Pick<ParticipantViewProps, 'participant' | 'videoMode'>
@@ -94,6 +97,7 @@ export const ParticipantView = forwardRef<HTMLDivElement, ParticipantViewProps>(
       sessionId,
     } = participant;
     const localParticipant = useLocalParticipant();
+    const masterAudioOutputLevel = useMasterAudioOutputLevel();
 
     const hasAudio = publishedTracks.includes(SfuModels.TrackType.AUDIO);
     const hasVideo = publishedTracks.includes(SfuModels.TrackType.VIDEO);
@@ -165,6 +169,7 @@ export const ParticipantView = forwardRef<HTMLDivElement, ParticipantViewProps>(
             muted={isLocalParticipant || muteAudio}
             sinkId={localParticipant?.audioOutputDeviceId}
             audioStream={audioStream}
+            volume={participant?.audioOutputLevel ?? masterAudioOutputLevel}
           />
           <Video
             VideoPlaceholder={VideoPlaceholder}

packages/styling/index.scss

@@ -4,6 +4,7 @@
 @use 'src/global-theme-variables';
 @use 'src/utils';
 
+@import 'src/AudioLevelSlider';
 @import 'src/Avatar';
 @import 'src/Button';
 @import 'src/CallControls';