View source for User:Popcorn/Dynamic Laser Music

{{Background|file=Prop laser relay2.jpg|opacity=0.15}}
{{User:Popcorn}}
This article is about the full process of adding synchronized looping music to a map in {{portal2|4}} 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 {{src|4}}. If your game supports [[Operator Stacks]] and custom [[soundscripts]], this article may be interesting for you aswell. I learnt a lot about how [[Sound and Music|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 {{ent|ambient_generic}} to the map for each music file playing a custom [[soundscript]] entry, and trigger them appropriately,
* create those custom soundscript entries in <code>maps/<mapname>_level_sounds.txt</code> 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 [https://musescore.org MuseScore] and [https://lmms.io 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.<br>
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 <code>measures * beats_per_measure / bpm * 60 s/min</code> 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.
{{seealso|[[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 [https://www.audacityteam.org/download/ Audacity] and [https://ffmpeg.org/download.html 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 ===
{| style="background:rgba(255,255,255,0.05); border:1px solid #888; padding:.5em 1em"
|
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 <code>bit_depth * sample_rate * number_of_channels</code>. For 16 bit PCM, 44100 Hz mono, you get <code>16 * 44100 * 1 = '''705''',600</code> or for stereo <code>16 * 44100 * 2 = '''1,411''',200</code>. 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|1=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 <code>5 * (44100*16*2) Bit/s * 80 s / 8 Bit/Byte = 70.56 MB</code> 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 <code>%LOOP_LENGTH%</code> appropriately. You must replace <code>"ffmpeg"</code> with the path to <code>ffmpeg.exe</code> if you don't have the <code>%PATH%</code> environment variable set to include the FFmpeg installation folder.
:<syntaxhighlight lang=batch>
@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
</syntaxhighlight>

=== Loop marker ===
[[Looping a sound]] file (in its entirety!) on Windows is as easy as creating a text file with [[Looping a sound#Windows|text to paste in]], save as <code>.bat</code> and dragging the files on it.<br>
But you can use [https://wavosaur.com Wavosaur], too: Open the program, drag a WAV file in, double click the waveform to select all, press {{key|L}}, save with {{key|Ctrl|S}}, close the internal waveform window and then the entire program (works for {{csgo}}).<br>

Source loops audio files ONLY based on the loop marker in the file. The spawnflag <code>Is NOT looped</code> seen in <code>ambient_generic</code> 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 <code>"cue "</code> (batch file) or <code>"smpl"</code> (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 ==
{{Background|file=1024 thermaldiscouragement.jpg|opacity=0.06|mode=1}}
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 <code>ambient_generics</code> 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 <code>common/null.wav</code>. Note that playing an undefined soundscript entry will play the default error sound, typically <code>error.wav</code> ({{hl2}} ''"Ooh, fiddlesticks, what now?"'').

As this is sound design, there may not be much to do. We need to add an {{ent|ambient_generic}} for each music file and trigger it appropriately.
The location of the <code>ambient_generic</code> 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 <code>ambient_generic</code> using soundscripts, which will be discussed below.

{| style=background:transparent
|
[[File:Ambient_generic.png|left|link=]]
|
 {| class=standard-table
 |+ style=white-space:nowrap| Object properties: ambient_generic
 ! Name
 | Music.Laser
 |-
 ! Sound name
 | music.l0
 |-
 ! Flags
 | &#9745; Start Silent<br>&#9744; 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 <code>ambient_generic</code> anyway!}}
|}
Since we talk about looping music, all of them should have the <code>Is NOT looped</code> flag set to false. It is probably good practice to have them <code>Start Silent</code> 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:
* <code>music.b0</code>, <code>music.b1</code>, ... for base music where at most one of them should play at once,
* <code>music.x0</code>, <code>music.x1</code>, ... for additional music intended to be played on top of <code>b0</code> etc.,
* <code>music.l0</code>, <code>music.l1</code>, ... like <code>x0</code> etc. but for laser catchers/relays.


The base music for example can be started and stopped by a {{ent|trigger_once}}, while the laser music should be triggered using a {{ent|prop_laser_catcher}} or {{ent|prop_laser_relay}} entity using outputs.
{| {{OutputsTable|sortable=0}}
|+ '''Outputs of each laser catcher/relay'''
| [[File:Io11.png]] || OnPowered || Music.Laser || PlaySound || || 0.00 || No
|-
| [[File:Io11.png]] || OnUnpowered || Music.Laser || StopSound || || 0.00 || No
|}
{{note|Depending on the soundscript entry, <code>StopSound</code> 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 <code>ambient_generic</code> 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 <code>common/<Game Name>/sdk_content/maps/<mapname>.txt"</code> along the [[VMF]] listing all files to pack, alternating between internal (<code>/</code>) and external (<code>\</code>) paths:
<pre>
sound/music/track_01.wav
C:\...\sound\music\track_01.wav
</pre>
Add a new compile option in expert mode before the default ''Copy File'' option: Command: <code>$exedir\bin\bspzip.exe</code>, parameters: <code>-addlist $path\$file.bsp $path\$file.txt $path\$file.bsp</code>

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 <code>maps/<mapname>_level_sounds.txt</code> and create an entry for each soundscript entry that you used earlier as the sound name for the <code>ambient_generic</code> entities.
The following is an example for background music <code>"music.b0"</code>, laser music synchronized to it <code>"music.l0"</code> and an unused sound entry <code>"music.b1"</code>. 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'' [[Soundscripts#Sound characters|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 &ndash; and if that starts badly synchronized, it would stay that way, bugging our ears.}}


:{{Expand|title=<code>maps/<mapname>_level_sounds.txt</code>|noborder=1|
<syntaxhighlight lang=php>
// 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"
}
</syntaxhighlight>
}}

== Testing ==
If everything went well, the music should play as intended.
{| class=wikitable
! Console command !! Comment
|-
| <code>cl_precacheinfo</code><br><code>sv_precacheinfo</code> || Check whether the game has loaded your custom sound files.
|-
| <code>sv_soundemitter_flush</code> || Whenever you change something in the soundscript, reload the soundemitter.
|-
| <code>playgamesound</code> || Play your soundscript entries without having to play the map. Note: Any sounds will "play everywhere" this way!
|-
| <code>stopsound</code> || 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.