Sound and music tutorial
Custom sounds and music are common in SRB2 addons. This tutorial teaches you how to add them to WAD or PK3 files. If you want custom music to be played in your custom level, see the level header article.
Accepted sound formats
SRB2 v2.2 can play many different sound and music formats. Like Doom itself and Doom-based games and mods, SRB2 includes native support for the Doom Sound Format, though another widely used format for sounds is WAV (.wav). The most widely used format for music is Ogg Vorbis (.ogg), as it compresses well without much drop in quality. Ogg Opus (also .ogg, sometimes .opus) may be preferred due to its superior quality-to-size ratios and low latency, but it cannot be used for sound effects and is not as widely supported in other software – notably, SLADE does not recognize and cannot play back Opus files.
Below is a list of the formats supported by each of the sound/music libraries included with SRB2.
- Source: 
- MikMod MOD
- MIDI (Timidity, Fluidsynth or native Windows support)
- Ogg Vorbis
- Ogg Opus (music only)
- MP3 (SMPEG libraries)
- Source: 
- AY (ZX Spectrum/Amstrad CPC)
- GBS (Nintendo Game Boy)
- GYM (Sega Genesis/Mega Drive)
- HES (NEC TurboGrafx-16/PC Engine)
- KSS (MSX Home Computer/other Z80 systems – doesn't support FM sound)
- NSF/NSFE (Nintendo NES/Famicom ndash; with VRC 6, Namco 106, and FME-7 sound)
- SAP (Atari systems using POKEY sound chip)
- SPC (Super Nintendo/Super Famicom)
- VGM/VGZ (Sega Master System/Mark III, Sega Genesis/Mega Drive,BBC Micro)
- Source: 
- MOD (ProTracker)
- S3M (ScreamTracker 3)
- XM (FastTracker 2)
- IT (Impulse Tracker)
- MPTM (OpenMPT)
- Source: 
- Your sound or music file, which can be in any of the supported formats listed above. If your file is in an unsupported format, you need to convert it using additional software such as Audacity.
- A lump editor. SLADE is recommended for this, but this tutorial will also cover XWE where necessary.
- If you want to add a loop point to your music, you also need a media application capable of editing a file's information tags, such as Audacity.
You can use any of the supported formats listed above for your sound file. However, some MP3s may not work properly as sounds (though they may work fine as music), and Ogg with the Opus codec is only supported in music. Since sounds are usually short, you can safely use uncompressed formats such as WAV.
Choosing the lump name
Before you import your sound lump, you need to know how to name it. The names of sound lumps are prefixed by
DSSPIN. If you want to replace an existing sound, look up the name of the lump in question in the list of sounds and give your lump the same name. To find out which sounds you want to replace, you can preview SRB2's sound lumps, which are stored in the file
srb2.pk3. SLADE and XWE both have settings for filtering the lump list, by selecting "Audio" on the "Show" drop-down box, or with the "Sound" button, respectively. Now that only sound effect and music files are shown, select the sound effect you want to check from the list and click the play button, or if using XWE, select Wave → Play in the menu bar.
If you want to add a new sound without replacing an old one, you must declare a name for it via SOC or Lua. The game will then automatically reserve one of 1600 free slots for the new sound. The internal sound names used by SRB2 are in lowercase and use a
sfx_ prefix. For example, if the name of your sound lump is
DSCUSTOM, you must declare the sound as
sfx_custom. See Freeslot > Declaring freeslot names for a guide on how to declare custom sounds.
Importing the sound file
Now you can import your sound file into your WAD or PK3 file as a lump. Open the WAD or PK3 file with your lump editor. Now insert your sound file. In SLADE, you can simply drag and drop the file into the lump list. In XWE, select Entry → Load on the menu bar, navigate to the folder that contains your file and insert it. Once the file is imported, make sure the lump name matches the name you decided to use. If not, right-click on the lump and select Rename or Rename Entry, respectively.
Now save the WAD or PK3 file, close the lump editor (XWE saves automatically) and load the file in SRB2 for testing. If the sound isn't played, check if you gave your lump the correct name and, if necessary, declared the freeslot correctly.
Unlike sounds, music files are typically fairly long, so you should make sure the size of your file isn't too large. This isn't a problem with MIDI or module formats like MOD and XM, whose file size is already very small. Recorded music (formats like MP3 and Ogg), however, can become rather large when using a high bitrate. It is recommended that you use the Ogg format (which sounds better at low bitrates) with a bitrate of no more than 128 kb/s. Most of the music included with SRB2 is encoded in Ogg Vorbis at 64 kb/s. Unlike in sound effects, the Opus codec is supported in music as an even higher-quality alternative to Vorbis. This article will not cover how to convert to Ogg.
Choosing the lump name
Before you import your music lump, you need to know how to name it. Formerly, most music lumps in SRB2 went by the naming convention
O_MAPxxM, with xx being the two-digit form of the number of the map in which the music should be used; for map numbers above 99, extended map numbers were used. Not all music lumps followed this convention, for example
O_CHRSEL, used for the music on the character select screen. Currently, music lumps in SRB2 can be given any name as long as it starts with
D_. If you want to replace SRB2's own music, look up the name of the lump in question in the List of music article and give your lump the same name. For example, if you want to replace the music for Greenflower Zone Act 1, name your lump
Note that music lumps in the MIDI format start with the prefix
D_. The prefix
O_ is used for all other formats.
To find out which music you want to replace, you can preview SRB2's music lumps, which are stored in the file
music.dta. SLADE can play back Ogg Vorbis music itself, but if you're using XWE, you will need to export the file. To do this, select the music lump in question and select Entry → Save As... in the menu bar. If your music lump starts with
O_, you must save it as an Ogg file. Under "Save as type", select "All Files (*.*)" and then save your file as
filename.ogg. Don't forget the
.ogg extension, as your music file can't be opened without it. After saving the file, you can open it in a compatible music player.
For digital music formats that do not automatically loop, there is a way to supply an external looping point for the music. This will cause SRB2 to loop the music back to a predefined point once it finishes playing, rather than the beginning of the track.
There are three ways to set up a loop point. The first two involve using a dedicated metadata tag, while the last uses the file's
COMMENT metadata field.
The preferred way of setting a loop point is using the
LOOPMS metadata tag. When using
LOOPMS, the loop point should be supplied in terms of milliseconds. Audacity can insert this dedicated tag in the "Export" dialog. To do so, click "File" on the menu bar, click "Export", and select your preferred audio format. Then, after selecting the folder you want the audio file to be exported to, click the "New" button in the "Edit Metadata Tags" window. Input
LOOPMS as the name for the tag and input the desired time in milliseconds as the value (for example, 30.25 seconds equal 30250 milliseconds).
The other methods require that you supply the loop point in terms of audio samples. As SDL_mixer is incapable of providing an audio file's sample rate to the program, this is approximated by dividing the sample count by 44100 to get the position in seconds. This has the side effect of making the looppoint inaccurate to the actual sample count in files using sampling rates other than 44.1kHz, notably in files encoded with Opus which always uses a 48kHz sample rate by design. A crude way to calculate the value of the loop point would be to multiply the position where you want to place the loop point, in seconds, by 44100 – for example, to place the loop point for a file at 30.250 seconds, you would use 1334025 (= 30.25 × 44100) as the value. A more fine-grained method is to load the file in Audacity, identify the best position for the loop and then look up the precise sample number at which it occurs, but for files with different sampling rates, the Project Rate field in the bottom left of the window should be set to 44100.
The second method of setting a loop point is through another dedicated metadata tag, the
LOOPPOINT tag. You can add this tag the exact same way as the
LOOPMS tag; just use
LOOPPOINT as the name instead, and the number of samples as the value (
1334025 with our example).
The third and last method of supplying a loop point is to insert the text
LOOPPOINT=<value> in the
COMMENTS field of the music file, where
<value> is the number of audio samples as mentioned above (again,
1334025 with our example). This method for providing a loop point is deprecated and exists only for backwards compatibility with older versions.
Note that music modules and emulated music tracks use different built-in mechanics for looping the track – if you need to edit the loop point for such a track, you should consult a tutorial for the format in question. MIDI tracks cannot be looped in SRB2 at all.
Importing the music file
Now you can import your music file into your WAD or PK3 file as a lump. Open the WAD or PK3 file with your lump editor. Now insert your music file. In SLADE, you can simply drag and drop the file into the lump list. In XWE, select Entry → Load on the menu bar, navigate to the folder that contains your file and insert it. Once the file is imported, make sure the lump name matches the name you decided to use. If not, right-click on the lump and select Rename or Rename Entry, respectively.
Now save the WAD or PK3 file, close the lump editor (XWE saves automatically) and load your file in SRB2 to test the music. If the music isn't played, check if you gave your lump the correct name.
Crediting music in Sound Test (optional)
If you're creating something such as a Map mod intended to be distributed publically, and your map(s) uses some obscure music that you feel is worth crediting, then putting a MUSICDEF lump in your WAD or PK3 file is a decent way to achieve that. When viewing the in-game Sound Test with your mod loaded, a properly set-up MUSICDEF lump will allow your music to appear in the soundtrack list (after the base SRB2 music entries) by its given Title.
To start, create a new plain-text file (preferably with Notepad) somewhere on your computer, and name it "MUSICDEF". (You can also create a new blank entry in your WAD or PK3 file directly if you're using Slade, if you don't want to have to import this file later. But for ease of explanation, this tutorial will use the text-file method). Follow the instructions below for what to input in this text file, and how to format it.
For each music entry, start the line with
Lump, followed by a space, followed by the music file's lump name (i.e. the part of the filename that comes after the
O_ part, and not including the
.ogg part). Now make a new line and field named
Title = , and follow this with the display name you want this song to show as in the Sound Test menu. Make sure each word/etc. is separated with an underscore, not a space. The maximum character limit that the title ribbon in the Sound Test will display is 31 characters, but instead, try to keep the Title string no longer than 16 or 17 characters; the musical note icon that appears at the other end of the blue menu box may partially obscure the 17th character, and any characters beyond 17 will simply trail off of the menu. For the next line, you can optionally create a field named
Alttitle = . This is where you can put in an alternate name for the song, which will show up in the title ribbon alongside the original Title field. Otherwise, the next field should be
Authors = . This is where you will put the name(s) of the Composer(s) of the song in question, separating each artist's name with a comma (although this is technically not necessary; it's just nice for formatting). However, if you don't know this information, you can just remove this field entirely. For the next line, just leave
Soundtestpage = as
1. For the line after:
Soundtestcond = can just be
0 if you have no intention of making this song be an unlockable; otherwise, this number corresponds to the extended map number of the map which should be completed to unlock this song, or -- if the number is negative, a condition set. Refer to the MUSICDEF page for more information on this and other fields.
If the music is a jingle/only plays once/does not loop -- such as a Level Clear jingle or 1-Up jingle, you can add a
Stoppingtime = field, in which the number is the amount of time, in milliseconds, the song plays for. This will cause the track to automatically stop playing once the internal song timer reaches the specified point in milliseconds. It's important to note that 1 second of time is equal to 1000 milliseconds. Therefore, for a jingle that lasts for 20 seconds, you would put
20000 in this field; for a jingle that lasts 6 seconds, you would put in
The last field is
BPM = , or Beats per Minute. This is where you put in the tempo of the song; the bouncing radio/boombox graphic to the left of the Sound Test menu bounces up and down in relation to the value of this field. e.g. Greenflower Zone Act 1's music plays at a BPM of 132. If you're not sure how to find the BPM of your music, just experiment with tweaking this value until it seems fast or slow enough for your liking; it doesn't have to be exact. Ultimately this is another field that is also just for show; putting in
0 means it will not move at all.
Once you're done, save the text file and import it into your WAD or PK3. Its location in the archive does not matter.
A correctly-formatted MUSICDEF lump should look something like this:
Lump MYLMP1 Title = My_Music's_Name Alttitle = Alternate_Name Authors = My_Music's_Composer,_or_Composers,_Each_Separated_By_a,_Comma Soundtestpage = 1 Soundtestcond = 0 BPM = 120 Lump MYLMP2 Title = My_Jingle's_Name Alttitle = Alternate_Name Authors = My_Music's_Composer,_or_Composers,_Each_Separated_By_a,_Comma Soundtestpage = 1 Soundtestcond = 0 Stoppingtime = 7000 BPM = 140
Listening to music with SLADE
SLADE can play certain sound formats, such as Ogg Vorbis, MP3, WAV, and MIDI. Some other formats, such as VGM, cannot be played in SLADE and will appear as a lump of unknown type. This does not mean your VGM won't work, but be sure to add the file you're working on to SRB2 and test to see if the music works properly.