User:Popcorn/Dynamic Laser Music

This article is about the full process of adding synchronized looping music to a map in Portal 2 for laser catchers or laser relays as they are activated by a laser beam.

Not much of this article is specific to Portal 2. It is mainly specific to sound editing, music and the sound system in Source. If your game supports Operator Stacks and custom soundscripts, this article may be interesting for you aswell. I learnt a lot about how sound works in Source when I made this, so if you're interested, read along. Some information on this page should probably also be on other pages about sound where it's missing, but I've yet to find the right places.

Overview

The result should be a map with some looping base background music as well as additional looping music emitted from laser catchers, synchronized to the base music, turning on and off.

The process we will undergo is to...

create music, export audio files, loop them,
add an ambient_generic to the map for each music file playing a custom soundscript entry, and trigger them appropriately,
create those custom soundscript entries in maps/<mapname>_level_sounds.txt which will use Operator Stacks,
test them in-game.

Composing music

First off, we need music files to work with. If you already have them, you can skip this section.

The programs I have used to create music so far are MuseScore and LMMS as well as other MIDI software for editing, playing and converting MIDIs.

Create a looping section and add instruments or whatsoever that you can turn on and off, especially when exporting. Remember that you want files with the same length in the end.
One problem that may arise if you work with reverb for example, you have trailing sound after the loop that may be cut off when looping back. That needs to be mixed to the beginning of the loop. One solution is to export the sound WITH the trailing reverb, i. e. longer than the actual loop, and to edit the sound later to remedy that, see the next section. Try to get the loop length in milliseconds (or even samples), or find the bpm and the number of measures to be able to calculate it as if it had no trailing reverb: The loop length is measures * beats_per_measure / bpm * 60 s/min seconds.

In case you intend music tracks to be played simultaneously, then you should keep in mind that the Source engine is the system that will finally mix your audio files by simply summing them. This means that you may want the audio signal to not clip at any point, or at least not noticeably. Try to avoid using compression when playing multiple of the individual music tracks in your DAW such that it will sound the same in-game.

You most likely want music to be stereo since it offers a better experience especially for headphone users. It's good to know whether some part of the music will be played either "everywhere" or from a specific location in the 3D world (spatialized). In the latter case, mono music is sufficient, which you can already regard when composing music.

Finally, keep the number of channels per file in mind to avoid surprises later.

See also: Music Composition

Preparing audio files

At this point, we have music files and must ensure that Source will accept them.

Software I use to edit audio files are Audacity and FFmpeg.

We're assuming that we have music files of the same length that, if played simultaneously and started at the same time, sum up to the "full" music track.

File requirements

For synchronized music, the audio files "should" be...

WAV, sample rate 44100 Hz, 16 bit PCM, stereo or mono,
exactly the same length,
looped,
sounding good when looping.

Most of the above audio file properties can be confirmed on Windows by checking the file properties:

file type: Wavesound (.wav)
bitrate of 1411 kBit/s (stereo) or 705 kBit/s (mono)
same file size in bytes among the files

The bitrate equals bit_depth * sample_rate * number_of_channels. For 16 bit PCM, 44100 Hz mono, you get 16 * 44100 * 1 = 705,600 or for stereo 16 * 44100 * 2 = 1,411,200. A sample rate of 48000 Hz or a bitrate of 24 bit, which don't work in Source, would yield different numbers. 22050 Hz works, too, which comes with half the file size but worse quality (~352 kBit/s).

