Volume control and mute

To use Voice SDK for audio communication, you implement a simple workflow in your game. The game joins a new or an existing channel using an app ID and an authentication token. If a channel of the given name exists within the context of the app ID, the game joins the channel. If the named channel does not exist, a new channel is created that other users may join. Once the game joins a channel, it subscribes to one or more of the audio streams published in the channel. The game also publishes its own audio stream that other users in the channel subscribe to. Each user publishes streams that share their microphone or audio data.

The basics of joining and leaving a channel are presented in the SDK quickstart for Voice Calling. This document explains the common workflows you need to handle in your app.

The following figure shows the typical workflow you integrate into your game in order to publish and subscribe to audio streams.

This page shows you how to add the following features to your game:

• Volume control

  Users in a channel often need to adjust the volume for local and remote audio. For example, they may want to increase the input volume from remote users and decrease the local audio recording volume. You use Voice SDK to enable game users to adjust recording and playback volumes. Voice SDK also provides methods to mute local audio, audio from a particular remote user, or audio from all remote users. Voice SDK provides several methods to manage local and remote audio volumes. These methods enable the user to control:

  • Recording signal volume: The volume of the signal recorded by the local user.
  • Playback signal volume: The playback audio level, after audio mixing, for all remote users, or for a specific remote user.
  • In-ear monitoring volume: The volume of their own voice, users hear through wired earphones.
  • Audio mixing volume: The mixing volume for local playback and for sending to other users.
  • Muting audio streams: Stop or resume playing a specified remote or local audio.

To follow this procedure you must have implemented the SDK quickstart project for Voice Calling.

To create the environment necessary to implement screen sharing and volume control features into your game, open the SDK quickstart Voice Calling project you created previously.

This section shows how to use Voice SDK to implement volume control in your game, step-by-step.

In a real-world application, for each volume setting you want the user to control, you typically add a volume control UI element such as a Slider to the audio configuration panel. To enable the user to mute local or remote audio, you add a Toggle to the interface for each user. In this example, you add a Toggle and a Slider to the UI to test different volume settings.

1. Right-click Sample Scene, then click Game Object > UI > Slider. A Slider appears in the Scene Canvas.

2. In Inspector, rename Slider to mediaProgressBar, and then change the following coordinates:

   • Pos X - 0
   • Pos Y - 142

3. Right-click Canvas, then click UI > Toggle. A toggle button appears in the scene canvas.

4. In Inspector, rename Toggle to Mute, then change Pos Y to 30.

1. Add the required library

   To import the required Unity UI library, in your script file, add the following to the namespace declarations:

   using TMPro;
   

To implement these features in your game, take the following steps:

1. Declare the variables you need

   To read, store and apply workflow settings, in your script file, add the following declaration to NewBehaviourScript:

   // Volume Control
   

   private Slider volumeSlider;
   

   // Remote user uid.
   

   private long remoteUid;
   

2. Access the UI elements

   To access the slider and teh toggle button, in your script file, add the following at the end of SetupUI method to NewBehaviourScript:

   // Access the slider from the UI
   

   go = GameObject.Find("mediaProgressBar");
   

   volumeSlider = go.GetComponent<Slider>();
   

   // Specify a maximum value for slider.
   

   go.GetComponent<Slider>().maxValue = 100;
   

   // Add a listener to the slider and invokes changeVolume when the value changes.
   

   go.GetComponent<Slider>().onValueChanged.AddListener(delegate {changeVolume ((int)volumeSlider.value);});
   

   // Access the Mute toggle from the UI.
   

   go = GameObject.Find("Mute");
   

   Toggle muteToggle = go.GetComponent<Toggle>();
   

   muteToggle.isOn = false;
   

   // Invoke muteRemoteAudio when te user taps the toggle button.
   

   muteToggle.onValueChanged.AddListener((value) =>
   

   {
   

   muteRemoteAudio(value);
   

   });
   

3. Adjust the recorded audio volume

   When you drag the slider left or right, your game calls the changeVolume method. The method reads the slider value and calls AdjustRecordingSignalVolume to adjust the recording signal volume. To implement this logic, in your script file, add the following method to NewBehaviourScript:

   private void changeVolume(int volume)
   

   {
   

   // Adjust the recorded signal volume.
   

   RtcEngine.AdjustRecordingSignalVolume(volume);
   

   }
   

   When using a device to capture audio, Voice SDK sets a default global volume value of 85 (range [0, 255]). Voice SDK automatically increases a capture device volume that's too low. You can adjust the capture volume as per your needs by adjusting the microphone or sound card's signal capture volume.

