Format:Krawall

The Krawall sound engine is an XM/S3M module player/tracker for the Game Boy Advance. Written by Sebastian Kienzl, it was used in various licensed games, such as The Lord of the Rings, Spider-Man, and The Sims.¹ Since 2013, the source code for the engine has been available on GitHub.² Krawall can be used to play background music in a game, as well as to play tracked single-activation jingles. The data is stored in the ROM as a set of samples, an optional set of instruments (depending on whether it's using S3M or XM modules), and one or more modules, with up to 256 patterns per module.

Signature#

Most ROMs with Krawall have a signature somewhere in the file that declares the presence of Krawall as well as the version. (Some retail ROMs have this stripped out. The Sims Bustin' Out is one example, though interestingly the Japanese release still has the signature.) The signature will likely look similar to the following in ASCII form:

$Id: Krawall $Id: version.h 8 2005-04-21 12:24:45Z seb $

Depending on the version, it may also be in a different format:

$Id: Krawall $Date: 2003/09/01 06:51:01 $

The first form of the string identifies the engine name (Krawall), the file the string came from, the build date of the version, and the creator ("seb", short for Sebastian Kienzl). The second form identifies just the engine name and build date.

This signature is a surefire way to detect the presence of Krawall in a ROM. If it is not present, you may need to use a more heuristic scan on the ROM to check for modules/samples. You can also look for seb's name in the credits.

Versions#

There have been various versions of Krawall since its initial release. The most recent version is 2005-04-21. The most important change that was made to the format was in version 2004-07-07, when the patterns were modified to allow more than 512 instruments and 255 rows. Make sure you know which version of Krawall is used by the ROM before ripping, as the two pattern formats are incompatible. Look for the signature in the ROM if present to find the version.

Known Versions

• 2003-09-01
• 2004-07-07
• 2004-09-17
• 2004-11-14
• 2005-04-21

Data Format#

Krawall stores its data in multiple places. Samples for all modules are stored in a single bank, as well as a separate bank for instruments if present. Both banks are indexed using a central array of pointers. Modules are stored individually, with pointers to each pattern at the end. Most of the data stored in each structure is analogous to a property in the comparable XM or S3M structure, so this makes conversion between the two/three formats easy.

All properties are stored in little-endian format. Pointers are stored as they would be addressed on the GBA, with a base address of 08000000. When converting down to ROM offsets, make sure to bitwise AND any pointers with 01FFFFFF. When converting up from ROM offsets, bitwise OR the offset with 08000000.

Samples#

Samples are stored as signed 8-bit PCM data, with an 18-byte header with a few properties relating to looping and frequency.

Pointers to all samples for a ROM are stored in a central pointer array. The index of each sample in this array is used for instrument sample assignments (in XM) or instrument selection in patterns (in S3M).

You can easily find samples in a ROM by opening it as raw data in Audacity or other program with signed (or unsigned if unavailable) 8-bit mono PCM at 16384 Hz. Look for the first sample of a region that appears to be audio, and backtrack 18 samples before that. Then seek to the position in the file equal to the sample position that you just got. This should be the beginning of a sample structure. Verify that the size property is valid, and if so you've now got a sample structure.

Once you have the position of a sample structure, it should be trivial to find the master sample table. Just search the ROM for the offset of the start of the sample structure (bitwise OR'ed with 08000000) as a little-endian 32-bit integer, and you should be able to find the rest of the table.

Instruments#

Instruments are used for modules converted from XM format. They can use multiple samples for different pitches to avoid distortion when playing a note that is much higher than the original sample. They also store volume and panning envelope information, as well as vibrato types. Instrument structures are always exactly 302 bytes in size. Some modules may not use instruments - check the flagInstrumentBased flag in each module to see whether instruments are required. Typically, modules converted from XM have instruments, while modules converted from S3M do not.

As with the sample structures, pointers to all instruments are kept in a central array to be referenced by the game/Krawall. The indices of the instruments in the array are used when playing back patterns.

Most of the data in the instrument structure is analogous to the XM format's instrument structure's fields. This is likely because instruments are only available when converting from the XM format, so it can stay the same for the most part. However, some semi-redundant data (like envelope loop end) was removed to save space.

Modules#

Modules store the metadata for each song. They contain the same sort of information as would be found at the top of an XM/S3M module file. Since Krawall handles both XM and S3M modules, there are some fields that are only useful for one of the formats and not the other. These will be noted in the table below.

Modules are directly referenced by the code, and thus do not have any sort of central pointer list. To find the offsets, you will need to either search the code regions for pointers to the module, or you can look for a block of data that roughly matches the format of the structure. One key characteristic is that there are often large regions of zero bytes in the order and songIndex arrays. You can try to search for these zero regions to find possible modules.

Patterns#

Patterns store the actual notes used in a module. They can be reused and rearranged in a module as needed. Patterns are split into a certain number of rows, which are played back at a set speed. There are two versions of the pattern format with some minor variations, so you'll need to make sure you're using the correct version before reading patterns. A pattern consists of some tracking indices, the number of rows, and packed pattern data.

The format of the packed data is very similar to S3M's packed data format. Each row is encoded as a list of note entries, with an initial channel/follow byte, followed by the data being set on the channel. A row can consist of zero or more entries with the most significant three bits denoting what's being set, and the least significant 5 bits denoting the channel. If the follow byte is 0, the row is finished and the next row is starting.

To decode the packed data:

1. Read a byte from the data
2. If the byte is 0, increment the row and restart the loop (if the row == rows, we're done)
3. If bit 5 is set (20): read two bytes for the note and instrument
   • If the version is >= 2004-07-07, the first byte is the note, and the second byte is the least significant byte of the instrument
     • If the high bit is set on the note, unset it and read in another byte for the most significant byte of the instrument
   • If the version is < 2004-07-07, the high 9 bits are the instrument, and the low 7 bits are the note
4. If bit 6 is set (40): read 1 byte for the volume (in XM volume column format, 10-50 for volume maps to 00-40 actual volume)
5. If bit 7 is set (80): read 2 bytes for the effect and effect parameter (listed below)
6. Write the data to the channel at the low 5 bits of the first byte (follow & 0x1F)
7. Repeat from the top

Effects#

These are the effects available in Krawall, as well as mappings to XM and S3M effects.

¹Effect is slightly incompatible with the conversion, you may need to adjust its behavior.
²Effect is only available in ModPlug/OpenMPT, it will not work in other trackers.

Tools#

To convert XM or S3M modules to Krawall format, the Krawerter program included in the Krawall sources should work well. This method was likely used by publishers to convert their music for games. To rip music from a Krawall ROM (or other compiled binary with Krawall data), UnkrawerterGBA by JackMacWindows can rip music into XM and S3M files.

Converting Modules to WAV/FLAC/MP3#

Since XM and S3M are module formats, to get playable audio files you will need to convert them using a tracker program. OpenMPT is recommended because it supports some special effects that are incompatible with the base specifications, but are implemented in Krawall and OpenMPT.

The following instructions will detail how to convert a module using OpenMPT.

1. Open the module file in OpenMPT.
2. Go to File => Stream Export (WAV, FLAC, MP3, etc.)...
3. Select your file type, sample rate, channel count, and bitrate under the Format box.
4. Select the loop type under the Limit box.
5. Optionally, add metadata under the Tags box.
6. Make sure Export To: File is selected, and click OK.
7. Browse to the destination, enter the file name, and click Save.
8. Wait for the audio to be rendered.

Once complete, the audio file will be located where you saved it.

References#