Difference between revisions of "Soundscape"

From Valve Developer Community
Jump to: navigation, search
 
m (Multiple instances of one sound in one soundscape: Fixed spelling and grammar errors)
 
(126 intermediate revisions by 46 users not shown)
Line 1: Line 1:
[[Category:Sound System]]
+
{{otherlang2
<i>Soundscapes</i> are definitions of sounds to be played within the Source engine. These soundscapes include settings for various DSP effects as well as commands for controlling sound playback (randomizing, looping etc). The sound system will play one soundscape at a time and crossfade between soundscapes as they are changed. There is some flexibility here that will be explained later in the document. The entity <code>env_soundscape</code> can be used to set a player's soundscape if he moves within its radius and it has line of sight to the player. Only one <code>env_soundscape</code> can be active per player at any one time. The <code>env_soundscape</code> refers to individual soundscapes that are defined in the <code>soundscapes.txt</code> script file.
+
| ru=Soundscape:ru
 +
}}
 +
 
 +
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.
 +
 
 +
{{tip|Cross fade time is defined by the [[convar]] <code>soundscape_fadetime</code>.}}
 +
 
 +
{{tip|Use the [[convar]] <code>soundscape_debug</code> to examine which soundscape is active and why.}}
 +
 
 +
{{note|Soundscapes will not work if the map has not been compiled with VVIS, at least in "-fast" mode.}}
 +
 
 +
{{note|Sound files will not properly loop unless they have a cue point. See [[Looping a Sound]].}}
 +
 
 +
{{note|In most ''Source'' engine branches, soundscapes cannot play two same sounds, even if the pitch, the volume or the sound level is different. See below for possible solutions.}}
 +
 
 +
 
 +
== Browsing Soundscapes ==
 +
 
 +
