CSoundEngine

The sound system allows you to play sounds, sentences and sentence groups, complete with sound replacement.

HTML documentation can be found here.

Implemented in the CSoundEngine class.

A single global instance exists: CSoundEngine g_SoundSystem;

1 Constants

All these constants exist in global scope.

1.1 SOUND_CHANNEL

Sound channels represent a number of audio channels that can simultaneously play sounds for any given entity. Note that despite what the name of some channels might imply, none of them are intended for any particular type of sound, with the exception of CHAN_STATIC due to its special behavior in networking code.

Channel	Description
CHAN_AUTO	Automatically selects a channel for use. You cannot stop sounds while using this channel with StopSound, or in conjunction with the SND_STOP flag.
CHAN_WEAPON	Sound channel recommended for weapons.
CHAN_VOICE	Sound channel recommended for voice (speaking).
CHAN_ITEM	Sound channel recommended for items (pickup sounds, etc).
CHAN_BODY	Sound channel recommended for body events (footsteps, clothes, etc).
CHAN_STREAM	General purpose channel.
CHAN_STATIC	Channel used for sounds that loop, or sounds that play for a long time (e.g. music). Is always sent to players, even if they are not within the Potentially Audible Set (i.e. outside of the audible range).
CHAN_NETWORKVOICE_BASE	Reserved for player voice data. Do not use.
CHAN_NETWORKVOICE_END	Reserved for player voice data. Do not use.

1.2 Sound flags

Constant	Description
SND_VOLUME	If set, a volume other than 1 is used. Do not use directly, automatically set.
SND_PITCH	If set, a pitch other than 100 is used. Do not use directly, automatically set.
SND_ATTENUATION	If set, an attenuation other than ATTN_NORM is used. Do not use directly, automatically set.
SND_ORIGIN	If set, an origin is sent instead of using the entity origin. Do not use directly, automatically set.
SND_ENT	If set, the sound is being played for an entity and its origin should be used. Do not use directly, automatically set.
SND_STOP	Tells the client to stop playing a sound.
SND_CHANGE_VOL	If set, instead of restarting the sound, just changes its volume.
SND_CHANGE_PITCH	If set, instead of restarting the sound, just changes its pitch.
SND_SENTENCE	If set, this is a sentence. Do not use directly, automatically set.
SND_REFRESH	If set, the sound is refreshed so clients that previously did not receive the sound due to not being in the Potentially Audible Set (for all channels except CHAN_STATIC) or not on the server when the sound started (all channels) will still hear it.
SND_FORCE_SINGLE	If set, the sound will not loop even if it normally would, e.g. if it has a cue point.
SND_FORCE_LOOP	If set, the sound will loop even if it normally wouldn’t, e.g. if it does not have a cue point.
SND_LINEAR	If set, the given attenuation has linear falloff. See Attenuation.
SND_SKIP_ORIGIN_USE_ENT	Don’t send the sound’s origin, instead, rely on entity index to re-create origin on client dll.

1.3 Attenuation

Attenuation affects sound falloff.

Falloff normally occurs between 64 and ( 4 / attenuation ) * 256. The flag SND_LINEAR can override this to provide a custom falloff range. When SND_LINEAR is used, the attenuation value is defined as follows: The lower 4 bits are minimum falloff, the higher 4 bits are maximum falloff. Minimum is multiplied by 256, maximum is multiplied by 256 and added to 32.

Constant	Description
const float ATTN_NONE	No attenuation is applied. Falloff is defined as minimum and maximum 10000. Equivalent to ambient_generic “play everywhere” flag.
const float ATTN_NORM	Normal attenuation. Equivalent to ambient_generic “large radius” flag.
const float ATTN_IDLE	Idle attenuation. Equivalent to ambient_generic “small radius” flag.
const float ATTN_STATIC	Static attenuation. Equivalent to ambient_generic “medium radius” flag.

1.4 Pitch

Pitch affects playback speed and can be used to simulate different voice depths.

Values are possible in the range [0, 255], where 255 is very high.

Constant	Value	Description
PITCH_NORM	100	Non-pitch shifted.
PITCH_LOW	95	Low pitch. Can be used for deep voices.
PITCH_HIGH	120	High pitch. Can be used for high voices (helium, children, etc).

