Sound & Music

Game Boy Audio Architecture

The Game Boy has four dedicated sound channels, each with distinct synthesis capabilities. All channels share a 4-bit volume range (0–15) and a length counter. On the Game Boy Color, each channel can be individually panned left/right for stereo output.

hUGE Music Driver

GB Studio uses the hUGE tracker driver for music playback. It supports the .uge file format and is installed as a VBlank routine, guaranteeing consistent tempo regardless of main loop performance.

• Driver runs in the VBlank ISR — precise timing on every frame
• Supports all 4 channels with effects (arpeggio, portamento, vibrato, etc.)
• Music data is banked — loaded via far_ptr_t (bank + address)

Music Playback (C API)

// Start music playback
music_play(bank, music_ptr);

// Stop music
music_stop();

GBVM Music Commands

Channel Mute Masks

Mute individual channels to free them for sound effects or direct hardware control. The mask is a 4-bit value where each bit corresponds to a channel:

// Mute CH4 so noise SFX won't conflict with music
VM_MUSIC_MUTE 0x08

// Mute CH1 and CH2 for a dual-pulse SFX
VM_MUSIC_MUTE 0x03

// Unmute all channels
VM_MUSIC_MUTE 0x00

Sound Effects System

Sound effects are played via a VGM-style player that runs alongside the music driver. An SFX temporarily takes over one or more channels; when the effect finishes, the channel returns to the music driver automatically.

SFX Playback

// GBVM:
VM_SFX_PLAY bank, pointer, mask, priority

// mask:     which channels the SFX uses (same bitmask as mute)
// priority: higher value = won't be interrupted by lower priority SFX

• Channel mask: Specifies which channels the SFX will use (same format as mute masks)
• Priority: Higher-priority SFX will interrupt lower-priority ones, but not vice versa
• SFX data is banked and referenced via far_ptr_t

Built-in Sound Types

GB Studio includes predefined sound effect types accessible from the event editor:

• Beep tones (short pulse blips)
• Tone sweeps (ascending/descending frequency)
• Noise bursts (percussion, explosions)
• Custom SFX via .vgm files or direct register writes

Direct Channel Control

For plugins that need precise control over audio hardware, you can write directly to the Game Boy’s sound registers. This is necessary for custom tones, engine sound effects, and any audio behavior not covered by the built-in SFX system.

Pulse Channel Registers (CH1 / CH2)

Noise Channel Registers (CH4)

Volume Envelope Format

Registers NR12, NR22, and NR42 share the same envelope format:

NRx2 format: VVVV DNNN
V = initial volume (0-15)
D = direction (0 = decrease, 1 = increase)
N = envelope period (0 = disabled, 1-7 = speed)

Frequency Calculation

The pulse and wave channels use an 11-bit frequency register. To play a specific note frequency:

frequency_register = 2048 - (131072 / desired_hz)

Common Patterns

Playing SFX Without Interrupting Music

Mute the target channel in the music driver before playing a sound effect on it:

// Mute CH4 in music, then use CH4 for noise SFX
VM_MUSIC_MUTE 0x08
VM_SFX_PLAY bank, sfx_ptr, 0x08, 5

Custom Tone from a Plugin

Play a 440 Hz tone (A4) on CH2 using direct register writes:

// Play a 440Hz tone on CH2
NR21_REG = 0x80;         // 50% duty cycle
NR22_REG = 0xF0;         // Volume 15, no envelope
UINT16 freq = 2048 - (131072 / 440);  // = 1750
NR23_REG = freq & 0xFF;               // Low byte
NR24_REG = 0x80 | ((freq >> 8) & 0x07);  // Trigger + high bits

Stopping a Tone

Set the volume envelope to zero to silence a channel:

// Silence CH2
NR22_REG = 0x00;  // Volume 0, no envelope
NR24_REG = 0x80;  // Trigger to apply the new envelope