Soundscripts

Soundscripts contain sound entries or game sounds that are used to wrap -specific playback instructions around WAV or MP3 files. A sound entry or game sound can define the meaning of a sound to NPCs, its pitch and volume, how far away it can be heard from (attenuation), and can be used to randomize which precise sound file is played. Operator stacks can be used to define even more complex behaviors.
Soundscripts are loaded on the server only from:
*
* 
All filepaths within a soundscript are relative to the game's folder.
playgamesound <entry> is a console command that one can "browse" and play the available sound entries of a game with.
== Example ==
entry.name
{
 channel CHAN_AUTO
 volume VOL_NORM
 pitch PITCH_NORM
 soundlevel SNDLVL_NORM
 wave common/null.wav
}
If a value has a space or tab character within it, it must be wrapped in "quote marks".
== Commands ==
=== Wave / Rndwave ===
Filename of the sound to play. All file paths can be preceeded with one or two sound characters, see below.
wave common/blah1.wav
You can also have the engine pick from a list of random files. A given sound won't repeat until all of the others have played. Note that the random choice is decided by the server, not the client.
rndwave
{
 wave common/blah1.wav
 wave common/blah2.wav
 wave common/blah3.wav
}
=== Volume ===
A number between 0 and 1, where 1 is the sound's original volume. VOL_NORM will insert your mod's default volume, which will probably be 1.
To have a random numeric value chosen every time the sound plays, type a lower bound and a higher bound, separated by a comma. Example: volume 0.4,0.6.
=== Pitch ===
Any number between 0 and 255, where 100 is the sound's original pitch and 255 is very high.
*PITCH_LOW = 95
*PITCH_NORM = 100
*PITCH_HIGH = 120
To have a random numeric value chosen every time the sound plays, type a lower bound and a higher bound, separated by a comma. Example: pitch 90,110.
=== Channel ===
Channels are used to categorize sounds in a way that NPCs, and game logic in general, can understand.
 
