Soundscape (Source 2)

Source Engine

Source 2

A Soundscape is a type of audio script used to add ambience to maps. It can be used in any number of maps, requires only a single entity to implement, and does not generate any network traffic. Soundscapes use a mixture of looped and randomly played sounds, all of which have the option to be emitted from one of eight assignable target locations; DSP and Soundmixer profiles can also be enforced.

Individual "Sounds" within a soundscape are called Sound Events. A soundscape script includes a listing of all Sound Events within the soundscape, and parameters on how the audio can be heard, played back, or otherwise manipulated. Beyond that, individual sound events can have their own parameters defined, which will function as written unless the parameters of the soundscape override those specific functions. The parameters that can be specified in a soundscape or sound event are theoretically option, as without defining them, they will revert to an engine "default".

Only one soundscape can be active at any given time, and the individual sounds used within it cannot be controlled via inputs, and must instead be addressed via invidiaul entities all pulling from the soundscape. When another soundscape is activated, the game will cross fade from one to the other.

Tip:

• Cross fade time is defined by the cvar soundscape_fadetime, or fadetime in newer branches.
• Use the cvar soundscape_debug to examine which soundscape is active and why.
• Soundscapes and sound events can be configured to either load into memory upon being called (i.e. a player entering a soundscape radius), or they can be pre-loaded upon launch of the addon in-game. This is preferable for sound events that need to be as timely as possible (such as gunshots), but is unnecessary for sounds such as music or atmosphere. The delay to load into memory is minimal, but perceptible in some instances.

Note:

• Sound files will not properly loop unless they have a cue point. See Looping a Sound. In Source 2, both .WAV & .MP3 files can be looped.
• At least one soundscape radius or trigger box should cover the info_player_start or whatever game specific player spawn entities you have, else the players will spawn without loading any soundscape until they trigger a Soundscape.

Soundscapes

Browsing Soundscapes

Soundscapes are typically located in the scripts\ folder of a game, stored across multiple text files prefixed with soundscapes_. Each file is loaded via scripts\soundscapes_manifest.txt, which lists all soundscape scripts that should be mounted by the game. Soundscapes mounted through the manifest can be used anywhere in the game, even if they're only intended for a specific area.

Some Source 2 titles have done away with having many of the game files accessible as editable text files, and instead have many such functions packed into .vpk files. For others, these files can beaccessed through an addon's Sounds & Sound Events folders, and the soundevents_addon.vsndevts file.

At the bottom of this article you will find links to lists of soundscapes for individual games, along with attempts at describing them.

You can browse through all the available soundscapes in a current game first hand, using the in-game console command PlaySoundscape. After typing in the first letter as the commands parameter, the auto-complete feature will list them as suggestions. You can then scroll through this list using the arrow keys.

Configuring Soundscapes

Soundscapes can only be configured through the entity env_soundscape.

There are other entities which can activate the soundscape, but these are the only entities which actually define soundscape properties. The other entities will point to these and use them as masters to remotely trigger the soundscape. (Such as point_soundevent).

Whenever these entities activate a soundscape, any positional audio will originate from the targets defined under their properties.

Tip: Many soundscapes define positions for sounds to emanate from, so it is always a good idea to peek into the soundscape entry and get a feel for what you can do. Most entries are found in the text files listed in the <addon>/Sound Events/soundevents_addon.vsndevts file. To better understand soundscape entries, see below.

Activating Soundscapes

Any soundscape entity that is enabled and becomes triggered by the player, activates its - or its master's - specified soundscape. Soundscapes remain active until a map change occurs, or another soundscape is activated, even if the entity that originally activated it becomes disabled.

Tip:The soundscape_flush console command will cancel an active soundscape.

Soundscape entities

env_soundscape entities are themselves point-based, but trigger when the player enters their specified radius and the entity has a line of sight to them. This radius has no bearing on where and how the audio plays, only when it is triggered. A soundscape will not stop playing just because a player exits its radius or it loses line of sight to them.

As only one soundscape can be active at any one time, if one or more soundscape entities are triggered simultaneously, the closest one is given precedence.

Tip:Use the cvar soundscape_debug to examine which entity is active and why.

Soundscape Placement

At first, a good rule is to place only as many soundscapes as you absolutely need. Try to choose from a similar set of soundscapes to be played, and then pick one that will be your primary soundscape. After that, place your secondary soundscapes at every contrasting location (e.g. house, generator room). Make sure that every location with localized sound effects has its own master soundscape that is tied to the proper targets.