1.5 Other

Constant	Description
const float VOL_NORM	Normal volume level.

2 Methods

2.1 PrecacheSound

void PrecacheSound(const string& in szFilename)

This method allows you to precache a sound for use. Sounds must be precached in MapInit or an entity’s Precache method.

The file path starts in sound/.

Argument	Purpose
szFilename	Name of the file to precache.

2.2 FindSoundReplacementSample

string FindSoundReplacementSample(CBaseEntity@ pEntity, const string& in szSample) const

Finds the sound replacement sample for the given entity and sample. If the sample is replaced, it will return the sample that is used instead. Otherwise, szSample is returned.

Both the entity’s sound replacement file as well as the global file will be checked.

Argument	Purpose
pEntity	Entity whose sound replacement file will be checked. Must be valid.
szSample	Sample to look up.

2.3 PlaySound

void PlaySound(edict_t@ entity, SOUND_CHANNEL channel, const string& in sample, float volume, float attenuation, int flags = 0, int pitch = PITCH_NORM, int target_ent_unreliable = 0, bool setOrigin = false, const Vector& in vecOrigin = g_vecZero)

Plays a sound. The sound is not considered for sound replacement.

Argument	Purpose
entity	Entity that the sound will be attached to. Sounds are played at the entity’s origin.
channel	Sound channel to use. An entity can have a sound playing on every channel it has at the same time. See SOUND_CHANNEL.
sample	Name of the sound to play.
volume	Volume to play the sound at. This value has a range of [0, 1], where 0 is muted, and 1 is maximum volume.
attenuation	Attenuation. Values lie in the range [0, 4]. Higher values decrease the falloff range. See Attenuation.
flags	Bit vector containing a number of flags. See Sound flags.
pitch	Pitch to use. See Pitch.
target_ent_unreliable	If not zero, this is the entity index of a player to send this sound to unreliably. Useful for non-critical sounds.
setOrigin	If true, use the given origin to play the sound, instead of the entity origin.
vecOrigin	If setOrigin is true, this is the origin in the world to play the sound at.

2.4 StopSound

void StopSound(edict_t@ entity, SOUND_CHANNEL channel, const string& in szSample, const bool fUseSoundReplacement = true)

Stops a sound that is playing on the given entity’s channel.

Argument	Purpose
entity	Entity whose sound will be stopped.
channel	Sound channel to stop.
sample	Name of the sound to stop.
fUseSoundReplacement	Whether to use sound replacement to find the actual sample or not.

2.5 EmitSoundDyn

void EmitSoundDyn(edict_t@ entity, SOUND_CHANNEL channel, const string& in szSample, float flVolume, float flAttenuation, int iFlags = 0, int iPitch = PITCH_NORM, int target_ent_unreliable = 0)

Plays a sound on the given entity’s channel. The sound may be sound replaced if there is a replacement sample provided by a replacement file.

Argument	Purpose
entity	Entity that the sound will be attached to. Sounds are played at the entity’s origin.
channel	Sound channel to use. An entity can have a sound playing on every channel it has at the same time. See SOUND_CHANNEL.
szSample	Name of the sound to play.
flVolume	Volume to play the sound at. This value has a range of [0, 1], where 0 is muted, and 1 is maximum volume.
flAttenuation	Attenuation. Values lie in the range [0, 4]. Higher values decrease the falloff range. See Attenuation.
iFlags	Bit vector containing a number of flags. See Sound flags.
iPitch	Pitch to use. See Pitch.
target_ent_unreliable	If not zero, this is the entity index of a player to send this sound to unreliably. Useful for non-critical sounds.

2.6 EmitSound

void EmitSound(edict_t@ entity, SOUND_CHANNEL channel, const string& in szSample, float flVolume, float flAttenuation)

Identical to EmitSoundDyn, but provides default values for omitted arguments.

2.7 EmitSoundSuit

void EmitSoundSuit(edict_t@ entity, const string& in szSample)

Play a specific sentence over the HEV suit speaker - just pass player entity, and !sentencename. Pitch is randomly calculated to fall around PITCH_NORM, volume is determined by the suitvolume cvar. Attenuation is ATTN_NORM.

Argument	Purpose
entity	Entity where the suit sound will be played. Can be any entity, not just a player.
szSample	Sentence to play.

