L4D2 Custom Sound and Music Tutorial

From Valve Developer Community
Jump to: navigation, search

<Left 4 Dead 2> Since the August 20, 2010 update, L4D2 fully supports custom sounds. Instructions provided by Valve are available in the L4D2 Campaign Add-on Tutorial article. This article covers how custom sounds are used in L4D2, file management, and testing.

Getting started

In general:

  1. There are many places where custom sound files work: either in an official sound folder, a sound folder in a known search path, or addon containing a sound folder.
  2. Build a new sound.cache in that folder with snd_buildsoundcachefordirectory before testing
Tip.png Tip: Building/rebuilding sound.cache of a separate search path or addon is faster than using the official sound folder (especially with older computers). There are a smaller number of sound files to process every time sound.cache is built. There is the added benefit of managing your assets in a modular fashion during development. It is also easier to merge assets into a single VPK when ready to share/ship.
Warning.png Warning: Don't place sounds files in root of the sound directory because it will cause bugs. Add them in a sub-directory instead (ex: ../sound/music/terror). It can be a new sub-directory or an "official" sub-directory provided by default.
Option 1 - As a custom search path
  1. Create a directory anywhere with a sound sub-folder.
  2. Add the directory path in gameinfo.txt found at "..\left 4 dead 2\left4dead2\gameinfo.txt"
  3. Create another folder within the sound folder, either a unique or existing name (i.e. ambient, music, etc.). Maintain the same naming structure as the official sound folder, if possible.
  4. Build sound.cache with the in-game console: snd_buildsoundcachefordirectory <absolute directory name, i.e. e:\custom_sounds or game root, i.e. ../left4dead2/ (this contains the official sound folder)>. This command will search for a directory called sound and generate sound.cache
  5. Restart client.
  6. Test the sound via console command (sound is the root directory): play (sub-directory of sound folder)/<name of sound>
Option 2 - As an addon/VPK
  1. Create a folder in the addons directory. It should contain a sub-folder named sound. The addons directory is located at "..\left 4 dead 2\left4dead2\addons"
  2. Create another folder within the sound folder. This is where sounds can be stored.
  3. Build sound.cache for the addon using in-game console: snd_buildsoundcachefordirectory ../left4dead2/addons/<name of VPK addon folder that will be packed into a VPK>. This command will search for a directory called sound and create a file called sound.cache within it.
  4. Create the VPK as a content pack. In other words, only the sounds (and correct directory structure) and sound.cache are needed. There is no need to delete the unpacked VPK. Keep that for making any later changes.
  5. Test the sound via console command (sound is the root directory): play (sub-directory of sound folder)/<name of sound>
  6. Update sound.cache and repack the VPK in order to hear new or relocated sounds.

If a custom sound file is found at left 4 dead 2/left4dead2/addons/customsoundaddon/sound/ambient/testsound.wav:

  • Build sound.cache with snd_buildsoundcachefordirectory ../left4dead2/addons/customsoundaddon.
  • As a custom search path: add Game left4dead2/addons/customsoundaddon
  • As an addon: After building sound.cache, create customsoundaddon.vpk dragging the customsoundaddon folder to a shortcut of vpk.exe.
  • Test testsound.wav in-game, play ambient/testsound.

Some suggestions

Keep assets organized, separate, and as small as possible. Also, sounds in L4D2 are usually assigned using soundscripts. Start with at the least the following when developing with sounds:

  1. A separate search path containing custom sounds and sound.cache, as discussed above. You may combine or separate assets anyway and anywhere you like as long as the mounting path is added to gameinfo.txt.
  2. A map that can be loaded in-game, usually the map to ship or a test map - maps/<map name>.bsp
  3. A blank per-map soundscript (a .txt file) - maps/<map name>_level_sounds.txt.
  4. These files and folders will ultimately integrate with the map(s) and other assets for shipping as a single add-on/VPK.

Getting it to sound right

So the sound works in-game now... what next? The rest of the article covers just that:

Compatible file types, specs, and bugs

.wav is used extensively for official sounds. There are also some .mp3 files used as well, mostly for UI music.

Bug.png Bug:  (Tested Oct. 6, 2011) .mp3 files are currently known to suddenly stop playing for soundscript entry "Event.MissionStart_<Music Post-Fix String>" and with ambient_music. With ambient_generic, the Start Silent flag and StopSound input will not work for .wav and .mp3 if the is NOT looped flag is checked. The exact causes are unknown, the bugs may be inconsistent, and they are subject to change (for better or worse) as the game continues to receive updates.

In other words, the sound system in L4D2 is buggy but extensive testing will still give desired results... eventually.

Compatible specifications

