Soundscape

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.
Only one soundscape can be active at any given time, and the individual sounds used within it cannot be controlled via inputs. When another soundscape is activated, the game will cross fade from one to the other.
==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.
Soundscapes can also be mounted on a per-map basis by naming them
with <mapname> being the map that they should be loaded on. These soundscapes will be mounted by that map automatically without changing the manifest and can only be used in that map.
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 these entities:
*env_soundscape
*env_soundscape_triggerable
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.
Whenever these entities activate a soundscape, any positional audio will originate from the targets defined under their properties.
===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. 
===Soundscape entities===
Soundscapes can be activated by any of the following entities:
*env_soundscape
*env_soundscape_triggerable (in turn typically activated by a trigger_soundscape.)
*env_soundscape_proxy (in turn activates an env_soundscape or an env_soundscape_triggerable.)
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.
The two exceptions to this are env_soundscape_proxy (that is triggered through an env_soundscape or an env_soundscape_triggerable), and env_soundscape_triggerable (that is typically set to also be triggered by a trigger_soundscape).
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. (The radius of soundscape entities always take precedence over trigger_soundscape brushes.)
Note that a soundscape will not stop playing just because a player exits its radius or it loses line of sight to them.
===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).
===Multiple instances of one sound in one soundscape===
Currently, in most Source engine branches, it is impossible to play two or more identical sounds at same time in the same soundscape, even if the volume, the pitch or the sound level is different.
This issue has been remedied , allowing soundscapes to play multiple instances of identical sounds concurrently.
A possible solution is to create a copy of the first sound and name it differently. This can be a workaround for really short sounds like light hum, but not recommended for others due to the fact that it increase the overall size uselessly. This is the solution that Valve has chosen in cs_militia, in Counter-Strike Source. In the kitchen, there are two fluorescent lights with hum sounds, but the first one is "ambient/machines/fluorescent_hum_1.wav" and the second one is "ambient/machines/fluorescent_hum_2.wav". Those two sounds are completely identical, but need to be two different name in order to be used in the same soundscape.
Another example is the situation below. We have 3 fluorescent lights and we want hum sounds at their locations. In order to work correctly, soundscape file and Hammer entities should be configured like below.
Despite the fact that most Source engine branches cannot play more than one identical sound at once, in some situations, it appears that it is possible to play the same sound multiple time at different locations using channels.
After many tests in various situations and source code exploration, it seems to be possible by using different channels. For example, instead of using different names, we use different channels like CHAN_STATIC, CHAN_STREAM, CHAN_AUTO, etc. For an unknown reason at the moment, this won't work every time or for each time the map is loaded.
See Soundscript for more information.
==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.
===Common keyvalues===
; wave <string>
: The path and filename of the sound to play, relative to game\sound\.
; volume <normal>
: 1 is full power, 0 is silent.
; pitch <integer>
: Percentage value. 70-130 is the useful range.
; music <boolean> 
: The sound is considered "music", and will be affected by the music volume setting. Akin to setting the sound character, only it is affected by DSP and is directional.
; position <0-7>
: One of eight locations in the world (defined by the mapper) from which a sound can be emitted.
; position random
: As above, but the sound emits from a completely random location near the player.
; origin <origin> 
: Plays a sound at this origin, for example "0,0,0". The coordinates must be comma-delimited but may contain preceding and following spaces. 
; attenuation <float>
: How quickly the sound's volume drops as the camera moves away from it. Only relevant with a position specified. Default value is: "1.00". The lower the value is, greater the radius of the sound will be. And the opposite, higher the value is, smaller the radius of the sound will be. See the image above for illustrated example.
; soundlevel <string>
: Can be used instead of attenuation. Accepts one of the engine's pre-set values.
; suppress_on_restore <0 or 1>
: Prevents sound from restarting upon loading a saved game.
===Randomized values===
Some rules accept 'upper' and 'lower' parameter values. For example:
Whenever the rule is executed the value will be randomly selected within the given range. 
===Rules===
====playlooping====
Plays a sound constantly. Does not allow random values.
====playrandom====
Plays a sound after the given range of the minimum and maximum numbers of seconds specified in the time KV. Allows random values.
Playrandom requires all wave KVs to be inside rndwave (even if there is only one). A random selection will be made every time the rule is executed.
:
====playsoundscape====
Plays a complete soundscape. DSP presets in the 'sub-scape' are ignored.
; name
: Name of the soundscape to play.
; position <int>
: Offsets each position index of the sub-scape.
: For example, if set to 2, then sounds at positions 0, 1, 2, and 3 from the sub-scape would be played at positions 2, 3, 4, and 5 respectively.
; positionoverride <int>
: Forces all positioned sounds in the sub-scape to emit from one location.
; ambientpositionoverride <int>
: Forces all unpositioned (i.e. ambient) sounds in the sub-scape to emit from one location.
====dsp <integer>====
;dsp_spatial <integer>
;;dsp_volume <float>
Set the current DSP preset. derives from the $surfaceprop of nearby materials.
For a list of values, open scripts\dsp_presets.txt. You may need to extract this from the relevant engine VPK with GCFScape. To preview a DSP preset, submit room_type <int> to the console.
====fadetime <float>====
The amount of time, in seconds, at which a soundscape fades in.
====soundmixer <string>====
Selects a custom soundmixer. Soundmixers manage the priority and volume of groups of sounds; create new ones in scripts\soundmixers.txt (ALWAYS use Default_Mix as a template).
===Example===
====Looping MP3 Files====
MP3 files cannot be looped in Source, and are only recommended for non-looping sounds. Nonetheless, it is possible to somewhat simulate looping using with identical files and set the time to the length of those files:
===Storing and using custom soundscapes===
The engine uses scripts/soundscapes_manifest.txt to find soundscapes files, but you could also use scripts/soundscapes_%mapname%.txt to load soundscapes on a map-by-map basis. All soundscapes are loaded on map start.
The soundscapes_%mapname% method should be used when modifying the manifest is unnecessary or impossible (e.g. on custom maps without their own mod directories). This file can be zipped into the BSP itself as well.
New soundscapes can be added to the manifest by adding a new "file" line at the bottom, like this:
==Creating Soundscapes using XBLAH's Modding Tool==
Soundscapes can now be easily created or modified using . The UI provides an intuitive way to create new soundscapes, using the integrated file explorer. This allows the user to browse all the files mounted (VPKs and loose files), let the user preview the files individually and let the user preview how the whole soundscape is gonna play in-game.
Where to find it
This can be accessed within the tool through Sounds > Soundscape Editor.
==See also==
* env_soundscape
* env_soundscape_proxy
* env_soundscape_triggerable
* trigger_soundscape
* Notepad++ VDF languages
Category:Sound System
Category:Level Design
Category:Plain text formats
Category:Plain text files
Category:Tutorials