2.8 EmitGroupIdSuit

void EmitGroupIdSuit(edict_t@ entity, int isentencereg)

Play a sentence, randomly selected from the passed in group id, over the HEV suit speaker.

Argument	Purpose
entity	Entity where the suit sound will be played. Can be any entity, not just a player.
isentencereg	Sentence group to play. Must be a sentence group id retrieved using the sound system’s sentence methods.

2.9 EmitGroupNameSuit

void EmitGroupNameSuit(edict_t@ entity, const string& in szSample)

Play a sentence, randomly selected from the passed in groupname.

Argument	Purpose
entity	Entity where the suit sound will be played. Can be any entity, not just a player.
szSample	Sentence group to select a sentence from.

2.10 LookupSentenceIndex

int LookupSentenceIndex(const string& in sentenceName)

Looks up the sentence index of the given sentence.sentenceName is the name of the sentence to find.

Return value: Sentence index if it was found, 0 otherwise.

2.11 LookupSentenceGroupIndex

int LookupSentenceGroupIndex(const string& in szGroup)

Looks up the sentence group index of the given sentence. szGroup is the name of the sentence group to find.

Return value: Sentence group index if it was found, 0 otherwise.

2.12 PlaySentenceGroup

int PlaySentenceGroup(edict_t@ entity, const string& in szGroupName, float volume, float attenuation, int flags, int pitch)

Plays a sentence from a sentence group. The sentence is randomly selected.

Argument	Purpose
entity	Entity where the sentence will be played.
szGroupName	Group to select a sentence from.
volume	Volume.
attenuation	Attenuation.
flags	Sound flags.
pitch	Pitch.

Return value: Index of the sentence that was played, or -1 if no such sentence group exists.

2.13 PlaySentenceGroup

int PlaySentenceGroup(edict_t@ entity, int iGroupIndex, float volume, float attenuation, int flags, int pitch)

Plays a sentence from a sentence group. The sentence is randomly selected.

Argument	Purpose
entity	Entity where the sentence will be played.
iGroupIndex	Group index to select a sentence from.
volume	Volume.
attenuation	Attenuation.
flags	Sound flags.
pitch	Pitch.

Return value:

Index of the sentence that was played.

2.14 PlaySentenceGroupSequential

int PlaySentenceGroupSequential(edict_t@ entity, const string& in szGroupName, float volume, float attenuation, int flags, int pitch, int ipick, const bool bReset)

Plays a sentence group sequentially.

Argument	Purpose
entity	Entity where the sentence will be played.
szGroupName	Name of the group to get the next sentence from.
volume	Volume.
attenuation	Attenuation.
flags	Sound flags.
pitch	Pitch.
ipick	Sentence to pick.
bReset	If true, the first sentence in the group will be used instead of ipick.

Return value:

Index of the sentence after the sentence that was played.

2.15 EmitAmbientSound

void EmitAmbientSound(edict_t@ entity, const Vector& in vecOrigin, const string& in szSample, float flVolume, float flAttenuation, int fFlags, int iPitch)

Plays an ambient sound. Ambient sounds use CHAN_STATIC.

Argument	Purpose
entity	Entity that the sound will be attached to. Sounds are played at the entity’s origin.
vecOrigin	Origin to play the sound at.
szSample	Name of the sound to play.
flVolume	Volume to play the sound at. This value has a range of [0, 1], where 0 is muted, and 1 is maximum volume.
flAttenuation	Attenuation. Values lie in the range [0, 4]. Higher values decrease the falloff range. See Attenuation.
iFlags	Bit vector containing a number of flags. See Sound flags.
iPitch	Pitch to use. See Pitch.

2.16 PlayHitSound

float PlayHitSound(TraceResult& in tr, const Vector& in vecSrc, const Vector& in vecEnd, int iBulletType)

Plays a hit sound based on the trace result’s hit target. Returns the volume at which the hit is being played.

Argument	Purpose
tr	Traceline to use.
vecSrc	Starting point for texture trace. Typically the location where a bullet is being fired from, or where a melee weapon starts its trace from.
vecEnd	End point for texture trace. Typically the location that defines the end position that a bullet traceline goes to, or where a melee weapon ends its trace at.
iBulletType	See the Bullet enum.