Warning:The music you want to play in Source cannot be indefinitely long. At first I tried playing five stereo tracks, 1:20 min each, simultaneously in-game and I was wondering why the game started to lag hard and not play any sound. Apparently I overwhelmed the audio system's buffers such that it couldn't play anymore (that's 5 * (44100*16*2) Bit/s * 80 s / 8 Bit/Byte = 70.56 MB of cache). Since I wanted two pairs of files to always together anyway, I combined them to one file, leaving me with only three files, and since the fifth one was spatialized in-game, it could be mono, cutting its file size in half. Altogether I halved the data in size, which in the end made my idea work at all.

Editing

Either way, you should take a look at the file in Audacity:

Ensure that the file loops properly. Play the track with (Audacity-)loop points enabled (right click on timeline or use/edit keybinds for setting/clearing loop points).
- Remove unintended preceding or trailing silence in case the loop is slightly too long.
- Wherever you hear a "crack", there is probably a "jump" in the waveform. Locate it, select a few samples in a region around it and Effects > Repair.
- If there is a crack when looping from the end to the beginning (and even if not), add a very short fade in and fade out at the beginning and end, only like 10-20 samples long.
If the music you have opened will be played spatialized, mono may be sufficient. Duplicate your stereo track, mix the copy down to mono, play and compare the two. If the mono track is fine (or identical), then use that, which saves file size.
Ensure you export the file with one of the above file formats. When exported, open and play the file to check the beginning and end.

Wrapping trailing sound to a loop

If you have music files with trailing reverb that should be wrapped to the beginning, you should edit the audio file.

Using Audacity: Open the file (better: all audio files at once), select the loop length (that you hopefully found out) from the beginning, split all clips at that time, move the trailing sound of one file to a new track (cut, new track, paste), shift it to the beginning (if it isn't there already) and merge the track with the original track it belongs to; Do that for each file.
Using FFmpeg: Create a batch file that calls FFmpeg and adjust the duration %LOOP_LENGTH% appropriately. You must replace "ffmpeg" with the path to ffmpeg.exe if you don't have the %PATH% environment variable set to include the FFmpeg installation folder.

@echo off
rem Drag-drop WAV files on this batch file to create a new WAV from it that wraps the sound at the specified time.
rem Unintended silence at the beginning is bad. The resulting audio length (-t %LOOP_LENGTH%) is the loop length.
rem We split each file at the specified time into two parts named [start] and [end] and mix them back together.
set "LOOP_LENGTH=40.0s"

for %%F in (%*) do (
	ffmpeg -loglevel quiet -i "%%~F" -filter_complex "[0:a]atrim=end=%LOOP_LENGTH%[start];[0:a]atrim=start=%LOOP_LENGTH%[end];[start][end]amix=duration=first:inputs=2:normalize=0:dropout_transition=0" -t %LOOP_LENGTH% "%%~dpnF_wrap.wav"
	echo Created wrapped file: %%~nF_wrap.wav
)
pause

Loop marker

Looping a sound file (in its entirety!) on Windows is as easy as creating a text file with text to paste in, save as .bat and dragging the files on it.
But you can use Wavosaur, too: Open the program, drag a WAV file in, double click the waveform to select all, press L, save with Ctrl+S, close the internal waveform window and then the entire program (works for ).

Source loops audio files ONLY based on the loop marker in the file. The spawnflag Is NOT looped seen in ambient_generic entities makes it seem like you had a choice, but you don't. The engine needs it to start and stop the audio file properly.

Audio files can also be looped differently. If the loop marker is not at the beginning of the file, then playing the file will start at the very beginning. When the end is reached, Source will skip back to the loop point, continuing to play until the end is reached etc.

Any WAV file with a loop marker does contain the four (!) ASCII characters "cue " (batch file) or "smpl" (Wavosaur loop). If a file doesn't contain any of the two, it has no loop point. Can be tested by opening the audio file with a text editor and searching for those two strings.

Mapping

The following is what needs to be done in the map editor in Hammer. In fact, this can already be done even if the exact music is not known yet. The musician can add "music hooks" to the map by adding and triggering ambient_generics that refer to undefined soundscript entries. This way, the musician can still work on the soundscript to define those soundscript entries and thus the music that will play, without having to edit the map. Adding too many "music hooks" is not a problem since you can define soundscript entries to play the null sound common/null.wav. Note that playing an undefined soundscript entry will play the default error sound, typically error.wav ( "Ooh, fiddlesticks, what now?").

As this is sound design, there may not be much to do. We need to add an ambient_generic for each music file and trigger it appropriately. The location of the ambient_generic entities does not matter. This may be obvious for music playing "everywhere" but even the others can later be manipulated to play from a different location other than the origin of the ambient_generic using soundscripts, which will be discussed below.

Object properties: ambient_generic
Name	Music.Laser
Sound name	music.l0
Flags	☑ Start Silent ☐ Is NOT looped

Important:Nothing else needs to be set. Sound properties (volume, pitch, ...) set in the soundscript entry "music.l0" (etc.) that we define later, will override any properties set in the ambient_generic anyway!

Since we talk about looping music, all of them should have the Is NOT looped flag set to false. It is probably good practice to have them Start Silent and trigger them explicitly.

The targetname "Music.Laser" is absolutely arbitrary and will only appear in the map file. It can also be the same as the soundscript entry name. The only important thing is that the name is not confusing.

We must play soundscript entries. We definitely do not want to play the raw sound file since those cannot be synchronized with Operator Stacks. For now, the soundscript entry names can be chosen arbitrarily and we define them in a text file later. The names are also absolutely arbitrary but it seems that Mike Morasky tried to use some naming pattern when creating the music soundscript entries for Portal 2:

music.b0, music.b1, ... for base music where at most one of them should play at once,
music.x0, music.x1, ... for additional music intended to be played on top of b0 etc.,
music.l0, music.l1, ... like x0 etc. but for laser catchers/relays.

The base music for example can be started and stopped by a trigger_once, while the laser music should be triggered using a prop_laser_catcher or prop_laser_relay entity using outputs.

**Outputs of each laser catcher/relay**
	My Output	Target Entity	Target Input	Parameter	Delay	Only Once
	OnPowered	Music.Laser	PlaySound		0.00	No
	OnUnpowered	Music.Laser	StopSound		0.00	No

Note:Depending on the soundscript entry, StopSound can also initiate a fade out.

Making sounds accessible to the game

In Portal 2, it was necessary for me to pack custom audio files to the map file. Otherwise the game can't play them because it would normally not precache anything beyond the game_sounds_manifest.txt (apart from map-specific soundscapes and such). This was never a problem for me in CS:GO though, apparently because you can use custom sounds only as RAW audio files in ambient_generic entities, which the game seems to precache. Custom soundscripts seem to be a different story, which mapmakers can't use in CS:GO.

To pack sounds to the map when compiling, you can create a compile option for that. To use BSPZIP, create a text file common/<Game Name>/sdk_content/maps/<mapname>.txt" along the VMF listing all files to pack, alternating between internal (/) and external (\) paths:

sound/music/track_01.wav
C:\...\sound\music\track_01.wav

Add a new compile option in expert mode before the default Copy File option: Command: $exedir\bin\bspzip.exe, parameters: -addlist $path\$file.bsp $path\$file.txt $path\$file.bsp

You can also use a third party tool such as VIDE or AutoBSPpackingTool.

Soundscript

If you're done with the above, this is the point where we can keep the game open to test the soundscript that we're writing.

Create the text file maps/<mapname>_level_sounds.txt and create an entry for each soundscript entry that you used earlier as the sound name for the ambient_generic entities. The following is an example for background music "music.b0", laser music synchronized to it "music.l0" and an unused sound entry "music.b1". There are more sound operators you can override and use, see Soundscripts/Operator Stacks#Music.

Todo: The following doesn't seem to yield consistently synchronized music. I have a map with one base music track (b0, stereo), one laser music (l0, mono) and an extension of the base music (b1, stereo), all three part of one piece of music (80 s each): Playing b0 and l0 together seems to be fine, but whenever b1 joins in, it's never entirely synchronized to b0, even if turned off and on again. Does that have to do with the stream sound character? Does that have to do with load times? Playing some music file for the first time? Note that the l0 is turned on and off during gameplay, while b1 is only started once – and if that starts badly synchronized, it would stay that way, bugging our ears.

// base background music, stereo, plays everywhere
"music.b0"
{
	channel    CHAN_STATIC
	soundlevel SNDLVL_NONE // "play everywhere"
	volume     1.00
	wave       "*music/track_01.wav" // note the * prefix
	soundentry_version 2
	operator_stacks
	{
		update_stack
		{
			import_stack "update_music_stereo"
			
			volume_fade_in
			{
				input_max 16.0 // fade in time in seconds
			}
		}
	}
}

// laser catcher music, mono, plays from a specific place
"music.l0"
{
	channel    CHAN_STATIC
	soundlevel SNDLVL_80DB // don't "play everywhere"
	volume     1.00
	wave       "*music/track_02.wav" // note the * prefix
	soundentry_version 2
	operator_stacks
	{		
		start_stack
		{
			import_stack "start_sync_to_entry"
			elapsed_time
			{
				entry "music.b0" // essential!
			}
			duration_div
			{
				input2 1 // length. use 1 for same length
			}
		}
		
		update_stack
		{
			import_stack "update_music_spatial"
			dsp_output
			{
				input_float 0.2 // dsp volume, 0-1
			}
			speakers_spatialize
			{
				input_radius 100 // radius outside which the sound becomes directional
			}
		}
	}
}

// a sound entry that was added to the map, but which ended up not being
// needed. however, we need to define the entry and play something silent,
// otherwise if an ambient_generic is told to play a sound entry that
// doesn't exist, the game plays some audible default error sound instead
"music.b1"
{
	channel    CHAN_STATIC
	soundlevel SNDLVL_NONE
	volume     1.00
	wave       "common/null.wav"
}

Testing

If everything went well, the music should play as intended.

Console command	Comment
`cl_precacheinfo` `sv_precacheinfo`	Check whether the game has loaded your custom sound files.
`sv_soundemitter_flush`	Whenever you change something in the soundscript, reload the soundemitter.
`playgamesound`	Play your soundscript entries without having to play the map. Note: Any sounds will "play everywhere" this way!
`stopsound`	Stop all sound, especially looping sounds started from the console that can't be stopped otherwise.

Thanks for reading, I hope you found something useful.

User:Popcorn/Dynamic Laser Music

Contents

Overview

Composing music

Preparing audio files

File requirements

Editing

Wrapping trailing sound to a loop

Loop marker

Mapping

Making sounds accessible to the game

Soundscript

Testing

Navigation menu

User:Popcorn/Dynamic Laser Music

Overview

Composing music

Preparing audio files

File requirements

Editing

Wrapping trailing sound to a loop

Loop marker

Mapping

Making sounds accessible to the game

Soundscript

Testing

Navigation menu

Search