Music Box GB

Music Box
Music Box
General
Author	Black Box
Type	Music Apps
Version	1.3
License	Mixed
Last Updated	2001/02/26
Links
	Download
	Website

"

Music Box is a Game Boy tracker developed by Ray Nemes and Zsolt Minier, It is an advanced musicsystem, soundeffect system and music editor for the Nintendo GameBoy family.

It is not as basic as typical audio systems used in games nor as resource-intensive as demonstration audio systems. It is possible to make multispeed music with the system, it uses all the four channels for both music and soundeffects (including the third wavetable channel). The size of the music is also really small.

User guide

Pattern Editor

The Pattern Editor allows editing patterns and has five sections:

Pattern Order Editor.
Note column.
Instrument column.
Actual row in actual window.
Actual pattern.

It offers control similar to tracker programs, with four pattern columns in the Pattern Order Editor, one for every channel, you have 64 rows ($00-$3f) to use the 56 patterns ($00-$37, $ff in the first column is the restart command, $fe is the stop). In the Pattern Editor you have the usual 64 rows too ($00-$3f), you can use notes between C-3 and B-8 and 32 instruments (note: between $01-$20, $00 is the empty line).

The Numeric Input window will show up when you press the B button in the Pattern Order Editor or in the Pattern Editor’s Instrument column; and if you press the B button in the Pattern Editor’s note column, it will bring up the Note Input window.

Instrument Editor

The Instrument Editor allows editing instruments and consists of several sections, including the ABC Editor, Sample Editor (channel 3), Arpeggio Editor, and 3 Bytes Editor.

ABC Editor

The ABC Editor is the most complex part, where each row represents an instrument. Musicians can freely set rules for instrument usage on different channels. The editor uses hexadecimal numbers for various options, and there are tables to guide composers in choosing settings for each instrument. The editor provides technical options for programmers and more experienced composers.

Channels 1 and 2 are similar pulse waveform modulators, channel 3 is a digital sample channel, and channel 4 is a noise generator mostly used for percussion instruments.

Byte A - Frequency Slide - register NR10 ($ff10)
- Speed of slide (choose one):
  - $00 - No slide
  - $10 - Sweep very swiftly
  - $20 - Sweep swiftly
  - ...
  - $70 - Sweep slowly
- Direction of slide (choose one):
  - $00 - Slide up
  - $08 - Slide down
- Step of slide - note that too little steps may result in no slide (choose one):
  - $00 - No slide
  - $01 - Biggest steps
  - $02 - A bit smaller steps
  - ...
  - $07 - Smallest steps
Byte B - Waveform/Sound Length - register NR11 ($ff11)
- Waveform (choose one):
  - $00 - 12.5% ( - _ _ _ _ _ _ _ )
  - $40 - 25.0% ( - - _ _ _ _ _ _ )
  - $80 - 50.0% ( - - - - _ _ _ _ )
  - $c0 - 75.0% ( - - - - - - _ _ )
- Sound Length - after this time the sound will be muted, see also Byte D (choose one):
  - $00 - Shortest
  - $01 - A little bit longer
  - $02 - Two little bits longer
  - ...
  - $1f - Longest
Byte C - Volume Envelope - register NR12 ($ff12)
- Initial volume (choose one):
  - $00 - Silence
  - $10 - Very, very quiet
  - $20 - Very quiet
  - ...
  - $f0 – Loudest
- Direction of volume change (choose one):
  - $00 - Fade away
  - $08 – Amplify
- Speed of change (choose one):
  - $00 - No change
  - $01 - Change very swiftly
  - $02 - Change swiftly
  - ...
  - $07 - Change slowly
Byte D - Sound Length Mode - counter/consecutive selection bit (bit 6 of NR14 ($ff14))
- $00 - Ignore the length in Byte B, note will sound till the next note
- $40 - The note sounds as long as specified in Byte B
Byte E - Arpeggio Pointer

100% same as Channel 1 ABC Bytes out of that Byte A is unused. So this is more or less compatible with channel 1. Channel 2 instuments can be played back on channel 1 and the result will sound the same if Byte A is $00 for channel 2.

And channel 1 instruments also can be played back on channel 2, if Byte A is $00 for channel 1, the result will sound the same, if it is different, still it will sound similiar and possibly good.

