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.pngTip: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.pngWarning: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.
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.
Warning.pngWarning:Sound.cache files for replacement sounds will not work when put into a .vpk!
Ex: Mods that swap sounds for longer ones require a sound.cache to work. But those Sound.Cache files only work as a loose file.

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:

Sound file compatibility

Icon-Bug.pngBug:As of Oct. 6, 2011, .mp3 files may suddenly stop playing for the soundscript entry Event.MissionStart_MusicPostFixString and the entity ambient_music. For the entity ambient_generic, the flag Start Silent and input StopSound will fail for all sounds if the is NOT looped flag is checked. The exact causes are unknown, and the side effects are inconsistent. This may change as the game is updated.  [todo tested in?]

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 (ffmpeg_format) Codecs (ffmpeg_codec) Codec profile Bit depth (bit) Sample rate (Hz) Bitrate (kbps)
.wav Mono
Stereo 		s16le adpcm_ms N/A 4* 44100
22050
11025 		Sample-rate dependent
pcm_s16le 16
u8 pcm_u8 N/A 8
.mp3 Mono
Stereo 		mp3 libmp3lame ABR
CBR
VBR 		N/A 44100
22050
11025 		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 without rebuilding the sound cache:

Extension Channels Format (ffmpeg_format) Codecs (ffmpeg_codec) Codec profile Bit depth (bit) Sample rate (Hz) Bitrate (kbps)
.wav Arbitrary s16le adpcm_ms N/A 4* Arbitrary Sample-rate dependent
pcm_s16le 16
u8 pcm_u8 8
.mp3 Mono
Stereo 		mp3 libmp3lame ABR
CBR
VBR 		N/A 44100
22050
11025
 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?
.wav Garbled playback N/A Garbled playback Incorrect playback speed N/A Normal playback if unlooped;
potential abnormal playback if looped 		Truncated playback No change
.mp3 Normal playback N/A Normal playback N/A 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.

Todo: It doesn't seem to translate perfectly in-game, so it could be hard coded folder locations.
Note.pngNote:Sound ducking (
Todo: 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.

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.

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

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

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.

Note.pngNote: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
    stopsound

With entities

  1. Create an ambient_generic, ambient_music, or any other entity that has a property that requires a sound name
    Tip.pngTip: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.pngNote: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.
Todo: extend testing: sounding right, unique music features in l4ds.

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

External links

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=L4D2_Custom_Sound_and_Music_Tutorial&oldid=308953"