GameBoy Music Compiler GB

GameBoy Music Compiler
GameBoy Music Compiler
General
Author	Leaf
Type	Music Apps
Version	2019
License	Mixed
System	CGB
Last Updated	2019/10/03
Links
	Download
	Website
	Source

GameBoy Music Compiler (GBMC) is a program that allows you to play music using the Game Boy's sound source. You can write music in MML (Music Macro Language) using a text editor and then pass it through the compiler to generate GBS files that can be played on various players.

The program has been redesigned based on feedback from NSF Player, previous versions, and tested on the actual Game Boy hardware. Now you can enjoy the nostalgic and warm 8-bit sounds on your Game Boy.

Features

Outputs GBS format, playable in various well-known players like KbMedia Player and foobar2000.
Directly outputs GBDSP (Game Boy Digital Sound Processor), a visual player enjoyable on GB emulators and similar platforms.
Pitch/volume/duty ratio/waveform memory timbre/localization can be defined independently
High-speed arpeggio, portamento, legato, grace note commands, etc.
PCM playback available (GBDSP only; not supported in GBS). Playback rate: 4096Hz/4-bit.
2 logical tracks can be used for each of the 4 physical channels. The upper track is played with priority over the lower track.
Distributed under a free license.

User guide

GameBoy Music Compiler (GBMC):

Comes with sample songs, source code, and a tutorial.
Requires .NET Framework, which can be obtained through Windows Update.

Compile from the command line. If successful, you'll get a GBS file playable in various players or a ROM file executable on GB emulators (based on #mode specification). If there are errors, it will display the corresponding line and exit.

MML manual

Please note that uppercase and lowercase letters are generally treated differently, so please be cautious. However, there are cases where it doesn't matter. For more details, refer to the explanations of each command.

In the initial state, you need to set v (volume), p (position), and x (waveform) first; otherwise, no sound will be produced. In the waveform memory sound source, don't forget to register the waveform and set it with @(waveform).

For non-looping songs, the sound will continue indefinitely. It's recommended to include a rest note at the end.

To reduce processing load, many checks have been omitted in the driver, so there might be weird sounds if accessing out-of-range memory. Rather than causing heavy issues, the focus is on making it sound correctly through manual effort. Even if you write strange commands, at most, the GB may hang up, so feel free to experiment.

To output GBS, use #MODE 0, and for running it on an emulator, you can use #MODE 3 (color) or 4 (monochrome).

PCM data

If you want to listen to GBS files, nezplay, which comes with nezplug++, is a compact and convenient option. You can run nezplay.exe with npnez.dll, and simply drag and drop the GBS file onto the player to start playback.

The maximum capacity for all song data, excluding PCM, is 16KB (16384byte). When using GBDSP, it reduces by 96 bytes. PCM data can be up to 16KB (16384 bytes) per note.

For PCM data, it is recommended to use the PCM converter. In that case, it is essential to follow these three rules:

Align to 16-byte boundaries.
Set to 4096Hz.
Use 1 byte for 2 data.

Note that these checks are not performed on the compiler side.

NoiseTest.gb

Also included is a program (noisetest.gb) that can assist with finding the noise frequency. Supports both GB/GBC.

Press A to play or mute the sound.
Press B to play the sound with an envelope.
Press the Select button to toggle the envelope direction.
The labels "SHORT" and "LONG" in the upper-left corner represent short and long period noises, respectively.
Use the D-Pad to move around and listen to the sound.
The hexadecimal value in the upper-right corner is the value used for the "w" command.

Running GBDSP

When compiling with GBMC, you can choose either the output for Monochrome GB or Color GB using the #mode compile option. Please note that you may need to adjust the emulator settings to match the chosen output mode for it to work properly.

The bottom row of options includes Play, Stop, Pause (Resume), and Fade Out functions. Above that, each channel can be muted by pressing the corresponding button, and pressing it again will unmute the channel.

Pressing the "TEMPO" section will toggle the display between the tempo (indicated by "t" in the MML code) and the musical tempo (indicated by a musical note symbol ♪).

Press the Start button and the color at the top of the screen will change. It represents the processing load of the sound driver. Press again to cancel.

Palette

In the GBC version, press the Select button to enter the palette change mode. The GB version changes color every time you press the Select button (24 patterns in total). Press Start+Select to restore all changes to default.

Below is an explanation of the GBC version:

First, select one of the icon sections 1 to 4 on the bottom left corner. When you move the cursor up and down here, the values on the right side should change.

The values on the right side represent the parts where further modifications can be made for each 1 to 4 (up to four parts grouped together as RGB). Each modifiable part is as follows, from top to bottom:

Background color of song information on the bottom screen.
White key/Black key.
Background color of the upper screen/text shadow, waveform display, small icon background/text color, content of small icons, text color of song information.
Color of the pressed keys on the keyboard.

Move the cursor to the part you want to change, and you can change each RGB value with B+Up/Down. Press Select again to return to the song information screen.

Changes made in the palette change mode will be saved and automatically applied in subsequent launches.

Putting multiple songs in one GBDSP ROM (album creation)

To combine multiple GBDSP songs into a single ROM (album), you can use the included "AlbumGBDSP" tool. This allows you to merge multiple GBDSP ROMs into one.

To merge songs, open the command prompt and use the following command:

> AlbumGBDSP TARGET.GBC APPEND.GBC

will add the songs in APPEND GBC to TARGET.GBC (for monochrome GB, change GBC to GB). Both must be GBDSP ROMs and must be compiled with the latest GBMC. Up to 240 songs.

To display the current playlist, use the following command:

> AlbumGBDSP TARGET.GBC -l

This will list the title information. Please note that the letter "l" is in lowercase.

If there is a song you want to remove, remember the number of the song from the above list and use the following command:

> AlbumGBDSP TARGET.GBC -d num

Replace "num" with the number of the song you want to delete. If you omit the "num," it will delete the last song in the list.

Control another Game Boy's GBDSP

When you press the A button on the play start icon, the GBDSP connected with the communication cable will also start playing at the same time.

To reproduce this in an emulator on a single PC (suppose you use BGB):

Launch two instances of the BGB emulator and load the GBDSP with the respective songs you want to play on each instance.
Right-click on one of the BGBs, select Link > Listen, and when asked for the port number (probably the default is 8765), press OK.
At this time, the firewall may ask for communication permission, so allow it.
On the other BGB instance, go to Link > Connect and when asked for the IP address (127.0.0.1 is the default), click OK.

After completing the setup, pressing the A button on the play icon will start the performance simultaneously on both connected GBDSPs. Please note that synchronization is only for starting the performance; stopping or other actions are independent (a bit of a shortcut).

Notes on tempo

The tempo is synchronized with the vblank, meaning the smallest note duration unit (192nd note = 1 count) is approximately 1/60 second. Due to the specifications of this sound driver, there might be instances of sound dropout.

The upper chart shows the progress of 1 count (t64) precisely executed in 1 vsync (vertical synchronization), repeated 8 times. At a musical tempo of tempo=75, all notes are guaranteed to be played in this case.

If we double the tempo, the second figure illustrates the result, with 2 counts (t128) being processed within 1 vsync period (vsync 4 times). As a consequence, only the portion highlighted in red will be played. This means that the distinctive strong attack part (v15) of the envelope is skipped, causing sound dropouts.

To prevent sound dropouts, some adjustments are necessary. For instance, one approach is to keep the tempo as t64 and halve the note duration, changing the envelope to v15c v9c v6c v2c, for example.

Another solution is to use lengthed notes macros. In this case, the MML tempo inside the macro is forced to vsync=t64. Outside the macros, the tempo remains t128 with a note length count of 8, while inside the macros, the note length is t64 (though only the first 4 note counts will be played in the macro). This is convenient because it saves the effort of manually adjusting other tracks' lengths to match the envelope.

This approach is similar to how game music maintains consistent sound effects, regardless of varying tempos in different tracks of the music.

#M0 v15cn1 v10cn1 v7cn1 v3cn1 v1cn1 cn1 cn1 cn1

'D t128 M0,n8

Please note that various modulations and high-speed arpeggios have their smallest change unit based on vsync, so you won't experience sound dropouts.

Whether the tempo is set to t64 or t128, the parameter sequences for modulations and the way arpeggios sound will remain unchanged. They won't be skipped or altered.

However, if you manually write elements like envelopes, you need to be cautious as this is where sound dropouts may occur.

Controls

GBDSP (general):

D-Pad - Navigate

A - Action

Start - Show processing load

Select - (GBC) Palette change mode, (GB) Change color

Start+Select - Restore changes to default

GBDSP (album):

B+Left/Right - Change the track number (release the B button to display the track information)

Press A on the play icon - Play selected song

B+Select - Return to the original track information (while the music is still playing)

Screenshots

Compiler

GBDSP

Changelog

2019/10/03

Added #DEFLEN and C commands. Now you can specify the count for a whole note.

2019/10/02

Fixed an issue with the counting method of the q- command. Changed all Q/q from vsync to timebase. Thanks MM1!

2019/07/07

Switched the song information font from NAGA10 to M+BITMAP FONTS. Also, added additional notes regarding distribution.

2019/07/04

Enabled to compile with new version of rgbasm.
Fixed an issue where modv/p wouldn't work properly when notes were connected with "&."
Fixed a case where the gates were triggered in places where they shouldn't have been when notes were connected with "&" or "^."
Fixed some potential runaway issues related to PCM.
It was unreasonable to use a timer as an interrupt source, so I changed it back to vblank. Accordingly, PCM support in gbs has been discontinued.
Fixed a bug where effects and portamento processing in lower tracks wouldn't work while upper tracks were active.
Expanded the macro functionality that allows specifying note lengths. It is no longer necessary to set complex macros separately for different note lengths, simplifying the process.
Modified note length-specific macros to be processed based on vsync rather than the timebase, ensuring consistent sound even when the tempo changes.
Added a new toggle switch that allows you to read macros by pitch such as M0=o2c. It is now possible to specify c8 c16 etc. by combining with the note length specification macro.
Fixed a bug where PCM's pan was not functioning correctly.
Fixed a problem where PCM may not sound on square wave channel ch1.2.
Changed the default tempo to 64. Now, it is possible to go up to t298, which corresponds to BPM (beats per minute).
When using "&r," gates are triggered immediately instead of being treated as rests.
Implemented relative tempo commands.
Implemented legato commands.
Due to the tempo's unification with vsync, the T command was discontinued.
[GBDSP] Supported auto-repeat for some operations.
[GBDSP] Can now reset color settings to default using START+SELECT.
[GBDSP] Implemented a load meter, showing red background color at vblank start, and returning to the original palette once processing is complete.
[GBDSP] Fixed the issue where rests were not properly displayed in the waveform memory sound.
[GBDSP] Changed the color of the mute icon to make mute status more apparent when channels are muted.
[GBDSP] Implemented the ability to save color settings.
[GBDSP] Implemented playing time display.
[GBDSP] Implemented fade-out. Since the master volume of the GB can still produce sound even at 0 volume, it is better to have a fade-out effect than complete silence.
[GBDSP] Enabled the ability to instruct another GBDSP on a separate GB connected via a communication cable to start playing. (Unconfirmed on the actual machine.)
[GBDSP] Implemented the option to switch between displaying tempo as SYNC value or musical tempo value.
[GBDSP] Added support for selecting multiple songs (album).

2014/10/21

Fixed the issue with GBDSP not working.
Made NoiseTest compatible with both GB and GBC.

2014/08/22

Changed octave range from o3-o8 to o2-o7.
Change #M- to #MKILL. Added #MKILLALL.
Added random option to positioning modulation #P.
Added #OCTAVE-REV.
Removed "@w" command and added #NOISENOTE. I don't think it can be changed in the middle of the song. The default is also changed back to non-scale mode.
The "&" command now only takes effect when placed immediately after a pitch command.
Removed the specification that the "v" command turns off the envelope. Envelope must now be explicitly turned off.
Added "u|d" option for specifying up or down in envelope "k" and sweep "s". Parameters can now be omitted.
Added "s|l" option for specifying short or long period in noise parameter "w". Parameters can now be omitted.
Parameters in modulation "zp,zx,zw,zp" can now be omitted.
Introduced "Q". "q/Q" can now be used independently from "zv".
Changed the behavior of "q/Q" when connecting notes with "&" or "^". Now only affects the last note.
Removed "@A". High-speed arpeggio now operates in 1/60-second units regardless of tempo.
Added decorative note "~".
Changed "W" to a compiler command for self-delay. Specification has also changed significantly.
Removed relative volume setting in "@", the waveform memory timbre specification.
Improved to minimize glitch noise.
Fixed PCM. A critical bug was causing it to stop playing (supposedly).
Fixed the bug that caused incorrect pitch with high-speed arpeggio.
Other bug fixes and optimizations.
Attached a GBC ROM for testing noise.

Credits

xpmck.

External links

Author's website - http://www.geocities.jp/submarine600/html/sounddriver.html