Byte A - Waveform Pointer
- Points to the waveform table. $00 = offset $00, $01 = offset $10, $0e is the last value. $ff is the channel 3 mute command.
Byte B - Sound Length - register NR31 ($ff1b)
- The length of the sound. All values ($00-$ff) are legal. The bigger the value the shorter the sound. See also Byte D.
Byte C - Sample Volume - register NR31 ($ff1c)
- $00 - Mute
- $20 - Full volume
- $40 - Half volume
- $60 - Quarter volume
Byte D - Sound Length Mode - counter/consecutive selection bit (bit 6 of NR34 ($ff1e))
- $00 - Ignore the length in Byte B, note will sound till the next note
- $40 - The note sounds as long as specified in Byte B
Byte E - Arpeggio Pointer

Byte A - Noise Mode - register NR43 ($ff22)
- Pitch of noise (choose one):
  - $00 - Highest
  - $10 - Very, very high
  - $20 - Very high
  - ...
  - $d0 - Lowest
  - $e0 & $f0 - Illegal values
- Noise mode (choose one):
  - $00 - Noise 1
  - $08 - Noise 2
- Another pitch of noise (choose one):
  - $00 - Highest
  - $01 - Very, very high
  - $02 - Very high
  - ...
  - $0f – Lowest
Byte B - Sound Length - register NR41 ($ff20)
- The length of the sound. Values $00-$3f are legal. The bigger the value the shorter the sound. See also Byte D.
Byte C - Volume Envelope - register NR42 ($ff21)
- Initial volume (choose one):
  - $00 - Silence
  - $10 - Very, very quiet
  - $20 - Very quiet
  - ...
  - $f0 – Loudest
- Direction of volume change (choose one):
  - $00 - Fade away
  - $08 – Amplify
- Speed of change (choose one):
  - $00 - No change
  - $01 - Change very swiftly
  - $02 - Change swiftly
  - ...
  - $07 - Change slowly
Byte D - Sound Length Mode - counter/consecutive selection bit (bit 6 of NR44 ($ff23))
- $00 - Ignore the length in Byte B, note will sound till the next note
- $40 - The note sounds as long as specified in Byte B
Byte E - Unused

Waveform Editor

The waveform table contains 240 bytes from $00 to $ef, 4 bit digital samples. These can be edited the usual way with the B button.

15 times 16 bytes are stored here (the size of the Wave RAM) and the selected one (Byte A of Channel 3 ABC Table, $00 = $00-$0f, $01 = $10 - $1f … $0e = $e0-$ef, $ff = mute) is uploaded to the Wave RAM at channel 3 instrument change.

Arpeggio Editor

The Arpeggio Editor is a programmable Frequency Manipulator Sequencer that allows programming effects like Arpeggio, Portamento, Vibrato, and other frequency changes.

It is edited similarly to the Waveform Editor and is open, allowing pointing to different parts of the table from any instrument or channel. There are four commands in the Arpeggio Table, controlling the frequency changes for all three channels. It's crucial to use the right commands to avoid false sounding music. The editor also handles Arpeggio Pointers automatically when inserting or deleting.

If it is not clear the following example is explaining it, we start with C-5 base note and the instrument’s Apreggio pointer is $05. On the left column we can see the offset and value in the Arpeggio Table, on the right the currently played note.

Offset $05: $00 – C-5 (base note)
Offset $06: $04 – E-5 (transpose base by 4 halfnotes)
Offset $07: $07 – G-5 (transpose base by 7 halfnotes)
Offset $08: $80 – jump command, take the destination from the next byte
Offset $09: $05 – jump to Offset $05, take $00 from there, play C-5 again

Also note that when you insert and delete in the Arpeggio Editor, the Arpeggio Pointers are getting fixed automatically.

3 Bytes Editor

The 3 Bytes Editor controls important parameters for the music.

The first one is the tempo, it is dividing the maximum BPM. The higher the value, the slower the music (multiply this for double and quattro replay speed).

The second byte (NR50 or $ff24 register) controls the global left/right volume, allowing adjustments from silence to maximum volume. Volume can be controlled only between $0 and $7, so $00 is silence, $77 is max volume, $73 is a heavy left balance.

The third byte (NR51 or $ff25 register) manages the output for each channel, enabling the choice of left, right, both, or no output for channels 1 to 4. Each value is represented by specific binary digits from the table.

$80 - Channel 4 is output to the left
$40 - Channel 3 is output to the left
$20 - Channel 2 is output to the left
$10 - Channel 1 is output to the left
$08 - Channel 4 is output to the right
$04 - Channel 3 is output to the right
$02 - Channel 2 is output to the right
$01 - Channel 1 is output to the right

Player Window

The Player Window provides controls for music playback, with a few commands available:

Starting pattern position.
Restarting (loop to) pattern position.
Actual pattern position.
Actual track position.
Actual pattern numbers.
A small bonus scroller, credits.

With the direction pad the starting pattern position can be changed with its left/right directions and the restarting pattern position (where the pattern sequencer will jump to after the $ff command in the first column of the pattern order) with its up/down directions.

The Start button is leaving this screen again and the select button will bring up the Extra Window. The A button will start the music and while playing, the B button is fast forward, everything else is stop.

Extra Window

This can be reached only from the Player Window by pressing the select button. You can find various functions, most are self-explanatory:

Clear samples (wavetable)
Clear patterns (plus pattern orders)
Clear arpeggio, vibrato, portamento table
Clear instruments
Clear everything (all above)
Copy pattern
Player type (1X, 2X, 4X speed)
Shut down

You can clear samples, patterns, arpeggio, and instruments, but remember there's no undo. B is the activation button. Back returns to the previous menu.

The Copy Pattern screen allows you to copy patterns between source and destination pattern numbers. Use the direction pad to change values: left/right for the source pattern, up/down for the destination pattern. Press B to copy and A to cancel the operation.

The Player type allows you to speed up the player to 2X or 4X its normal speed, useful for techno music and accurate timing. However, this speed isn't stored in the music, so you need to manually set it when starting Music Box.

The Shut Down Window provides a quit option to stop the machine safely. This prevents potential data corruption in the Battery Backed SRAM where the music is stored. Make sure to use this option before turning off the machine to avoid data loss, especially if you have spent many hours working on your music. Regularly backing up your SRAM is also recommended to keep your work safe.

Tips

Always back up files, especially SRAM. Note playback speed for multispeed musics (doubleplayer and quattroplayer) in the extension (.1X, .2X, .4X) and adjust it in the Extra Window when restarting the tracker.

Organize instruments between the four channels. Set rules for instrument allocation (e.g., $01-$08 for channel 1, $09-$10 for channel 2) or customize for each song. Share instruments between channels 1 and 2, which are similar, and allocate fewer instruments for percussion (channel 4).

Keep a null instrument with $00 filled values for muting looping sound effects or as a note-off. It is usually recommended to place it on the first ($01) instrument, but it can be placed as needed.

A null Arpeggio is also useful for instruments that don't need arpeggios. Place it at the beginning of the Arpeggio Table using $00, $80, $00, so the default $00 Arpeggio pointer will point to it from the instrument description bytes (ABC Bytes).

Controls

Pattern Editor

A - Switch between Pattern Order Editor and Pattern Editor

B - Numeric Input window (when in Pattern Order Editor or the Pattern Editor’s Instrument column)

B - Note input window (when in Pattern Editor’s note column)

Select - Switch to Instrument Editor and back

Start - Switch to the Player Window and back

Numeric/Note Input window:

D-Pad - Navigate

Up/Down - Move slower by one position

Left/Right - Move faster by one column

B - Enter your selection

A - Cancel selection

Select - Insert/Delete menu

Insert/Delete menu:

A - Inset/Delete row, Press on an empty menu to go back

Player window

D-Pad - Change the starting and restarting positions

Start - Leave Player window

Select - Open the Extra Window

A - Start the music

During playback:

B - Fast-forwards

All other buttons - Stop the music

Extra window

Clear samples/patterns,arpeggio/instruments:

B - Activate

Copy Pattern:

Left/Right - Change the source pattern

Up/Down - Change the destination pattern

B - Copy

A - Cancel

Screenshots

https://dlhb.gamebrew.org/gbhomebrews/musicboxgb2.bmp https://dlhb.gamebrew.org/gbhomebrews/musicboxgb3.bmp https://dlhb.gamebrew.org/gbhomebrews/musicboxgb4.bmp

Compatibility

Music Box 1 has modest hardware requirements and is compatible with all Game Boy models, from the earliest DMG to the Game Boy Advance (in Game Boy Color mode). It works well with most development tools, software, and hardware emulators. It utilizes 32 kilobytes of ROM and 8 kilobytes of Battery Backed SRAM, making it compatible with various memory bank controllers. However, there might be some compatibility limitations with certain devices.

Some official Flash Cards lack SRAM and Battery Backed SRAM, which are essential for Music Box 1 compatibility. Certain non-standard memory bank controllers, like the Bung and Mr Flash PocketVoice card, are also incompatible due to their lack of SRAM and unusual operation. Certain software emulators may not emulate SRAM or the sound chip properly, leading to potential issues. To avoid data loss, it's advised to save works frequently to the PC and replace the old weak batteries when needed. (In every 1-2 years).

Credits

All code, design, graphics, documentations - Zsolt Minier and Ray Nemes.

Thanks for the help (ideas, tests, example songs) - Jukka-Pekka Luukkonen.

Thanks for the help (ideas, tests, documentation works) - Attila Szoke.

External links

Official website - http://blackbox.resource.cx/