:: Exceeding this will result in a channel allocation error, preventing sounds from playing. 
Value for channel 	Description
CHAN_AUTO 	Default, generic channel.
CHAN_WEAPON 	Player and NPC weapons.
CHAN_VOICE 	Voiceover dialogue. Used for regular voice lines, etc.
CHAN_VOICE2 	Additional voice channel. Used in for the announcer.
CHAN_ITEM 	Generic physics impact sounds, health/suit chargers, sounds.
CHAN_BODY 	Clothing, ragdoll impacts, footsteps, knocking/pounding/punching etc.
CHAN_STREAM 	Sounds that can be delayed by an async load, i.e. aren't responses to particular events.
CHAN_REPLACE 	Used when playing sounds through console commands.
CHAN_STATIC 	A constant/background sound that doesn't require any reaction.
CHAN_VOICE_BASE 	Network voice data (online voice communications)
CHAN_USER_BASE+<number>	Custom channels can be defined here. Allocates a channel for the desired sound entry.
Channels can also be specified by a number, corresponding to the enum in the engine. For example -1 will be CHAN_REPLACE.
=== Soundlevel ===
The sound's attenuation; how fast it drops away. The engine starts running into trouble below 60dB.
The following list contains all default sound levels, their attenuation value, real world examples, and in-game examples. All values and real world examples were taken from .
It is possible to pass a literal number value ("150" as opposed to "SNDLVL_150") and freely choose any number between 0 and 255. Games tested: 
Value for soundlevel 	AttenuationValue	Real World 	In Game
SNDLVL_NONE 	0 	Everywhere 	: Music disconnected from environment (Ex: checkpoint music, credit music, mob music)
SNDLVL_20dB 	 	Rustling leaves 	
SNDLVL_25dB 	 	Whispering 	
SNDLVL_30dB 	 	Library, dishwasher 	
SNDLVL_35dB 	 	 	
SNDLVL_40dB 	 	Moderate rainfall 	
SNDLVL_45dB 	 	Refrigerator 	
SNDLVL_50dB 	3.9 	Average home, heavy rainfall 	
SNDLVL_55dB 	3.0 	 	: Digital alarm clock in C8M1_Apartment.
SNDLVL_60dBSNDLVL_IDLE	2.0 	Normal conversation, clothes dryer 	
SNDLVL_65dB 	1.5 	Washing machine, dishwasher 	
SNDLVL_STATIC 	1.25 	 	
SNDLVL_70dB 	1.0 	Car, vacuum cleaner, mixer, electric sewing machine 	: Moustachio whack smash and pop-up, tv static, whacked piano
SNDLVL_75dBSNDLVL_NORM	0.8 	Busy traffic 	: Various doors, swarm of flies, Lilpeanut audible, bullet impact on wood.
SNDLVL_80dB 	0.7 	Mini-bike, alarm clock, noisy restaurant, office tabulator, outboard motor, passing snowmobile, police siren	: Jukebox, music spitter spit pile as source.
SNDLVL_TALKING 	0.7 	 	Valve's chosen dialogue attenuation
SNDLVL_85dB 	0.6 	Average factory, electric shaver 	: Moustachio strength attract, big fire after airliner crash in C11M5_runway
SNDLVL_90dB 	0.5 	Screaming child, passing motorcycle, convertible ride on freeway, hair dryer 	: Moustachio strength attract, gas can bursting
SNDLVL_95dB 	 	 	: Mounted Machine Gun
SNDLVL_100dB 	0.4 	Subway train, diesel truck, woodworking shop, pneumatic drill, boiler shop, jackhammer 	: Music coop player in danger AKA tags (ledge hanging, pinned down by SI), Elevators.
SNDLVL_105dB 	 	Helicopter, power mower 	
SNDLVL_110dB 	 	Snowmobile (drivers seat), inboard motorboat, sandblasting, chainsaw 	: Boomer alert close, Van in C11M4_Terminal.
SNDLVL_120dB 	 	Car horn, propeller aircraft, concert 	: Boomer alert, Indoor fire in C1M1_Hotel, Fireworks in C2M5_Concert, Rain in "Hard Rain" campaign.
SNDLVL_125dB 	 	 	: Boomer alert far
SNDLVL_130dB 	 	Air raid siren, fireworks 	: Carousel music during crescendo event, C5M2_park perimeter alarm.
SNDLVL_GUNFIRE 	0.27 	Threshold of pain, gunshot, jet engine 	
SNDLVL_140dB 	0.2 	Airplane taking off, jackhammer 	: Flock of crows, Lowering bridge in C5m5_Bridge, APC engine.
SNDLVL_145dB 	 	 	: Wandering witch music ("lost little witch")
SNDLVL_150dB 	0.2 	Smithing hammer 	: Concert music, parade music, zombie choir, Boat Horn
SNDLVL_180dB 	 	Rocket launching 	
== Operator Stacks ==
 introduced Operator Stacks, which are a system used to add complex behaviour to sounds, extending soundscripts.
