VERC: Voice API in SDK 2.2 Last edited 5 years ago2019-04-17 10:25:47 UTC

HL SDK 2.2

This article was originally made available as part of version 2.2 of the Half-Life SDK. As such, all limitations, restrictions, license agreements, copyrights and trademarks from the original document apply here.

Voice API

In this version of the Half-Life engine and SDK, we have added the ability for players to speak to each other while playing on a server. MOD authors have full control over which players are allowed to speak to each other.

There are two new functions in enginefuncs_s you can use to find out which players are allowed to talk to each other and to change who can talk to each other.

qboolean (*pfnVoice_GetClientListening)(int iReceiver, int iSender);

Use pfnVoice_GetClientListening to ask the engine if a certain player is currently allowed to hear another player's speech.

qboolean (*pfnVoice_SetClientListening)(int iReceiver, int iSender, qboolean bListen);

Use pfnVoice_SetClientListening to tell the engine if a certain player is allowed to hear another player's speech.

These two functions are all that the engine exposes to the MOD to control voice. Most of the code involved in adding voice to a MOD is in the form of HUD elements and such. A good way to add voice to your mod and have its functionality appear familiar to players is to use the code we have for Half-Life Deathmatch in the SDK. We describe the UI code below.

On the client, there is a new function a MOD can implement that takes this form:

void DLLEXPORT HUD_VoiceStatus(int entindex, qboolean bTalking)

The engine calls this when it detects that players in the game have started or stopped talking. Entity indices are usually passed into this function, but there are two special entity indices that are passed in.

• If -1 is passed as the entity index, it means the local player has pressed their voice key and the engine is now recording their voice and sending it to the server.
• If -2 is passed as the entity index, it means that the server has received the local client's speech. This is used by CVoiceStatus to display an icon to the user confirming that their voice data got to the server.

SDK MOD Code

This section describes the SDK code that is available to MOD authors to use as a starting point for adding voice to their MOD.

In the MOD game DLL, we have a manager class called CVoiceGameMgr in the game_shared/voice_gamemgr.h file which:

• Receives info from clients describing whose voice they want to hear.
• Asks the MOD which players are allowed to speak to each other (for example, players on opposite teams usually can't speak to each other).

To use CVoiceGameMgr, derive a class from IVoiceGameMgrHelper and implement the CanPlayerHearPlayer function so CVoiceGameMgr can ask your MOD which players are allowed to hear each other. Then call its Update, ClientConnected, and ClientCommand functions from your CGameRules class in the corresponding callbacks (Update corresponds to Think).

Most of the game code that we have added to the SDK deals with presentation of UI elements for players to control who they want to hear. The core of this code is in the CVoiceStatus class in the game_shared/voice_status.h file. CVoiceStatus manages a list of who is currently speaking in the game and displays icons for the speakers on the screen. It also manages, saves, and loads a list of which players the local player has banned from hearing. This allows people to completely turn off players that abuse the voice functionality.

Use GetClientVoiceMgr() to get a pointer to a global instance of this class. Then call its member functions from the appropriate places in the rest of your client DLL code. You can find all the places CVoiceStatus is called from other code by doing a Find In Files through the client DLL files and searching for " GetClientVoiceMgr ".

CVoiceStatus makes use of several resources for the HUD display if they exist:

• Sprites/voiceicon.spr - This icon is placed over a player's head when they are speaking.
• Scripts/voicemodel.txt - This file just contains a number telling how high voiceicon.spr should be above a player's head.
• gfx/vgui/icntlk_pl.tga - This icon is shown in the lower-right corner of the screen when a player has started speaking and sending data to the server.
• gfx/vgui/icntlk_sv.tga - This icon is shown in the lower-right corner of the screen when the server confirms that it is receiving the local player's voice data.

Console Variables and Commands of Interest

Server Console Variables/Commands

• sv_voicecodec - The game DLL or the server admin can set this cvar to "", in which case none of the clients will be able to speak to each other or send voice data to the server.
• voice_serverdebug - Setting this to 1 causes CVoiceGameMgr to print out debug information.

Client Console Variables/Commands

• voice_clientdebug - Setting this to 1 causes CVoiceStatus to print out debug information that can help track down bugs.
• voice_loopback - Setting this to 1 tells the server to send the local player's voice data back so they can hear themselves speak and hear what they sound like to other players.
• voice_recordtofile and voice_inputfromfile help if you're testing voice locally and you don't want to have to say "testing testing 1, 2, 3" into the microphone repeatedly. To use this functionality, follow these steps:
  1. Set voice_recordtofile to 1.
  2. Press your voice record button and say something like "testing 1, 2, 3" into the microphone.
  3. Set voice_recordtofile back to 0.
  4. You should now have a new file called voice_micdata.wav sitting in your executables directory. Rename this to voice_input.wav.
  5. From now on, if you set voice_inputfromfile to 1, it will send the sound data in voice_input.wav to the server rather than recording what you're saying into the microphone. Voice_inputfromfile and voice_loopback are usually used hand-in-hand.