L4D2 Custom Sound and Music Tutorial

Introduction

Since the August 20, 2010 update, L4D2 fully supports custom sounds (custom sound cache named sound.cache). Initial instructions provided by Valve are available in the L4D2 Campaign Add-on Tutorial article. The rest of this article covers how custom sounds in L4D2 can be managed and tested during development and when shipping.

Getting started

Basic

Getting a custom sound to play is a simple process. Either add a custom wav file in an official sound folder or addon containing a sound folder. In both cases, sound.cache has rebuilt with snd_buildsoundcachefordirectory before testing. Keep in mind that rebuilding sound.cache of an addon is a lot faster since there are a smaller number of sound files to deal with. There's also the added benefit of easier file management.

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 the soundcache for add directory using in-game console: snd_buildsoundcachefordirectory ../left4dead2/addons/<name of VPK addon folder>
   Todo: Do you type in this command if your custom sounds - during development - are just inside the sounds directory?
4. Create the VPK
5. Test the sound via console command (sound is the root directory): play (sub-directory of sound folder)/<name of sound>

Todo: Does this mean that every time we want to just test a map with a custom sound we have to drag our whole custom map or campaign onto vpk.exe just to see if the custom sound works?

An example:

• The add-on directory has a custom wav file stored in ../customsoundaddon/sound/ambient/testsound.wav.
• sound.cache was built with command snd_buildsoundcachefordirectory ../left4dead2/addons/customsoundaddon.
• customsoundaddon.vpk was created by dragging the customsoundaddon folder to a shortcut of vpk.exe.
• testsound.wav was tested in-game, play ambient/testsound.

Warning:Currently, custom sounds will not work if any file is placed in the root of the sound directory. Please place custom sound files in a subdirectory instead.

Tip:This process may seem overwhelming considering the number of steps involved, but they are all small steps. Also keep the naming conventions simple to avoid any unforeseen consequences.

Recommended

The goal is to speed up the process of testing. Create the following:

1. An addon/VPK containing custom sounds and sound.cache, like above. Simply keep it separate from other content types during development/testing.
2. A map that can be loaded in-game named however you like - maps/<map name>.bsp
3. A blank per-map soundscript (a .txt file) named maps/<map name>_level_sounds.txt

Todo: Explain why or how this speeds up development?

Compatible file types and specs

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

Compatible specifications

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: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!

A feature called soundmixers manage the priority and volume of groups of sounds. The location of a sound file within the sound directory determines 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.

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

Warning:Sound priorities are not fully understood in this article. Soundmixers may not be the only factor that determines 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.

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.

Todo: 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:

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

Examples

Ambience.Siren
{
	channel		CHAN_WEAPON
	volume		VOL_NORM
	pitch		PITCH_NORM
	soundlevel	SNDLVL_NORM
	wave		siren1.wav
}

Arbitrary.Song
{
	channel		CHAN_AUTO
	volume		VOL_NORM
	pitch		PITCH_NORM
	soundlevel	SNDLVL_NORM
	wave		music/singalongsong.wav
}

Foo.Song_mp3
{
	channel		CHAN_STATIC
	volume		VOL_NORM
	pitch		100
	soundlevel	SNDLVL_NORM
	wave		music/songalongdong.mp3
}

Official Sound and Music Uses Soundscripts

All official in-game sound effects, vocalizations, and music rely on soundscripts to tweak the sound to the correct channels, volume, pitch, etc. With maps/<map name>_level_sounds.txt, you can customize those entries without causing conflicts with other addons and the 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 and nav mesh attributes. 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

They're all interesting, but 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 during development or when shipped as a VPK (named as a per-map soundscape).

Please see:

• env_soundscape
• env_soundscape_triggerable
• trigger_soundscape

Note:Official maps exclusively use env_soundscape for soundscapes. Other entities and methods may not work as intended. (Question: What other entity would one use, other than env_soundscapes, to create a soundscape? Ambient_generics are not "soundscapes".)

Todo: thoroughly test vpks with custom per-map soundscapes with other users or computers

In short, custom soundscapes in L4D2 are text files located in the scripts folder, named "per-map" as scripts/soundscapes_<map name>.txt
There is nothing different about preparing the sound files in order for the soundscapes to play, although using .MP3 files for soundscapes would be unusual there is typically looping involved.

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.

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.

By 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
   

   stopsound

By Entities

1. Create an ambient_generic, ambient_music, or any other entity that has a property that requires a sound name
   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, but it is not necessary.
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

6. In most cases, if a sound refuses to stop playing, stop the sound via console
   

   stopsound

Shipping

See L4D2 Campaign Add-on Tutorial.

See also

• L4D2 Campaign Add-on Tutorial - Creating a sound.cache file
• ambient_generic
• ambient_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