Once you've gotten a general idea of where your soundscapes will be located, you'll then be able to start adding/configuring the entities that will trigger your soundscapes and create a kind of blueprint for how soundscapes will flow from one to another. In many cases, you'll be placing entities that block off all exits from your contrasting locations with triggers to your primary soundscapes. Basically, the goal is to anticipate the player's movement throughout the map, and to block off each area in such a way that it will always have the proper soundscape activated.

After your flow is organized, you'll be able to specialize your soundscapes/triggers to behave in complex ways (e.g responding to game events).

Custom Soundscapes

Creation

Soundscape scripts are very similar to soundscripts, but still remain entirely different things.

Soundscapes require a few of their own rules, and are placed in plain text files that are separate from normal soundscript files. A typical soundscape file might be named soundscape_mall.txt and may contain anywhere from 5-30 different soundscapes that take on the following format.

Bug:If a soundscape's name is too long, soundscape entities will not be able to trigger it, although it will still be triggerable through console. Character limit unknown.  [todo tested in ?]

<name>
{
	<rule>
	{
		<keyvalue>
		...
	}

	...
}

Keyvalues For Sound Events and Soundscapes

type <string>

This references specific pre-defined classifications for audio files, and how they are treated in individual Source games. Generally required to properly define an initial sound event, essentially telling the engine "You're allowed to use this for this game". type does not inherently define any parameters. (i.e. type "csgo_mega")

vsnd_files_track_01 <string>

