tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Game Multimedia Engine
    Documentation
    Download PDF

    Range Voice

    Last updated: 2023-04-27 17:06:32
    Download PDF

      Overview

      In a voice chat room, a user can talk with other users within a certain distance. This feature calls the GME client API at the business layer to update the sound source position to inform the server of the local player's position. The server forwards the audio streams within the players' ranges after checking the local coordinates and audio reception range against remote coordinates and audio reception range. By default, 20 audio streams nearest a player are forwarded, and up to 10,000 players can mic on simultaneously in a room.
      

      Use Cases

      Battle royale games
      GME provides the "Team only" and "Everyone" voice modes unique to battle royale games and mobile survival shooter games. The voice effect varies by selected mode as follows: 1. If the "Team only" mode is selected, the player can hear only the voice of teammates. 2. If the "Everyone" mode is selected, the player can hear the voice of teammates as well as the voice of enemies within a certain range.
      Immersive virtual scenarios
      In a virtual scenario like in-game concert, when the singer sings in the virtual room, the range voice feature can be used to enable the audience to talk with other players within a certain range while hearing the singer. Up to 10,000 players can turn on their mics simultaneously in a room.
      

      Demo Effects

      You can download the free demo to try out the 3D sound effect and range voice features.
      

      Concepts

      The range voice feature involves three concepts: voice mode, range for hearing the voice, and TeamID.

      Voice mode

      When the user enters a range voice room, the user can choose from two voice modes:
      Voice Mode
      Parameter
      Feature
      Everyone
      RANGE_AUDIO_MODE_WORLD
      In this mode, the player can be heard by other players within a certain range and can talk with them if they are also in this mode.
      Teammates can hear each other.
      Team only
      RANGE_AUDIO_MODE_TEAM
      Only teammates can hear each other.
      Note
      Teammates can talk with each other regardless of the distance and voice mode.

      Range for hearing the voice

      
      If the voice mode is set to Everyone (RANGE_AUDIO_MODE_WORLD), the range for hearing the voice will be subject to the UpdateAudioRecvRange API.
      Suppose players A and B in different teams both set their voice modes to Everyone (RANGE_AUDIO_MODE_WORLD):
      Player Coordinates
      Range for Hearing the Voice
      Voice Reachability of the Other Player
      Voice Reachability of Teammates
      A (0,0,0)
      10 meters
      The player can hear player B, as player B is within 10 meters of the player.
      Teammates can talk with each other.
      B (0,8,0)
      5 meters
      The player cannot hear player A, as player A is more than 5 meters away.
      Teammates can talk with each other.
      Note
      For more information on the specific voice reachability of players, see Range Voice.

      TeamID

      To use the range voice feature, you need to call the SetRangeAudioTeamID API to set the team ID (TeamID) and then call the EnterRoom API to enter the room.
      If TeamID specified during room entry is not 0, a user will enter the range voice chat room mode. If a user sets TeamID to 1 and the voice mode to RANGE_AUDIO_MODE_TEAM when entering a voice chat room, only members whose TeamID is 1 can hear the user. If the user sets the voice mode to RANGE_AUDIO_MODE_WORLD, players within a certain range as well as members whose TeamID is 1 can hear the user.
      TeamID Value
      Voice Mode
      Range
      Voice Reachability
      TeamID is not 0. Suppose TeamID is 1.
      RANGE_AUDIO_MODE_TEAM
      10 meters
      The user can talk with only members whose TeamID is 1.
      RANGE_AUDIO_MODE_WORLD
      10 meters
      The user can talk with members whose TeamID is 1 and members in RANGE_AUDIO_MODE_WORLD voice mode within 10 meters in the same room.
      If a user enters a voice chat room with TeamID set to 0, the user will enter the range voice host mode, where all members in the room (regardless of their voice mode) can hear the user.
      TeamID Value
      TeamID Modification Time
      Range
      Voice Reachability
      TeamID = 0
      TeamID is not 0 before room entry and is changed to 0 after room entry.
      10 meters
      All members in the room (regardless of their voice mode) can hear the user.
      The user can talk with members whose TeamID is 0.
      The user can hear members in RANGE_AUDIO_MODE_WORLD voice mode within 10 meters in the same room.
      TeamID is 0 before and during room entry.
      10 meters
      All members in the room (regardless of their voice mode) can hear the user.
      The user can talk with members whose TeamID is 0.
      The user cannot hear other members in the room.

      Scenarios

      Battle royale game: In a battle royale game, every four players are grouped into a team, and a team ID (TeamID) needs to be set for them. A battle room can contain 100 players, i.e., 25 teams, so all those teams enter the same voice chat room. In a battle, if a player wants to communicate with a stranger within 10 meters, the player can set the range for hearing the voice to 10 meters and the voice mode to RANGE_AUDIO_MODE_WORLD and enable both the mic and speaker. If the player wants to communicate with only teammates, the player can set the voice mode to RANGE_AUDIO_MODE_TEAM.
      Game concert: If a singer wants to hold a concert in a game but doesn't need to interact with players, players can enter the range voice chat room with their TeamID set to OpenID, voice mode set to RANGE_AUDIO_MODE_WORLD, and range for hearing the voice set to an appropriate value so as to talk with players nearby. The singer can set TeamID to 0 before entering the room to be heard by all members in the room without hearing other members.
      Host mode: In a game such as virtual board game, the host needs to be heard by all members in the room and hear players within a certain range. In this case, the host can enter the room with TeamID set to a non-0 value and change TeamID to 0 after room entry, so as to be heard by all members in the room while hearing players within a certain range.

      Prerequisites

      You have activated the voice chat service. For more information, see Activating Services.
      You have integrated the GME SDK, including core APIs and voice chat APIs. For more information, see Quick Integration of Native SDK, Quick Integration of SDK for Unity, and Quick Integration of SDK for Unreal Engine.
      You have applied for a voice chat room for over 10,000 users: If more than 1,000 users in a room use range voice, submit a ticket for application.

      Directions

      
      Notes
      Be sure to follow the flowchart to call the API.
      The blue part of the flowchart shows the process of the range voice.
      A range voice chat room is different from a team voice chat room in that you must select the smooth sound quality when entering the range voice chat room.
      Once you enter the room, call UpdateAudioRecvRange (once at least) and call UpdateSelfPosition once per frame.

      1. Set TeamID

      Calling this API to set the team ID before room entry will affect the next room entry.
      This API can be called to modify the team ID after room entry. The modification will take effect immediately.
      TeamID will not be automatically reset to 0 upon room exit. Therefore, once you decide to call this voice mode, do so to set the TeamID before each call of EnterRoom.
      When entering a room after exiting the room, call the API for setting the team ID again after the callback for successful room exit is returned.

      Function prototype

      ITMGContext SetRangeAudioTeamID(int teamID)
      Parameter
      Type
      Description
      teamID
      int
      Team ID, which is used in range voice mode only. When it is set to 0 (default), the team voice mode is used.

      2. Set the voice mode

      Calling this API to change the voice mode before room entry will affect the next room entry.
      Calling this API to change the voice mode after room entry will directly change the current voice mode.
      This parameter will not be automatically reset to MODE_WORLD upon room exit. Therefore, once you decide to call this method, do so before each call of EnterRoom.

      Function prototype

      ITMGRoom int SetRangeAudioMode(RANGE_AUDIO_MODE rangeAudioMode)
      Parameter
      Type
      Description
      rangeAudioMode
      int
      0 (MODE_WORLD): everyone; 1 (MODE_TEAM): team only.

      3. Enter a voice chat room

      Before entering a voice chat room by calling EnterRoom, you need to call the following two APIs: SetRangeAudioTeamID and SetRangeAudioMode.

      Function prototype

      ITMGContext.GetInstance(this).EnterRoom(roomId,ITMG_ROOM_TYPE_FLUENCY, authBuffer);
      Choose smooth sound quality when entering the voice chat room, and monitor and process the callback for room entry.
      public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
          if (ITMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_ENTER_ROOM == type)
              {
                     // Analyze the returned data
                  int nErrCode = data.getIntExtra("result" , -1);
                  String strErrMsg = data.getStringExtra("error_info");
      
                  if (nErrCode == AVError.AV_OK)
                  {
                      //If you receive a success response for room entry, you can proceed with your operation
                      ScrollView_ShowLog("EnterRoom success");
                      Log.i(TAG,"EnterRoom success!");
                  }
                  else
                  {
                      //If you fail to enter the room, you need to analyze the returned error message
                      ScrollView_ShowLog("EnterRoom fail :" + strErrMsg);
                      Log.i(TAG,"EnterRoom fail!");
                  }  
              }
          }
      Once you enter the room, call UpdateAudioRecvRange (once at least), and call UpdateSelfPosition once per frame.

      4. Set the voice reception range

      This method is used to set the voice reception range (subject to the game engine) and can be called only after successful room entry.
      This method must be used together with UpdateSelfPosition to update the sound source position.
      This method needs to be called only once to take effect, and the parameter value can be modified.

      Function prototype

      ITMGRoom int UpdateAudioRecvRange(int range)
      Parameter
      Type
      Description
      range
      int
      Maximum voice reception range in the distance unit used by the game engine.

      Sample code

      ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);

      5. Update the sound source position

      The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.
      This API is used to update the sound source position information. It can be called only after successful room entry and needs to be called once per frame. Taking the Unity engine as an example, this API needs to be called in Update.
      If range voice is enabled, the sound source position must be updated. Even if range determination is not required, this API still needs to be called once after room entry.
      If you want to enable 3D sound effect at the same time, set the axisForward, axisRight, and axisUp parameters as specified in "4. Update the sound source position (for the 3D sound effect)" in Range Voice.

      Function prototype

      public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
      Parameter
      Type
      Description
      position
      int[]
      Your own position (forward, right, and up) in the world coordinate system
      axisForward
      float[]
      This parameter can be ignored in this product.
      axisRight
      float[]
      This parameter can be ignored in this product.
      axisUp
      float[]
      This parameter can be ignored in this product.

      Range voice combined with 3D sound effects

      The range voice feature controls the reachability of sound through distance. It is recommended to use with 3D sound effects if you want a more immersive experience.

      Directions

      If you want to use 3D sound effects while using range voice, please complete the step 1, 2, 3 and then initialize 3D engine and open 3D sound effects.
      
      
      Note
      The blue part of the flowchart shows the process of the 3D sound effect feature.

      Prerequisites

      Perform steps 1, 2, and 3 as instructed in Directions.

      4. Initialize the 3D sound effect engine

      This function is used to initialize the 3D sound effect engine and needs to be called after room entry. You must call this API before using the 3D sound effect, even if you want to enable only the 3D sound effect reception rather than the 3D sound effect playback.

      Function prototype

      public abstract int InitSpatializer(string modelPath)
      Parameter
      Type
      Description
      modelPath
      string
      Enter null.

      5. Enable/disable the 3D sound effect

      This function is used to enable or disable the 3D sound effect. You can hear the 3D sound after enabling it.

      Function prototype

      public abstract int EnableSpatializer(bool enable, bool applyToTeam)
      Parameter
      Type
      Description
      enable
      bool
      You can hear the 3D sound effect after enabling it.
      applyToTeam
      bool
      This parameter specifies whether 3D sound effect is enabled within the team and takes effect only when enable is true.
      The IsEnableSpatializer API can be used to get the 3D sound effect status.

      6. Set the voice reception range (for the 3D sound effect)

      This method is used to set the voice reception range (subject to the game engine) and can be called only after successful room entry.
      This method must be used together with UpdateSelfPosition to update the sound source position.
      This method needs to be called only once to take effect.
      In the 3D sound effect, the sound will begin to attenuate to almost zero as the distance to the sound source exceeds a specified threshold (range/10).
      For more information on the relationship between the distance and sound attenuation, see the appendix.

      Function prototype

      ITMGRoom int UpdateAudioRecvRange(int range)
      Parameter
      Type
      Description
      range
      int
      Maximum voice reception range in the distance unit used by the game engine.

      Sample code

      ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);

      7. Update the sound source position (for the 3D sound effect)

      The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.
      
      This API is used to update the sound source position information. It can be called only after successful room entry and needs to be called once per frame. Taking the Unity engine as an example, this API needs to be called in Update.
      Directly copy and call the sample code to use this feature.

      Function prototype

      public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
      Parameter
      Type
      Description
      position
      int[]
      Local position (forward, right, and up) in the world coordinate system
      axisForward
      float[]
      Forward vector in the local coordinate system
      axisRight
      float[]
      Right vector in the local coordinate system
      axisUp
      float[]
      Up vector in the local coordinate system

      Sample code

      Unreal
      FVector cameraLocation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraLocation();
      FRotator cameraRotation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraRotation();
      int position[] = { 
          (int)cameraLocation.X,
          (int)cameraLocation.Y,
          (int)cameraLocation.Z };
      FMatrix matrix = ((FRotationMatrix)cameraRotation);
      float forward[] = { 
          matrix.GetColumn(0).X,
          matrix.GetColumn(1).X,
          matrix.GetColumn(2).X };
      float right[] = { 
          matrix.GetColumn(0).Y,
          matrix.GetColumn(1).Y,
          matrix.GetColumn(2).Y };
      float up[] = { 
          matrix.GetColumn(0).Z,
          matrix.GetColumn(1).Z,
          matrix.GetColumn(2).Z};
      ITMGContextGetInstance()->GetRoom()->UpdateSelfPosition(position, forward, right, up);
      Unity
      Transform selftrans = currentPlayer.gameObject.transform;
      Matrix4x4 matrix = Matrix4x4.TRS(Vector3.zero, selftrans.rotation, Vector3.one);
      int[] position = new int[3] { 
          selftrans.position.z,
          selftrans.position.x,
          selftrans.position.y};
      float[] axisForward = new float[3] { 
          matrix.m22,
          matrix.m02,
          matrix.m12 };
      float[] axisRight = new float[3] { 
          matrix.m20,
          matrix.m00,
          matrix.m10 };
      float[] axisUp = new float[3] { 
          matrix.m21,
          matrix.m01,
          matrix.m11 };
      ITMGContext.GetInstance().GetRoom().UpdateSelfPosition(position, axisForward, axisRight, axisUp);

      Disabling the 3D sound effect for the host

      If a player in the scenario uses the range voice host mode, the player's voice needs to be heard by all players in the room. In this case, you need to add the host to the 3D sound effect blocklist of all the other players as instructed in 3D Sound Effect to prevent the host's voice from being attenuated by the 3D sound effect feature.
      Below are the API call sequences of different roles:
      API Call Sequence of the Host
      API Call Sequence of a Listener
      
      

      Appendix

      Voice modes

      Player voice reachability in different voice modes is as follows:
      The table below lists the possible cases of voice reachability for player B in different voice modes if player A selects the "Everyone" mode:
      In the Same Team
      Within the Range
      Voice Mode
      Can A and B Hear Each Other
      Same team
      Yes
      MODE_WORLD
      Yes
      MODE_TEAM
      Yes
      No
      MODE_WORLD
      Yes
      MODE_TEAM
      Yes
      Different team
      Yes
      MODE_WORLD
      Yes
      MODE_TEAM
      No
      No
      MODE_WORLD
      No
      MODE_TEAM
      No
      The table below lists the possible cases of voice reachability for player B in different voice modes if player A selects the "Team only" mode:
      In the Same Team
      Within the Range
      Voice Mode
      Can A and B Hear Each Other
      Same team
      Yes
      MODE_WORLD
      Yes
      MODE_TEAM
      Yes
      No
      MODE_WORLD
      Yes
      MODE_TEAM
      Yes
      Different team
      Yes
      MODE_WORLD
      No
      MODE_TEAM
      No
      No
      MODE_WORLD
      No
      MODE_TEAM
      No

      The relationship between distance and sound attenuation

      In the 3D sound effect, the sound will begin to attenuate to almost zero as the distance to the sound source exceeds a specified threshold (range/10).
      Distance (Unit in the Engine)
      Attenuation Coefficient
      0 < N < range/10
      1.0 (no attenuation)
      N ≥ range/10
      Range/10/N
      
      
      
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy