::|CONTENTS
- Capabilities
- Quick set up
- Expert tricks
- Links for further development
- See also
Maxmod is a sound engine for the Game Boy Advance and the Nintendo DS. Its core feature is to play songs from .s3m, .xm, .mod and .it modules.
It's available for Windows, macOS and Linux as a part of the devkitPro framework.
Capabilities
You can find a detailed list of Maxmod capabilities as well as the API reference on the Maxmod
website.
Quick set up
Go to the devkitPro install page and follow the instructions for your operating system:
https://devkitpro.org/wiki/Getting_Started
devkitPro as a lot of components, corresponding to different consoles. To use Maxmode, you will only need the Game Boy Advance and/or the Nintendo DS libraries, depending on the console you're interested in.
Configuration (Game Boy Advance)
In this part, we will see how you can use Maxmod to generate a simple GBA ROM capable of playing your module files.
For this you will need a module file. You can read section "Composing" to see how to make valid module files but for now, using this
example module will be enough.
The command line
On Windows, you will use MSYS2, this application creates an environment similar to Linux inside Windows. You won't need to install anything as the Windows version of devkitPro is bundled with it's own modified version of MSYS2.
Launch MSYS2 from the Start menu, it will open a shell. On Linux and macOS, simply start a shell session instead.
Enter the command:
cd Documents
Press return to execute the command, I won't repeat it but you'll need to do the same for any other command. Note that your Documents folder will be named differently depending on your computer language, please adapt it to your localization.
Enter the command:
ls
It will display the content of your Documents folder! Actually, MSYS2 works in some ways like the file explorer but with a text interface. Instead of using the mouse, you interact with it by entering commands, for instance:
ls: display the content of the current folder
cd <folder name>: open a directory named <folder name> (cd stands for "change directory")
Now using the file explorer, move your module file to Documents if it was not already here and enter the command
ls again. It should show you the module file among your usual files and directories.
Making the ROM
To generate a GBA ROM, use the following command:
mmutil -b FlatOutLies.mod
Here we supposed your module is called FlatOutLies.mod (which should be the case if you downloaded the example from above). Change it to your module name if it's not the case.
If everything went correctly, you should see a Game Boy Advance ROM called FlatOutLies.gba. Open it in an emulator!
It will show you a music player. Press A to play your song, press B to stop it.
Note: here we took care to go to Documents using the command cd. It is because you need to be in the same directory as your module file in order to use the command mmutil as shown above.
Composing (Game Boy Advance)
Compatible features
While Maxmod supports most of the features from the different module formats, it has some limitations:
- you can't use more than 32 channels
- using stereo samples will result in an error while making the ROM
- filter envelopes will be ignored (without causing any error)
- Note off command (~~): no error but will make a glitchy sound instead of note fading in the GBA ROM
- Panning slide effects (P0x and Px0) as well as panbrello (Yxy) don't work
- Putting a volume command (v64) on the same row as a note off (^^) will make the note-off not work
On the contrary, you can use these noticeable features:
- volume, panning and pitch envelopes
- NNAs
- Portamento (Exx, Fxx), Set panning (Xxx), Vibrato (Hxx)
Note: as far as we know, there is no documentation listing all the effects and other features from DOS modules you can use in Maxmod. This means you will have to learn by experimenting. If you find something that should be added to the two lists from above, please edit this page or leave a post on the "Discussion" tab.
8-bit samples
The Game Boy Advance only supports 8-bit samples. You can still use 16-bit samples as Maxmod will automatically convert them to 8-bit while making the ROM.
However, you may prefer to convert your samples to 8-bit by yourself as it will make the sound of your module closer to what you will hear from the GBA ROM. This can be done by using
MODPlug Tracker (right-click in the sample area) or
Audacity.
In addition, converting samples to 8-bit may create noticeable hissing. You can prevent it (or at least make it less audible) by normalizing your samples before converting them to 8-bit. Again, OpenMPT and Audacity are both capable of normalizing samples.
Expert tricks
In this section, we will see a way to compile GBA ROMs without using the mmutil utility. While this new process is more complicated, you may want to try it for the following reasons:
- This is a good training about modifying example code, this method is also used to set up the
Krawall sound engine.
- As we will access directly to the source code of the ROM, you can customize it as much as you want. In this case, you may also be interested by
this.
- The ROM we will build here will be even simpler than the music player generated by mmutil. It plays the music as soon as the ROM starts, no need to press A anymore.
Obtaining the Maxmod example program
devkitPro comes with some example programs demonstrating the capabilities of libgba, the Game Boy Advance library. Make a copy of the Maxmod example (the whole maxmod folder) somewhere on your computer, by default you should find it in:
C:\devkitPro\examples\gba\audio\maxmod on Windows
/opt/devkitpro/examples/gba/audio/maxmod on Linux
Alternatively, you can download it
from GitHub (look into the audio subfolder).
Building the example ROM
Windows
Launch MSYS2 from the Start menu.
Go to the Documents directory with the command:
cd Documents
Now using the file explorer, move the Maxmod example directory to Documents if it was not already here and enter the command
ls. It should show you the maxmod folder among your usual files and directories.
Use
cd to open the maxmod folder and see its content with
ls:
cd maxmod
ls
You will see a file named Makefile, it contains all the instructions to build the example ROM. To use it, you just need to run the command
make:
make
It will automatically build the rom. Note that your current directory has to be the same as the Makefile or it won't work.
Look at the content of the directory called basic_sound, either by using the file explorer or by using MSYS2 with the command:
ls basic_sound
If everything went correctly, you should see a Game Boy Advance rom called basic_sound.gba. You can open it in an emulator.
Linux
Open a terminal and go to the location of the maxmod folder:
cd <path to your maxmod folder>
Go in the maxmod folder and use
ls to see its content:
cd maxmod
ls
You will find a Makefile, which contains the instructions to build the GBA rom. In order to use it, simply use the command
make:
make
It will build a GBA ROM in the directory basic_sound called basic_sound.gba. You can give it a try in an emulator.
Other operating systems
Unfortunately I don't have macOS running on my computer or in a virtual machine...
If you have macOS or another operating system, you can read the Linux part and try to adapt it to your computer. Please consider adding a section to this page if it works!
Hacking the example ROM
The current ROM is a very simple game, it displays some text, play a background music and you can activate some sound effects by pressing A or B.
We will make it even simpler so that it only plays a background music.
This is how is structured the maxmod directory (before using make).
maxmod
├── Makefile
└── basic_sound
├── Makefile
├── maxmod_data
│ ├── Ambulance.wav
│ ├── Boom.wav
│ └── FlatOutLies.mod
└── source
└── MaxModExample.c
- The first Makefile is the one you used to build the rom
- The second one is an intermediary Makefile, please don't use it
- The directory maxmod_data contains the assets of the game, which are:
------ two sound effects using the wav format
------ the background song, an Amiga module in this case
- The directory source, containing the source code of the program
Open the file MaxModExample.c using your favorite text editor. On Windows, you can use the Notepad. Please don't use a word processor like MS Word or LibreOffice Writer. Then replace the content of the file with this:
#include <gba.h>
#include <maxmod.h>
#include <stdio.h>
#include <stdlib.h>
#include "soundbank.h"
#include "soundbank_bin.h"
int main() {
irqInit();
// Maxmod requires the vblank interrupt to reset sound DMA.
// Link the VBlank interrupt to mmVBlank, and enable it.
irqSet( IRQ_VBLANK, mmVBlank );
irqEnable(IRQ_VBLANK);
consoleDemoInit();
// ansi escape sequence to clear screen and home cursor
// /x1b[line;columnH
iprintf("\x1b[2J");
// initialise maxmod with soundbank and 8 channels
mmInitDefault( (mm_addr)soundbank_bin, 8 );
// Start playing module
mmStart( MOD_FLATOUTLIES, MM_PLAY_LOOP );
// ansi escape sequence to clear screen and home cursor
// /x1b[line;columnH
iprintf("\x1b[2J");
do {
VBlankIntrWait();
mmFrame();
} while( 1 );
}
Build the rom again using make, then open it in an emulator. Now the game only plays the background music and it doesn't display any text.
Playing your own songs
Delete the file FlatOutLies.mod in maxmod_data, then replace it with a copy of your song. The copy has to be named FlatOutLies.<your module extension>. For instance, if your song module is vombot.it, you will call the copy FlatOutLies.it.
Now edit these two lines from the source code file MaxModExample.c:
// initialise maxmod with soundbank and 8 channels
mmInitDefault( (mm_addr)soundbank_bin, 8 );
You need to change 8 by the number of channels used in your module.
Build the rom again with make, then open it in an emulator, it should now play your song!
Optional: changing the song module name
If you don't want to call your module FlatOutLies.<extension>, you can edit the source code to set a different name. Let's suppose you put a module file called vombot.xm in maxmod_data, then you need to edit these two lines:
// Start playing module
mmStart( MOD_FLATOUTLIES, MM_PLAY_LOOP );
Replace MOD_FLATOUTLIES by MOD_ followed by the name of your file in uppercase letters, without its extension. In our case, this will be MOD_VOMBOT.
Note that MOD_ has nothing to do with the .mod extension, don't write something like XM_VOMBOT.
Links for further development
The development of Maxmod is still active, the code is on
GitHub and you can join the devkitPro community through their
forum.
See also
-
GameBoy Advance
-
s3xmodit (format)
-
Krawall