Although you're not restricted to these, the following are known sample rates, bitrates, and channels that were used in official sounds:

  • .wav: 176, 353, 706 or 1411 kbps (doesn't have to be exact); 11, 22, or 44 kHz (must be exact); Stereo or Mono
Tip.png Tip: Use 16 Bit PCM format, as this is common in most audio software and is supported.
  • .mp3: 64 or 128 kbps; 44 kHz; Stereo or Mono

Location matters!

For example, the song to the rolling credits, music/unalive/themonsterswithin.wav, plays over almost every other sound. If that sound file (along with the soundscript entry) is moved to the different directory, the music will behave differently. The player will hear other sounds mixed into the ending credits, such as zombies moaning, survivor remarks, soundscapes, etc.

A feature called soundmixers may be the script behind priority/ducking of sounds. The location of a sound file within the sound directory dynamically controls what is played in the foreground and what is softened or muted. The script is located in scripts\soundmixers.txt within pak01_dir.vpk. See GCFScape for details on how to extract the script for viewing. To do: It doesn't seem to translate perfectly in-game, so it could be hard coded folder locations.

Note.png Note: Sound ducking (To do: is that correct terminology? priorities? ducking?) is not fully understood in this article. Soundmixers may or may not be a factor in determining the priority of songs. More information derived from testing or documentation is needed to fully document the way it works. For example, there is suspicion that there may be hard coding of directories involved (testing directories with the same priority attributes). New sound entry attributes only found in recent Source games may also contribute to sound priority.


Sounds that loop need to be looped with a third-party program. Please see Looping a Sound for details.

Looping examples: tank in-play music, motor engine, attacked by a hunter music, player-in-acid-pool music


Per-map soundscripts appear to be the only way to create custom or modified soundscript entries. Brand new soundscript entries can easily be created or an existing soundscript entry like Event.Tank can be safely overridden for a single map. When testing or shipping, the result is a maps folder that contains a <map name>_level_sounds.txt for every map within the campaign.

Open <map name>_level_sounds.txt with a text editor.

Please see L4D2 Soundscripts for more details. To do: Cover L4D2 soundscripts. What is unique to the game.

Soundscript entries

An entry can be played in-game via console or entity, such as ambient_generic or ambient_music. An example entry:

	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, wrap it in "quote marks".

Soundscripts are used frequently

All official in-game sound effects, vocalizations, and music rely on soundscripts to tweak the sound to the desired channels, volume, pitch, etc. With maps/<map name>_level_sounds.txt. You can customize existing entries without causing conflicts with other addons and official campaigns. Simply copy the entries you would like to change to the per-map soundscript.

Soundscript entries can be found in the scripts/game_sounds_*.txt folder by opening pak01_dir.vpk with GCFScape.

A lot of music entries rely on Map Properties > Post-Fix String found in Hammer and nav mesh attributes in-game. For example, the Post-Fix String of the map c5m1_waterfront.bsp is "BigEasy" and it plays its style of intro music in-game, where the nav mesh is marked PLAYER_START and CHECKPOINT.

Interesting soundscripts

All of them are interesting. Here are a couple of them:

  • game_sounds_music.txt provides great sample soundscript entries for music. Some entries string together different notes of the same instrument and are played randomly in succession.
  • game_sounds_physics.txt has entries for sounds that play during in-game interactions, such as a walking on snow or shooting a concrete wall.


Custom soundscapes in L4D2 appear to work well without the need to modify the official soundscapes manifest. They are "per-map" text files like soundscripts, but are instead located in the scripts folder: scripts/soundscapes_<map name>.txt. Soundscapes usually use .wav files, where looping is typically involved. .mp3 files may also work (looping not supported).

Soundscape entities

Official maps only use env_soundscape for level sound design. Other entities and methods may not work as intended. Feel free to experiment!


Testing a custom soundscript entry is as simple as creating an up-to-date sound.cache, restarting the game, and then playing the sound within a map. As noted in the add-on tutorial, sound.cache is built with the console command snd_buildsoundcachefordirectory ..\left4dead2\<location of sound folder>. When the sound cache is successfully created or updated, the console will output the number of sound files found in the add-on sound directory.

Note.png Note: There are other ways to confirm that sound.cache has been updated. Go the sound directory of that add-on and look at the time in which it was modified. You can even open sound.cache with a text editor to see if they contain sound files that are expected to be there.

With console

  1. Open <map name>.bsp
    map <map name> coop
  2. Test out the sound
    playgamesound entry.name
  3. In most cases, if a sound refuses to stop playing, stop the sound

With entities

  1. Create an ambient_generic, ambient_music, or any other entity that has a property that requires a sound name
    Tip.png Tip: For ambient_generic, if the sound file is programmed to loop (the actual sound file itself), then un-check the flag "is NOT looped" in order to be able to stop the sound from continuously looping with input StopSound. ambient_music does not have this flag and looping should work as intended.
  2. Change the targetname and change sound name to the soundscript entry of your choice
  3. Optional: create an entity that will trigger the sound, if necessary or desired
  4. Open <map name>.bsp via console
    map <map name> coop
  5. Test out the sound via "trigger entity" or console command:
    ent_fire <ambient_generic targetname> PlaySound
    Note.png Note: ambient_generic also features FadeIn and FadeOut inputs.
  6. In most cases, if a sound refuses to stop playing for any reason, stop the sound via console. Consider the bugs involved with these sound enties if you need to be able to StopSound with entity I/O.
    stopsound //This is a console command, looks just like the input for the two sound entities.

To do: extend testing: sounding right, unique music features in l4ds.


As mentioned in the L4D2 Campaign Add-on Tutorial, the final, and most likely separate, VPK will contain all the unique assets to your campaign or single map. In terms of custom sound, simply copy over the sound folder and per-map soundscripts that you have been working with. Congratulations on shipping!

See also

External links