SoundSystem
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;
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. |
| 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. |
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. |
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). |
| Constant | Description |
|---|---|
| const float VOL_NORM | Normal volume level. |
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. |
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. |
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 |
|---|---|
| pEntity | 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. |
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 |
|---|---|
| pEntity | 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. |
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 |
|---|---|
| pEntity | 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. |
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.
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. |
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. |
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. |
int LookupSentenceIndex(const string& in sentenceName)
Looks up the sentence index of the given sentence.
| Argument | Purpose |
|---|---|
| sentenceName | Name of the sentence to find. |
Return value:
Sentence index if it was found, 0 otherwise.
int LookupSentenceGroupIndex(const string& in szGroup)
Looks up the sentence group index of the given sentence.
| Argument | Purpose |
|---|---|
| szGroup | Name of the sentence group to find. |
Return value:
Sentence group index if it was found, 0 otherwise.
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.
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.
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.
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 |
|---|---|
| pEntity | 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. |
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. |