Outside , they are supported in: 
The keyvalues soundentry_version 2 and operator_stacks are characteristic. Example:
VFX.LightFlickerEnd 
{
	channel		CHAN_AUTO
	soundlevel	SNDLVL_105db
	volume		1.0
	rndwave
	{
		wave	"vfx/light_flicker/light_flicker_end_01.wav"
		wave	"vfx/light_flicker/light_flicker_end_02.wav"
		wave	"vfx/light_flicker/light_flicker_end_03.wav"
		wave	"vfx/light_flicker/light_flicker_end_04.wav"
	}
	soundentry_version 2
	operator_stacks
	{
		start_stack // applied when the sound begins
		{
			import_stack 	"P2_exclusion_time_blocker_start" // defined in scripts/sound_operator_stacks.txt
			// We are now extending/configuring "P2_exclusion_time_blocker_start"
			// which contains an operator with the exact name "block_entries" whose values we will now override:
			block_entries // prevents another sound from playing
			{
				input_duration	0.25					// seconds to block for
				match_entry		"World.LightFlickerEnd"	// the sound entry to block
				match_entity	false					// only on the same entity that this sound is playing from?
			}
		}
	}
}
== Sound characters ==
The first two characters of a WAV's name are scanned for the following:
Symbol	Name 	Game/branch	Purpose / Notes
* 	CHAR_STREAM 	all 	Streams from the disc, get flushed soon after. Use for one-off dialogue files or non-looping music.
# 	CHAR_DRYMIX 	all 	Bypasses DSP, becomes affected by the user's music volume setting (). The latter part also requires the sound to be non directional (soundlevel of 0).
@ 	CHAR_OMNI 	all 	Non-directional sound; plays "everywhere", similar to SNDLVL_NONE, except it fades with distance from its source based on its soundlevel.
> 	CHAR_DOPPLER 	all 	Doppler encoded stereo: left for heading towards the listener and right for heading away.
< 	CHAR_DIRECTIONAL 	all 	Stereo with direction: left channel for front facing, right channel for rear facing. Mixed based on listener's direction.
^ 	CHAR_DISTVARIANT 	all 	Transition distance is hard-coded, see below.
) 	CHAR_SPATIALSTEREO	all 	Spatializes both channels, allowing them to be placed at specific locations within the world; see below.
} 	CHAR_FAST_PITCH 	all 	Forces low quality, non-interpolated pitch shift.
$ 	CHAR_CRITICAL 	Up to 	Forces sound to be cached at a fixed point in memory.
! 	CHAR_SENTENCE 	Since 	An NPC sentence.
? 	CHAR_USERVOX 	all 	Voice chat data. You shouldn't ever need to use this.
& 	CHAR_HRTF_FORCE 	 	Indicates wav should use HRTF spatialization for all entities (including owners).
~ 	CHAR_HRTF 	 	Indicates wav should use HRTF spatialization for non-owners.
` 	CHAR_HRTF_BLEND 	 	Indicates wav should use HRTF spatialization for non-owners, blended with stereo for sounds sufficiently close.
+ 	CHAR_RADIO 	 	Indicates a 'radio' sound -- should be played without spatialization.
$ 	CHAR_SUBTITLED 	 	Indicates the subtitles are forced.
% 	CHAR_MUSIC 	 	Indicates main menu music.
( 	CHAR_DIRSTEREO 	 	Indicates directional stereo wav (like doppler).
For example: 
*
*
=== Spatial Stereo ===
Adding ) in front of a stereo sound name in the soundscript such as tells the sound engine that it is a spatialized sound; this allows the sound to emit from a specific location within the world. When not used, stereo sounds play in a fixed 2-channel orientation and cannot be panned to simulate a location. Single-channel files do not require ) before the filename and will be spatialized automatically.
=== Soundscapes ===
Soundscapes have special needs. Stereo wave files used in PlayRandom require that ( is placed before the filename. PlayLooping still uses ) but ( will spatialize the two channels separately for an alternate effect; ( sounds more environmental, but the exact nature of this behavior is unknown. Generic soundscripts can sometimes use ( to gain the same stereo spatialization that occurs in PlayLooping.
=== Distance variance in Source ===
Adding ^ in front of a sound name, such as tells the sound engine that it is a distance based sound. The left channel of the sound file is the 'near' sound that will play when the sound originates close to you, and the right channel is the 'far' sound that will play when the sound originates far from you. If the ^ mark is not used in the soundscript, the sound is treated as stereo with no directionality or distance. This is a different feature than the soundlevel property to control attenuation. This distant variant feature allows you to play two different sounds (but using only one file) and crossfading between the two depending on how far away the sound originates.
The fade distances are hardcoded to begin at 240 world units and end at 1320 world units, and cannot be changed in custom maps or mods.
== See also ==
*
*Soundscape
*Left 4 Dead Soundscripts
*Podcast 17 Mike Morasky Interview - Discussion about audio production and insight into the evolution of the sound system. Archived from the original.
----
*
*
*
*
Category:Source
Category:Sound System
Category:Plain text formats
Category:Plain text files