L4D2 Custom Sound and Music Tutorial

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:
#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.
#Build a new sound.cache in that folder with snd_buildsoundcachefordirectory before testing 
;Option 1 - As a custom search path:
#Create a directory anywhere with a sound sub-folder.
#Add the directory path in gameinfo.txt found at "..\left 4 dead 2\left4dead2\gameinfo.txt"
#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.
#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
#Restart client.
#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:
#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"
#Create another folder within the sound folder. This is where sounds can be stored. 
#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.
#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.
#Test the sound via console command (sound is the root directory): play (sub-directory of sound folder)/<name of sound> 
#Update sound.cache and repack the VPK in order to hear new or relocated sounds.
;Example
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:
#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.
#A map that can be loaded in-game, usually the map to ship or a test map - maps/<map name>.bsp
#A blank per-map soundscript (a .txt file) - maps/<map name>_level_sounds.txt. 
#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:
* Compatibility and current bugs
* Sound file location
* Looping
* Soundscripts
* Soundscapes
* Testing
== Sound file compatibility ==
The game can playback both WAV and MP3 files only if they have a sound cache entry.
=== Sound cache compatibility ===
As of version 2.2.2.6, you can build the sound cache for sound files with these properties:
Extension	Channels 	Format ()	Codecs ()	Codec profile	Bit depth (bit)	Sample rate (Hz)	Bitrate (kbps)
 	MonoStereo	 	 	N/A 	4* 	441002205011025 	Sample-rate dependent
 	MonoStereo	 	 	N/A 	16 	441002205011025 	Sample-rate dependent
 	MonoStereo	 	 	N/A 	8 	441002205011025 	Sample-rate dependent
 	MonoStereo	 	 	ABRCBRVBR 	N/A 	441002205011025 	32‒320
=== Replacement sound file compatibility ===
Many L4D2 mods replace existing sounds without packaging a sound cache.
This is the only option if you want to avoid having your users modify game files directly, since addon sound caches have the lowest priority and are overridden by higher-priority sound caches.
As of version 2.2.2.6, the engine will happily accept replacement sound files with these properties :
Extension	Channels 	Format ()	Codecs ()	Codec profile	Bit depth (bit)	Sample rate (Hz)	Bitrate (kbps)
 	Arbitrary 	 	 	N/A 	4* 	Arbitrary 	Sample-rate dependent
 	Arbitrary 	 	 	N/A 	16 	Arbitrary 	Sample-rate dependent
 	Arbitrary 	 	 	N/A 	8 	Arbitrary 	Sample-rate dependent
 	MonoStereo	 	 	ABRCBRVBR 	N/A 	441002205011025 	32‒320
If you want your replacements to playback "normally", you are constrained by information in the sound cache entry of the original sound:
* file size
* sound length
* loop points (if WAV)
* sample rate
* channels
Your replacement's properties should be close, if not identical, to the original's to prevent abnormal playback.
The following will occur if you attempt to play a replacement sound without rebuilding the sound cache:
Extension	Changed number of channels?	Changed format? 	Changed codec? 	Changed codec profile?	Changed bit depth?	Changed sample rate? 	Changed bitrate?	Smaller than original? 	Larger than original?	Changed loop points?
 	Garbled playback 	Garbled playback	Garbled playback	N/A 	Garbled playback 	Incorrect playback speed	N/A 	Normal playback if unlooped;potential abnormal playback if looped	Truncated playback 	No change
 	Normal playback 	N/A 	N/A 	Normal playback 	N/A 	Normal playback 	Normal playback 	Normal playback 	Truncated playback 	N/A
==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. 
==Looping==
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
==Soundscripts==
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.
===Soundscript entries===
An entry can be played in-game via console or entity, such as ambient_generic or ambient_music. An example entry:
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, 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.
==Soundscapes==
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).
Because Soundscapes are "Per Map" every single map of a campaign needs one.
To avoid copy-pasting the entire script and keeping track of changes across all soundscape files, you can create a "master" soundscape which has all the content it needs, while all other soundscript files simply "include" the master script. So all changes in the master are automatically loaded into all other scripts.
like so:
#include "soundscapes_mymap_master.txt"
;Soundscape entities
*env_soundscape
*env_soundscape_proxy
*env_soundscape_triggerable
*trigger_soundscape
Official maps only use env_soundscape for level sound design. Other entities and methods may not work as intended. Feel free to experiment!
==Testing==
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.
===With console===
#Open <map name>.bspmap <map name> coop
#Test out the soundplaygamesound entry.name
#In most cases, if a sound refuses to stop playing, stop the soundstopsound
===With entities===
#Create an ambient_generic, ambient_music, or any other entity that has a property that requires a sound name
#Change the targetname and change sound name to the soundscript entry of your choice
#Optional: create an entity that will trigger the sound, if necessary or desired
#Open <map name>.bsp via consolemap <map name> coop
#Test out the sound via "trigger entity" or console command:ent_fire <ambient_generic targetname> PlaySound
#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.
==Shipping==
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==
*L4D2 Campaign Add-on Tutorial - Creating a sound.cache file
*ambient_generic
*ambient_music
*List of L4D2 Campaign Music
*Looping a Sound
*Music Composition
*Sound and Music
*Soundcache
*Sound Download Sites
*sound_mix_layer
*Soundscapes
*env_soundscape
*env_soundscape_triggerable
*trigger_soundscape
*Soundscripts
*Category:Sound System
==External links==
*Gamasutra Game Audio Theory: Ducking - 'Ducking', or lowering the audioscape volume, can create greater engagement for listeners.
*Podcast 17 Mike Morasky Interview - Discussion about audio production and insight into the evolution of the sound system.
Category:Left 4 Dead 2
Category:Sound System
Category:Tutorials