4. Get the uid of the remote user

   When a remote user joins the channel, Voice SDK triggers OnUserJoined. You use this callback to save the uid of remote user. To implement this callback, in your script file, add the following callback to UserEventHandler:

   public override void OnUserJoined(RtcConnection connection, uint uid, int elapsed)
   

   {
   

   // Save the remote user ID in a variable.
   

   _audioSample.remoteUid = uid;
   

   }
   

5. Implement the logic to mute and unmute the remote user

   When the user taps the mute toggle button, your game calls muteRemoteAudioStream and mutes the remote user. To implement this workflow, in your script file, add the following to NewBehaviourScript:

   private void muteRemoteAudio(bool value)
   

   {
   

   // Pass the uid of the remote user you want to mute.
   

   RtcEngine.MuteRemoteAudioStream(System.Convert.ToUInt32(remoteUid), value);
   

   }
   

To ensure that you have implemented Voice Calling in your game:

1. Generate a temporary token in Agora Console .

2. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

3. In your script file, update _appID, _channelName and _token with the values for your temporary token.

4. In Unity Editor, click Play. A moment later you see the game running on your development device.

5. Press Join to connect to the same channel as your web demo.

6. Test volume control

   a. Speak into your Android device as you move the slider to the left and then right. You notice the volume decrease and then increase in the web demo app as the recording volume changes.

   b. Tap the Mute Toggle while you speak into the microphone connected to the web demo app. You notice that the remote audio is muted on your Android device.

   c. To test other volume control methods, in changeVolume replace the AdjustRecordingSignalVolume call with one of the following:

   RtcEngine.AdjustPlaybackSignalVolume(volume);
   

   RtcEngine.AdjustUserPlaybackSignalVolume(remoteUid,volume);
   

   RtcEngine.AdjustAudioMixingVolume(volume);
   

   RtcEngine.AdjustAudioMixingPlayoutVolume(volume);
   

   RtcEngine.AdjustAudioMixingPublishVolume(volume);
   

   RtcEngine.SetInEarMonitoringVolume(volume);
   

   Run the app again and use the volume slider to test the change in the corresponding volume setting.

   d. To test other mute methods, in muteRemoteAudio replace the MuteRemoteAudioStream call with one of the following:

   RtcEngine.MuteAllRemoteAudioStreams(value);
   

   RtcEngine.muteLocalAudioStream(value);
   

   Run the app again and tap the CheckBox to test the effect of these mute methods.

3. In Visual Studio, in AgoraImplementation.h, update appId, channelName and token with the values for your temporary token.

4. In Visual Studio, click Local Windows Debugger. A moment later, you see the app running on your development device.

   If this is the first time you run your app, grant camera and microphone permissions.

5. Press Join to connect to the same channel as your web demo.

6. Test volume control

   1. Speak into your development device as you move the slider on the slider to the left and then right. You notice the volume decrease and then increase in the web demo app as the recording volume changes.

   2. Tap Mute while you speak into the microphone connected to the web demo app. You notice that the remote audio is muted on your development device.

   3. To test other volume control methods, in AgoraImplementationDlg.cpp, replace the adjustRecordingSignalVolume call in OnNMCustomdrawSlider2 with one of the following:

      agoraEngine->adjustPlaybackSignalVolume(value);
      

      agoraEngine->adjustUserPlaybackSignalVolume(remoteUId,value);
      

      agoraEngine->adjustAudioMixingVolume(value);
      

      agoraEngine->adjustAudioMixingPlayoutVolume(value);
      

      agoraEngine->adjustAudioMixingPublishVolume(value);
      

      agoraEngine->setInEarMonitoringVolume(value);
      

      Run the app again and use the volume slider to test the change in the corresponding volume setting.

   4. To test other mute methods, in AgoraImplementationDlg.cpp, replace the muteRemoteAudioStream call in OnBnClickedCheck1 with one of the following:

      agoraEngine->muteAllRemoteAudioStreams(isChecked);
      

      agoraEngine->muteLocalAudioStream(isChecked);
      

      Run the app again and tap the CheckBox to test the effect of these mute methods.

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

• AdjustRecordingSignalVolume
• AdjustPlaybackSignalVolume
• AdjustUserPlaybackSignalVolume
• AdjustAudioMixingVolume
• AdjustAudioMixingPlayoutVolume
• AdjustAudioMixingPublishVolume
• SetInEarMonitoringVolume