Soundscapes are typically located in the <code>scripts\</code> folder of a game, stored across multiple text files prefixed with <code>soundscapes_</code>. Each file is loaded via <code>scripts\soundscapes_manifest.txt</code>, 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 <code>soundscapes_%mapname%.txt</code>, with <code>%mapname%</code> 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.
 +
 
 +
{{note|These files are usually packed away in the original Valve games, but they can be overridden automatically by any unpacked files within that folder.}}
 +
 
 +
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 <code>PlaySoundscape</code>. 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.{{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 <code><game>/scripts/soundscapes_manifest.txt</code> file. To better understand soundscape entries, [[Soundscape#Creating_Soundscapes|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 <code>soundscape_flush</code> console command will cancel an active soundscape.}}
 +
 
 +
 
 +
=== 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 activated by a [[env_soundscape]] or an [[env_soundscape_triggerable]].)
 +
 
 +
Soundscape entities are themselves [[point_entities|point-based]], but trigger when the player enters their specified radius and the entity has a [[line of sight]] to him.
 +
 
 +
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 him.
 +
 
 +
 
 +
{{tip|Use the [[convar]] [[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).
 +
 
 +
 
 +
== 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.
 +
 
 +
{{CSGO add}}: this issue has been remedied, allowing soundscapes to play multiple instances of identical sounds concurrently.
 +
 
 +
{{confirm|Has this been fixed in any pre-CS:GO branches?}}
 +
 
 +
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|Counter-Strike Source]]. In the kitchen, there is two fluorescent lights with hum sounds, but the first one is "<code>ambient/machines/fluorescent_hum_1.wav</code>" and the second one is "<code>ambient/machines/fluorescent_hum_2.wav</code>". 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.
 +
 
 +
[[Image:Soundscape identicalsounds.jpg|right|325px]]
 +
[[Image:Hammer_identicalsounds.jpg|right|325px]]
 +
"soundscape.demovdc"
 +
{
 +
"playlooping"
 +
{
 +
"volume" ".65"
 +
"pitch" "92"
 +
"channel" "CHAN_AUTO"
 +
"position" "0"
 +
"attenuation" "1.2"
 +
"wave" "ambient\machines\fluorescent_hum_1.wav"
 +
}
 +
 +
"playlooping"
 +
{
 +
"volume" ".65"
 +
"pitch" "92"
 +
"channel" "CHAN_AUTO"
 +
"position" "1"
 +
"attenuation" "1.2"
 +
"wave" "ambient\machines\fluorescent_hum_2.wav"
 +
}
 +
 +
"playlooping"
 +
{
 +
"volume" ".65"
 +
"pitch" "92"
 +
"channel" "CHAN_AUTO"
 +
"position" "2"
 +
"attenuation" "1.2"
 +
"wave" "ambient\machines\fluorescent_hum_3.wav"
 +
}
 +
}
 +
 
 +
 
 +
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 <code>CHAN_STATIC</code>, <code>CHAN_STREAM</code>, <code>CHAN_AUTO</code>, 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 <code>soundscape_mall.txt</code> and may contain anywhere from 5-30 different soundscapes that take on the following format...
 +
 
 +
<name>
 +
{
 +
<rule>
 +
{
 +
<keyvalue>
 +
...
 +
}
 +
 +
...
 +
}
 +
 
 +
{{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.}}
 +
 
 +
=== Common keyvalues ===
 +
; <code>wave <[[string]]></code>
 +
: The path and filename of the sound to play, relative to <code>game\sound\</code>.
 +
; <code>volume <[[normal]]></code>
 +
: 1 is full power, 0 is silent.
 +
; <code>pitch <[[integer]]></code>
 +
: Percentage value. +/-30 is the useful range.
 +
[[image:Sound_attenuation.jpg|right|200px]]
 +
; <code>position <0-7></code>
 +
: One of eight locations in the world (defined by the mapper) from which a sound can be emitted.
 +
; <code>position random</code>
 +
: As above, but the sound emits from a completely random location near the player.
 +
{{p2 add|; <code>origin <origin></code>}}
 +
: Plays a sound at this origin (X,Y,Z).
 +
; <code>attenuation <[[float]]></code>
 +
: How quickly the sound's volume drops as the camera moves away from it. Only relevant with a <code>position</code> 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.
 +
; <code>soundlevel <string></code>
 +
: Can be used instead of <code>attenuation</code>. Accepts [[Soundscripts#SoundLevel|one of the engine's pre-set values]].
 +
{{warning|Remember to enclose any values with space characters in "quote marks".}}
 +
 
 +
=== Randomized values ===
 +
Some rules accept 'upper' and 'lower' parameter values. For example:
 +
"pitch" "80,120"
 +
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.
 +
 
 +
{{note|Sound files will not properly loop unless they have a cue point. See [[Looping a Sound]].}}
 +
 
 +
"playlooping"
 +
{
 +
"volume" "0.98"
 +
"pitch" "110"
 +
"soundlevel" "SNDLVL_85dB"
 +
 +
"position" "0"
 +
 +
"wave" "ambient/swamps/water_Lap_loop_st.wav"
 +
}
 +
 
 +
{{bug|If another soundscape containing the same "playlooping" sound is triggered, but the sound has a different "pitch" value, the sound will cease to play unless the soundscape is re-triggerred from the one not containing said sound.}}
 +
 
 +
==== playrandom ====
 +
 
 +
Plays a sound after given number of seconds. Allows random values.
 +
 
 +
Playrandom requires all <code>wave</code> KVs to be inside <code>rndwave</code> (even if there is only one). A random selection will be made every time the rule is executed.
 +
 
 +
{{warning|Be careful not to specify any looping sounds in a playrandom group as they may not stop even if a different soundscape is activated.}}
 +
 
 +
"playrandom"
 +
{
 +
"time" "1,4"
 +
"volume" "0.4,1"
 +
"pitch" "90,105"
 +
"soundlevel" "SNDLVL_85dB"
 +
 +
"position" "0"
 +
 +
"rndwave"
 +
{
 +
"wave" "ambient/wind/wind_med1.wav"
 +
"wave" "ambient/wind/wind_hit1.wav"
 +
}
 +
}
 +
 
 +
==== playsoundscape ====
 +
 
 +
Plays a complete soundscape. DSP presets in the 'sub-scape' are ignored.
 +
 
 +
; <code>name</code>
 +
: Name of the soundscape to play.
 +
; <code>position <int></code>
 +
: Offsets each position index of the sub-scape. {{todo|What does that mean?}}
 +
; <code>positionoverride <int></code>
 +
: Forces all positioned sounds in the sub-scape to emit from one location.
 +
; <code>ambientpositionoverride <int></code>
 +
: Forces all unpositioned (i.e. ambient) sounds in the sub-scape to emit from one location.
 +
 
 +
"SubScape"
 +
{
 +
"playsoundscape"
 +
{
 +
"name" "GenericIndoor"
 +
 +
// Overall sub-scape volume to 50%
 +
"volume" "0.5"
 +
 +
// Emit all positioned sounds from position 0
 +
"positionoverride" "0"
 +
 +
// Emit all ambient sounds from position 1
 +
"ambientpositionoverride" "1"
 +
}
 +
}
 +
 
 +
==== dsp <[[integer]]> ====
 +
;dsp_spatial <[[integer]]>
 +
;;dsp_volume <[[float]]>
 +
 
 +
Overrides the current [[DSP]] preset (which would otherwise be derived from the [[$surfaceprop]] of nearby [[material]]s).
 +
 
 +
For a list of values, open <code>scripts\[[dsp_presets|dsp_presets.txt]]</code>. You may need to extract this from the relevant engine GCF with [[GCFScape]]. To preview a DSP  preset, submit <code>room_type <[[int]]></code> to the console.
 +
 
 +
{{note|Be careful when setting presets in soundscapes that could be used in many different locations.}}
 +
{{note|You can also use <code>dsp_volume</code> to define how loud the dsp effect is.}}
 +
{{note|In newer branches of Source (2009+) the convar for ''room_type'' is ''dsp_room'' with the addition of a spatial dsp preset ''dsp_spatial''.}}
 +
{{note|A dsp spatial type can also be assigned to a soundscape in conjunction with dsp room type ("dsp") with <code>"dsp_spatial" "''n''"</code>}}
 +
 
 +
// Disable DSP and play no ambient sounds
 +
"Empty"
 +
{
 +
"dsp" "0"
 +
"dsp_volume" "1.0"
 +
}
 +
 
 +
//DSP room type with a DSP spatial type
 +
"Empty2"
 +
{
 +
"dsp" "40"
 +
        "dsp_spatial" "119"
 +
"dsp_volume" "1.0"
 +
}
 +
 
 +
==== fadetime <[[float]]> ====
 +
 
 +
{{CSGO add}}
 +
{{l4d2 add}}
  
=Using the env_soundscape Entity=
+
The amount of time, in seconds, at which a soundscape fades in.
  
To control soundscapes in a game map, we use the <code>env_soundscape</code> entity. Each entity has a <i>radius</i> and <i>soundscape</i> field. The <i>soundscape</i> field is the name of a soundscape to play when activated, as defined in <code>soundscapes.txt</code>. The radius describes a sphere around the entity that a player must be within to be considered for activating the soundscape. The player must also be visible to the soundscape entity (not occluded by walls or other obstructions). Once a player has triggered a soundscape, that soundscape will remain active until a new one is activated by the player. This means that even if a player leaves a soundscape’s radius after having activated it, the soundscape will continue to play. Only one soundscape may play at any one time. If a new soundscape is activated, the currently playing soundscape will fade out while the new one fades in.
+
"SoundScapeName"
 +
{
 +
    "fadetime"  "1.0"
 +
    "playlooping"
 +
      {
 +
        ...
 +
        ...
 +
      }
 +
}
  
The entity also has eight entity references slots available for use. These correspond to the position values declared in the soundscape. These may point to any valid entity, and will use that entity’s <i>position</i> as a reference point for sound spatialization.
+
==== soundmixer <[[string]]> ====
Creating and Editing soundscapes.txt Entries
 
  
<code>Soundscapes.txt</code> is a simple key/value pair file with the same format as .VMT or .VMF:
+
Selects a custom [[soundmixer]]. Soundmixers manage the priority and volume of groups of sounds; create new ones in <code>scripts\soundmixers.txt</code> (ALWAYS use Default_Mix as a template).
  
<pre>
+
"quiet"
"example"
+
{
{
+
"soundmixer" "Citadel_Dialog_Only"
  "key1" "value1"
+
  "key2" "value2"
+
...
  "subexample"  
+
}
  {  
 
          "key3" "value3"  
 
  }
 
  "key4" "value4"
 
}  
 
  
// Comment text, not parsed
+
===Example===
"example2"       // This is a comment as well
+
"swamp.water.slow"
{
+
{
}  
+
        "dsp" "1"
</pre>
+
        "dsp_spatial" "20"
 +
        "dsp_volume"  "1.0"
 +
        "fadetime"  "1.0"
 +
        "soundmixer" "outside_swap_mixer"
 +
"playlooping"
 +
{
 +
"volume" "0.98"
 +
"pitch" "110"
 +
"soundlevel" "SNDLVL_85dB"
 +
 +
"position" "0"
 +
 +
"wave" "ambient/swamps/water_Lap_loop_st.wav"
 +
}
 +
 +
"playrandom"
 +
{
 +
"time" "1,4"
 +
"volume" "0.4,1"
 +
"pitch" "90,105"
 +
"soundlevel" "SNDLVL_85dB"
 +
                "origin" "3424.676025, 381.604095, 152.927948"
 +
 +
"rndwave"
 +
{
 +
"wave" "ambient/wind/wind_med1.wav"
 +
"wave" "ambient/wind/wind_hit1.wav"
 +
}
 +
}
 +
}
  
Each root-level section (a section that is not within another section) is considered to be a definition of a soundscape. The name given to this soundscape is referenced by the <code>env_soundscape</code> entity.
+
==== Looping MP3 Files E.G.====
  
=Commands=
+
<syntaxhighlight>
 +
//////////// Outside bird sounds (loop mp3 sound file trick by gtamike_TSGK) ////////////
 +
//////////// The 2 .mp3 files are the same as each other just not the same file name ////////////
 +
//////////// MP3 Sound file runtime 3.29mins = 3 X 60 + 29 = 209secs ////////////
  
==dsp==
+
// mp3_loop
  
Sets the DSP effect to a particular room number. In general this should be set to 1. With this DSP the sound engine will attempt to discover the proper parameters based on the surrounding geometry. Setting the DSP to 0 will result in effectively turning DSP effects off. Using other pre-sets are only recommended for special cases. These pre-sets are declared in the <code>../hl2/scripts/dsp_preset.txt</code> file.
+
"mp3_loop"
 +
{
 +
"dsp" "1"
 +
"playlooping"
 +
{
 +
"volume" "1.0"
 +
"pitch" "100"
 +
"soundlevel" "SNDLVL_150dB"
  
 +
"wave" "loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
 +
}
  
Example
+
"playrandom"
<pre>
+
{
    // This soundscape disables DSP and plays no sounds
+
"time" "209"
        "Nothing"  
+
"volume" "1.0"
        {
+
"pitch" "100"
              "dsp"   "0"  
+
"soundlevel" "SNDLVL_150dB"
        }
 
</pre>
 
  
==playlooping==
+
"rndwave"
 +
{
 +
"wave" "loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
 +
"wave" "loop_mp3_soundscape/outside_1MB_20KB_part_2.mp3"
 +
}
 +
}
 +
}
 +
</syntaxhighlight>
  
Plays a looping sound until a new soundscape is triggered.
+
{{warning|Mp3 soundscapes might save filesize for custom maps but are not recommended. It can happen that the FIRST file at "rndwave" plays after the half of the time value has passed. In this case you have to double the value (418 in this case, but live with the consequence that there will be a pause after the soundfile has played twice. }}
  
<code>wave</code>
+
=== Storing and using custom soundscapes ===
* The name of the wave file.
 
<code>volume</code>
 
* Sets the wave's volume (0-1).
 
<code>pitch</code>
 
* Sets the pitch for the wave (100 is normal).
 
<code>attenuation</code>
 
* Sets the attenuation of the wave (only used if a "position" command follows).
 
** '''NOTE:''' These can be random intervals - the random value will be chosen once each time the soundscape is triggered.
 
<code>position</code>
 
* References a position by index (0-7) that the level designer has pointed to in the <code>env_soundscape</code> entity.
 
  
Example
+
The engine uses <code>scripts/soundscapes_manifest.txt</code> to find soundscapes files, but you could also use <code>scripts/soundscapes_%mapname%.txt</code> to load soundscapes on a map-by-map basis. All soundscapes are loaded on map start.
<pre>
 
    // This plays a single looping sound, with a generic reverb (room type 1)
 
    "GenericIndoor"
 
    {
 
        "dsp"  "1"
 
        "playlooping"
 
        {
 
                "volume"      "1"
 
                "pitch"        "100"
 
                "wave"        "ambient/areas/air_exchange/indoor2.wav"
 
        }
 
    }
 
</pre>
 
  
==playrandom==
+
The <code>soundscapes_%mapname%</code> 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 [[BSPZIP|zipped into the BSP itself]] as well.
  
Plays random sound events until a new soundscape is triggered.
+
New soundscapes can be added to the manifest by adding a new "file" line at the bottom, like this:
  
<code>time</code>
+
<syntaxhighlight>
* Time interval of the random event.
+
"file" "<file location>"
<code>volume</code>
+
</syntaxhighlight>
* Random volume interval (0-1).
 
<code>pitch</code>
 
* Random pitch interval (50-250).
 
<code>attenuation</code>
 
* Random attenuation of sound.
 
<code>rndwave</code>
 
* A list of random wave files to choose from.
 
<code>position</code>
 
* Position to use, if spatialized (0-7).
 
  
Example
+
{{note|All soundscape names must be globally unique within a game.}}
<pre>
 
    "GenericOutdoor"
 
   
 
    {  
 
        "dsp"  "1"
 
       
 
        "playrandom"
 
        {  
 
            // Play every 0.1 to 1.5 seconds
 
            "time" "0.1, 1.5"
 
           
 
            // At a volume of 0.5 to 1
 
            "volume" "0.5,1"
 
           
 
            // At a pitch of 50% to 120%
 
            "pitch" "50,120"
 
           
 
            // With an attenuation of 0.7
 
            "attenuation" "0.7"
 
           
 
            // At entity specified at position 1
 
            "position"  "1"
 
           
 
            // Play one of these .wav files randomly each time
 
            "rndwave"
 
            {
 
                "wave" "temp/soundscape_test/music_snippet1.wav"
 
                "wave" "temp/soundscape_test/music_snippet2.wav"
 
                "wave" "temp/soundscape_test/music_snippet3.wav"
 
            }
 
        }  
 
    }
 
</pre>
 
  
==playsoundscape==
+
{{note|Although map-specific soundscripts are mounted in a similar way through <code>maps/%mapname%_level_sounds.txt</code>, soundscapes are mounted through the <code>scripts</code> folder and start with <code>soundscapes_</code> instead of starting in the <code>maps</code> folder with <code>%mapname%</code> at the beginning. You can still use both map-specific soundscripts and map-specific soundscapes at the same time.}}
  
Plays another soundscape and all of its sub-commands.
+
== See also ==
  
'''NOTE:''' DSP effects cannot be altered by sub-soundscapes.
+
{{soundscape lists}}
 +
* [[env_soundscape]]
 +
* [[env_soundscape_proxy]]
 +
* [[env_soundscape_triggerable]]
 +
* [[trigger_soundscape]]
 +
* [[Notepad++ VDF languages]]
  
<code>name</code>
 
* Sub-soundscape to play.
 
<code>volume</code>
 
* All volumes in the sub-soundscape are scaled by this value (0-1).
 
<code>position</code>
 
* An offset added to each position index of the sub-soundscape (0-7).
 
<code>positionoverride</code>
 
* Forces all sub-soundscape positional sounds to occur at a single position originating from the entity at this index (0-7).
 
<code>ambientpositionoverride</code>
 
* Forces all sub-soundscape ambient sounds to be spatialized at a particular position originating from the entity at this index. Useful to make ambient sounds come “from a direction" (0-7).
 
<pre>
 
Example
 
  
    "SubSoundscape"
+
[[Category:Sound System]]
    {
+
[[Category:Level Design]]
        "dsp"  "1"
 
       
 
        "playsoundscape"
 
        {
 
            // Sub-soundscape to play
 
            "name" "GenericIndoor"
 
           
 
            // All sub-soundscape volumes reduced by 50%
 
            "volume" "0.5"
 
           
 
            // All sub-soundscape position sounds will come from this point
 
            "positionoverride" "0"
 
           
 
            // All sub-soundscape ambient sounds will come from this point
 
            "ambientpositionoverride" "1"
 
        }
 
    }
 
</pre>
 

Latest revision as of 19:50, 17 March 2020

Русский

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.

Tip:Cross fade time is defined by the convar soundscape_fadetime.
Tip:Use the convar soundscape_debug to examine which soundscape is active and why.
Note:Soundscapes will not work if the map has not been compiled with VVIS, at least in "-fast" mode.
Note:Sound files will not properly loop unless they have a cue point. See Looping a Sound.
Note:In most Source engine branches, soundscapes cannot play two same sounds, even if the pitch, the volume or the sound level is different. See below for possible solutions.


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 soundscapes_%mapname%.txt, 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.

Note:These files are usually packed away in the original Valve games, but they can be overridden automatically by any unpacked files within that folder.

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:

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.
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 <game>/scripts/soundscapes_manifest.txt 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

Soundscapes can be activated by any of the following entities:

Soundscape entities are themselves point-based, but trigger when the player enters their specified radius and the entity has a line of sight to him.

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 him.


Tip:Use the convar 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).


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.

(in all games since <Counter-Strike: Global Offensive>): this issue has been remedied, allowing soundscapes to play multiple instances of identical sounds concurrently.

Confirm:Has this been fixed in any pre-CS:GO branches?

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 is 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.

Soundscape identicalsounds.jpg
Hammer identicalsounds.jpg
"soundscape.demovdc"
{
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"0"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_1.wav"
	}
	
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"1"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_2.wav"
	}
	
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"2"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_3.wav"
	}
}


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...

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

	...
}
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.

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. +/-30 is the useful range.
Sound attenuation.jpg
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> (in all games since [Portal 2])
Plays a sound at this origin (X,Y,Z).
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.

Warning: Remember to enclose any values with space characters in "quote marks".

Randomized values

Some rules accept 'upper' and 'lower' parameter values. For example:

"pitch"	"80,120"

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.

Note:Sound files will not properly loop unless they have a cue point. See Looping a Sound.
"playlooping"
{
	"volume"	"0.98"
	"pitch"		"110"
	"soundlevel"	"SNDLVL_85dB"

	"position"	"0"

	"wave"	"ambient/swamps/water_Lap_loop_st.wav"
}
Bug: If another soundscape containing the same "playlooping" sound is triggered, but the sound has a different "pitch" value, the sound will cease to play unless the soundscape is re-triggerred from the one not containing said sound.

playrandom

Plays a sound after given number of seconds. 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.

Warning: Be careful not to specify any looping sounds in a playrandom group as they may not stop even if a different soundscape is activated.

"playrandom"
{
	"time"		"1,4"
	"volume"	"0.4,1"
	"pitch"		"90,105"
	"soundlevel"	"SNDLVL_85dB"

	"position"	"0"

	"rndwave"
	{
		"wave"	"ambient/wind/wind_med1.wav"
		"wave"	"ambient/wind/wind_hit1.wav"
	}
}

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. To do: What does that mean?
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.
"SubScape"
{ 
	"playsoundscape"
	{ 
		"name"	"GenericIndoor"

		// Overall sub-scape volume to 50% 
		"volume"	"0.5"

		// Emit all positioned sounds from position 0
		"positionoverride"	"0"

		// Emit all ambient sounds from position 1
		"ambientpositionoverride"	"1"
	} 
}

dsp <integer>

dsp_spatial <integer>
dsp_volume <float>

Overrides the current DSP preset (which would otherwise be derived 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 GCF with GCFScape. To preview a DSP preset, submit room_type <int> to the console.

Note:Be careful when setting presets in soundscapes that could be used in many different locations.
Note:You can also use dsp_volume to define how loud the dsp effect is.
Note:In newer branches of Source (2009+) the convar for room_type is dsp_room with the addition of a spatial dsp preset dsp_spatial.
Note:A dsp spatial type can also be assigned to a soundscape in conjunction with dsp room type ("dsp") with "dsp_spatial" "n"
// Disable DSP and play no ambient sounds 
"Empty"
{ 
	"dsp"	"0"
	"dsp_volume"	"1.0"
}
//DSP room type with a DSP spatial type
"Empty2"
{ 
	"dsp"	"40"
        "dsp_spatial"	"119"
	"dsp_volume"	"1.0"
}

fadetime <float>

(in all games since <Counter-Strike: Global Offensive>) (in all games since <Left 4 Dead 2>)

The amount of time, in seconds, at which a soundscape fades in.

"SoundScapeName"
{
   "fadetime"  "1.0"
    "playlooping"
     {
       ...
       ...
     }
}

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).

"quiet"
{
	"soundmixer"	"Citadel_Dialog_Only"

	...
}

Example

"swamp.water.slow"
{
       "dsp" "1"
       "dsp_spatial" "20"
       "dsp_volume"  "1.0"
       "fadetime"  "1.0"
       "soundmixer" "outside_swap_mixer"
	"playlooping"
	{
		"volume"	"0.98"
		"pitch"		"110"
		"soundlevel"	"SNDLVL_85dB"

		"position"	"0"

		"wave"	"ambient/swamps/water_Lap_loop_st.wav"
	}

	"playrandom"
	{
		"time"		"1,4"
		"volume"	"0.4,1"
		"pitch"		"90,105"
		"soundlevel"	"SNDLVL_85dB"
                "origin"	"3424.676025, 381.604095, 152.927948"

		"rndwave"
		{
			"wave"	"ambient/wind/wind_med1.wav"
			"wave"	"ambient/wind/wind_hit1.wav"
		}
	}
}

Looping MP3 Files E.G.

//////////// Outside bird sounds (loop mp3 sound file trick by gtamike_TSGK) ////////////
//////////// The 2 .mp3 files are the same as each other just not the same file name ////////////
//////////// MP3 Sound file runtime 3.29mins = 3 X 60 + 29 = 209secs ////////////

// mp3_loop

"mp3_loop"
{
	"dsp" "1"
	"playlooping"
	{
		"volume"	"1.0"
		"pitch"		"100"
		"soundlevel"	"SNDLVL_150dB"

		"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
	}

	"playrandom"
	{
		"time"		"209"
		"volume"	"1.0"
		"pitch"		"100"	
		"soundlevel"	"SNDLVL_150dB"

		"rndwave"
		{
			"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
			"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_2.mp3"
		}
	}
}

Warning: Mp3 soundscapes might save filesize for custom maps but are not recommended. It can happen that the FIRST file at "rndwave" plays after the half of the time value has passed. In this case you have to double the value (418 in this case, but live with the consequence that there will be a pause after the soundfile has played twice.

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:

	"file"		"<file location>"
Note:All soundscape names must be globally unique within a game.
Note:Although map-specific soundscripts are mounted in a similar way through maps/%mapname%_level_sounds.txt, soundscapes are mounted through the scripts folder and start with soundscapes_ instead of starting in the maps folder with %mapname% at the beginning. You can still use both map-specific soundscripts and map-specific soundscapes at the same time.

See also

Valve soundscapes lists: HL:S | HL2 | EP1 | EP2 | CS:S | CS:GO | L4D | L4D2 | Portal | Portal 2 | Alien Swarm | DoD:S | TF2
Mods soundscapes lists: INFRA | SE1 | The Ship | VTMB | Dark Messiah | BMS | DOI | Insurgency