The path and filename of the sound to play, relative to addon\sound\. vsnd_files_track_01 can be modified for each sequential sound file being referenced (i.e. vsnd_files_track_01 = "sound/soundfile_01.vsnd", vsnd_files_track_02 = "sound/soundfile_02.vsnd". This must reference the compiled (.vsnd) version of the audio file, located under the game directory, rather than the original .WAV or .MP3 file located in the addon directory. Multiple files can be referenced as one "track", at which point the file played will be randomly selected when the sound event is called on by the soundscape.

soundevent_01 <string>

References another pre-existing sound event. soundevent_01 can be modified for each sequential sound file being referenced (i.e. soundevent_01 = "Sound_Event.01", vsnd_files_track_02 = Sound_Event.02.

base <string>

Copies a pre-existing copy, from which sounds and parameters will be pulled from, but can be overridden. (i.e. base = "Sound_Event.01"

volume <float>

1 is full power, 0 is silent.

volume_random_max <float>

Defines upper end of a range. 1 is full power, 0 is silent.

volume_random_min <float>

Defines lower end of a range. 1 is full power, 0 is silent.

use_distance_volume_mapping_curve <string>

Enables or disables position-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

distance_volume_mapping_curve <normal>

Defines a distance-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_distance_volume_mapping_curve. This function is useful for creating sound entities that "radiate" sound, and are immersive.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ distance, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 1 at the entity origin, and 0 500 units away:

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 500.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Distance is defined in Hammer Units from the entity origin. Volume is a range, where 1 is full power and 0 is silent.

use_time_volume_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables time-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

time_volume_mapping_curve <normal>

Similar to distance_volume_mapping_curve, defines a time-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_time_volume_mapping_curve. This function is useful for creating fade-ins.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ time, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 0 at the beginning of the sound event being triggered, and fades-in with a linear curve to 1 after 5 seconds.

[ 0.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

[ 5.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

Time is defined in seconds. Volume is a range, where 1 is full power and 0 is silent.

use_fadetime_volume_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables further time-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

fadetime_volume_mapping_curve <normal>

Similar to distance_volume_mapping_curve, defines a time-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_fadetime_volume_mapping_curve. This function is useful for creating fade-outs.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ time, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 1 at the beginning of the sound event being triggered, and fades-out with a linear curve to 0 after 5 seconds.

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 5.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Time is defined in seconds. Volume is a range, where 1 is full power and 0 is silent.

pitch <integer>

Integer value for audio pitch. 1 is the original pitch of the file, and every whole integer increases or decreases the pitch by an octave (12 semitones, 1200 cents). Non-whole integers are valid, for smaller scale changes in pitch. Importantly, pitch also defines playback speed. Thus, pitch = 1 will result in a file playing back at original pitch and original speed, pitch = 2 will result in a file playing back at one octave above it's original pitch and twice it's original speed, and pitch = 0.5 will result in a file playing back at one octave below it's original pitch and half it's original speed.

pitch_random_max <float>

Defines upper end of a range. Positive number required.

pitch_random_min <float>

Defines lower end of a range. Negative number required.

occlusion <string>

Similar to use_distance_volume_mapping_curve, enables or disables occlusion, which can then be defined by another keyvalue. Possible values include true & false.

occlusion_intensity <integer>

Determines how occluded sounds are when played back. Will not function unless enabled by occlusion. Occlusion results in a sound being "muffled" when the player has a solid object between their line of sight of the sound origin, with occlusion_intensity acting as a percentage value ranging from 0 to 100.

use_distance_unfiltered_stereo_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables distance-based stereo mapping, which can then be defined by another keyvalue. Possible values include true & false.

distance_unfiltered_stereo_mapping_curvee <normal>

Similar to distance_volume_mapping_curve, defines a distance-to-stero width ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_distance_unfiltered_stereo_mapping_curve. This function is useful for immersion, as immersive sounds are often wider in the stero field when closer to the player, and more narrow when further away.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ distance, stereo width, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where stereo width is 1 when the player is at the same location as the sound origin, and 0 when the player is 500 units away from the sound origin.

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 500.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Distance is defined in Hammer Units from the entity origin. Stereo Width is a range, where 1 is the original stereo imaging of the audio file and 0 is fully mono playback.

dsp_preset <string>

Defines which DSP reverb preset to apply to the sound event or soundscape.

Possible options include:

• reverb_0_null
• reverb_2_crawlSpace
• reverb_3_smallTunnels
• reverb_4_smallCarpetRoom
• reverb_5_smallRoom
• reverb_6_largeRoom
• reverb_7_mediumHall
• reverb_8_mediumCarpetRoom
• reverb_9_mediumChamber
• reverb_10_warehouse
• reverb_11_smallBright9
• reverb_12_mediumBright
• reverb_13_largeBright
• reverb_14_brightHallway
• reverb_15_largeCarpetRoom
• reverb_16_carpetCorridor
• reverb_17_smallConcrete
• reverb_18_mediumConcrete
• reverb_19_largeConcrete
• reverb_20_outsideAlley
• reverb_21_outsideStreet
• reverb_22_outsideOpen
• reverb_23_smallBathroom
• reverb_24_largeBathroom

override_dsp_preset <string>

When enabled, allows a Sound Event to Override the parent DSP (The Soundscape's specified DSP) with it's own DSP. Possible values include true & false.

reverb_wet <[[integer]>

Determines the blend between the volume of the original audio file(s), and the reverb created by the DSP. A value range from 0-1, 0 = the original audio file, played with no reverb, 1 = the audio file played with the full effect of the reverb DSP.

use_world_position <string>

Similar to use_distance_volume_mapping_curve, enables or disables setting a specific coordinate position for a sound origin, which can then be defined by another keyvalue. Possible values include true & false.

position <normal>

Determines the position of the sound origin, without any bearing on where the entity source of the sound is located on the map. Made up of a data point containing [ x, y, z ], using unit coordinates in Hammer.

position_relative_to_player <string>

Similar to use_distance_volume_mapping_curve, enables or disables a sound origin being constantly set to a player's position, which can then be defined by another keyvalue. Possible values include true & false.

randomize_position_max_radius <float>

Defines upper end of a range. Sets the origin of a sound to a random point within the bounds of the radius. The origin point of the radius is the sound entity. Measured in Hammer units.

randomize_position_min_radius <float>

Defines lower end of a range. Sets the origin of a sound to a random point within the bounds of the radius. The origin point of the radius is the sound entity. Measured in Hammer units.

randomize_position_hemisphere <string>

By default, sounds only randomize above a player in position, but with this function, they can appear above or below a player on the Z axis. Possible values include true & false.

enable_trigger <string>

Allows other parameters to trigger the sound event, independently of I/O. Possible values include true & false.

retrigger_interval_max <integer>

Defines upper end of a range. If enabled by enable_trigger, the sound event will randomly retrigger constantly on a random interval within the range, recalculated every time it triggers. Measured in seconds.

retrigger_interval_min <integer>

Defines lower end of a range. If enabled by enable_trigger, the sound event will randomly retrigger constantly on a random interval within the range, recalculated every time it triggers. Measured in seconds.

mixgroup <string>

Determines a sound's priority. Sounds with a lower priority will "duck" under sounds with a higher priority. Also can act as an internal form of "tagging" sounds. A list of possible mixgroups is included below. As can be seen, less frequent, individual short foreground sounds are often higher priority, while constant, background sounds are lower priority.

• "Ambient" // Low Priority
• "World" // Low Priority
• "Footsteps" // High Priority
• "Weapons" // High Priority
• "WeaponsDistant" // High Priority
• "Explosions" // High Priority
• "Foley" // High Priority
• "UI" // High Priority
• "VO" // Unknown Priority
• "Music" // Unknown Priority
• "All" // Unknown Priority

block_matching_events <string>

If enabled, prevents more than one of the same sound event being active at one time. When enabled, a retriggered sound event will restart a sound, rather than play a second instance of it. Possible values include true & false.

block_matching_entity <string>

If enabled, prevents more than one of the same sound from one sound entity being active at one time. When enabled, a retriggered sound entity will restart a sound, rather than play a second instance of it. Possible values include true & false.

block_distance <integer>

Prevents more than one of the same sound event being active at one time, within a range of 0 to the specified integer, from the origin point of the sound. Measured in Hammer units.

instance_limit <integer>

Sets the limit of how many instances of a sound from a single source can be playing before further instances become blocked by block_distance, block_matching_events & block_matching_entity.

delay <integer>.

Sets a delay in seconds from when a sound event is triggered, to when it begins to play.

vsnd_duration <integer>.

Stops the currently playing sound after a certain duration of seconds after it was initially triggered (not when it began playing). This will trigger a fade curve if you have one defined. Otherwise, it will simply stop the sound.

preload_vsnds <integer>.

Preloads the required audio file(s) into system memory, so they can be called upon with as low latency as possible. Preferably used for shorter sounds that must be timely, such as gunshots, or sounds in a rhythm game.

Storing and using custom soundscapes

Source 2 does away with the sound scripts model, and replaces those files with soundevents_addon.vsndevts. This is also an editable text file, and is where new user-created soundscapes and sound events can be entered. This file contains example soundscapes and sound events that can be copied or modified. The same key values and functions detailed earlier for scripts work within this file as well. The This file details potential uses for the preset base soundevents and soundscapes, and more information on implementing new content.

An example of a base Soundscape:

"ambient_example.outdoors" = 
{
	base = "amb.soundscapeParent.base"
	enable_child_events = true
	soundevent_01 = 
	[
		"ambient_example.outdoors.birds",
		"ambient_example.outdoors.airplanes",
		"ambient_example.outdoors.wind",
	]
}

An example of a base sound event:

"amb.base" = 
{
	type = "csgo_mega"
	mixgroup = "Amb_Common"
	occlusion_intensity = 0.0
	distance_effect_mix = 0.0
	restrict_source_reverb = true
	use_distance_unfiltered_stereo_mapping_curve = true
	use_time_volume_mapping_curve = true
	distance_volume_mapping_curve = 
	[
		[
			0.0, 1.0, -0.00394, -0.00394,
			2.0, 3.0,
		],
		[
			300.0, 0.0, -0.002991, -0.002991,
			2.0, 3.0,
		],
	]
	fadetime_volume_mapping_curve = 
	[
		[
			0.0, 1.0, -1.223776, -1.223776,
			2.0, 3.0,
		],
		[
			0.208571, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
	distance_unfiltered_stereo_mapping_curve = 
	[
		[
			0.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
		[
			300.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
	time_volume_mapping_curve = 
	[
		[
			0.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
		[
			0.297143, 1.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
}

While soundevents_addon.vsndevts is a text file, it has to be compiled by either Hammer, or the Game Engine before it will function correctly. If you have completed entered in all the parameters for your soundscapes and sound events in the text file, and they are not appearing in Hammer or playing in game, soundevents_addon.vsndevts can be recompiled either be re-openeing a build of the map in-game, or by selecting the file in the "Asset Browser", right clicking, and selecting Recompile > Full>.

To add Soundscape and sound event entries to soundevents_addon.vsndevts, they should be added directly after the soundscape templates in the file, just before the ///BASE SOUNDEVENT TEMPLATES header. An example Source 2 Soundscape:

"soundscape_name" 
{
	base = "amb.looping.stereo.base"
	volume = 0.2 
	pitch = 1.0
	mixgroup = "Ambient"
	use_distance_volume_mapping_curve = false	
	vsnd_files_track_01 = "sounds/soundevent_audio_file.vsnd"
	distance_unfiltered_stereo_mapping_curve = 
	[
		[
			0.0, 1.0, 0.0, 0.0, 2.0, 3.0,
		],
		[
			1000, 1.0, 0.0, 0.0, 2.0, 3.0,
		],
	]
}

This example uses a template soundevent base for many of its parameters when playing back the audio file, and then overrides a few of those parameters, such as the specified stereo mapping curve.

Storing Audio Files

In Source 2, Audio files that you would like to become sound events, triggerable as part of a soundscape, must be stored in the sounds folder, under the content directory of your addon. After you have placed files there, launch Hammer, and open your addon. This should cause the audio files to be auto-compiled into .vsnd files. Check the asset browser, or the sounds folder, under the game directory, to ensure they have been compiled. The soundevents_addon.vsndevts file can only read, and call on .vsnd files, rather than the raw .wav or .mp3 files.

See also

• env_soundscape