MrCART 128

ESSound

ESSound is an external audio system that lets homebrew games play MP3 and WAV files while still allowing the VSU to be used at the same time.

Workflow

VB ROMWrites one 16-bit command to the expansion address.
/ES CommandThe expansion signal selects the audio command path.
ARMDecodes MP3 or WAV assets from the same game folder.
Mixer + DACCombines one MP3 and one WAV source in stereo.
VB AudioPlays alongside the original Virtual Boy sound.

Core capabilities.

MP3

Music Slot

One MP3 can play at a time, with play, stop, loop, volume, and balance.

WAV

Effect Slot

One WAV can play at a time, suitable for effects or short audio events.

L/R

Stereo Output

Two DAC outputs provide left and right channels at 12-bit output depth.

Audio file IDs

1-100

MP3 Files

  • Named 1.mp3 through 100.mp3
  • Constant bitrate
  • Up to 128 kbps
  • 44.1 kHz audio
101-254

WAV Files

  • Named 101.wav through 254.wav
  • 44.1 kHz audio

Folder placement

Audio files must be placed in the same folder as the .vb file that triggers them.

GAMES/FormulaV/
  FormulaV.vb
  1.mp3
  2.mp3
  101.wav
  102.wav

Command structure.

The Virtual Boy writes one 16-bit value to the expansion address. The high byte selects the track, the middle nibble carries a command value, and the low nibble selects the command.

bits 15..8 Track ID
bits 7..4 Command value
bits 3..0 Command

Defined commands

Command Name Public behavior
0x0 STOP Stops the selected track. 0x0000 stops all active audio.
0x1 PLAY Starts the selected MP3 or WAV file once.
0x2 PLAY LOOP Starts the selected MP3 or WAV file in loop mode.
0x3 SET VOLUME Uses command value 0x0 to 0xF, from minimum to maximum volume.
0x4 SET BALANCE Uses command value 0x0 to 0xF, from right to left balance.
0xFFFF ESSound Init Starts ESSound and sends a pulse on /INTCRO so the ROM can confirm that ESSound initialized correctly. Calling init again restores volume and balance to their default values.

Example commands

0xFFFF = ESSound init
0x0101 = play 1.mp3
0x0102 = play 1.mp3 in loop
0x6502 = play 101.wav in loop
0x0573 = set track 5 volume to 0x7
0x05F4 = set track 5 balance fully left
0x0500 = stop track 5
0x0000 = stop all audio

VUEngine Studio examples

From VUEngine, send ESSound commands by writing a 16-bit value to the expansion address.

*((volatile uint16)0x04000000) = 0x0101; // Play 1.mp3
*((volatile uint16)0x04000000) = 0x6502; // Play 101.wav in loop
ESSound can play one MP3 and one WAV at the same time. It cannot play two MP3 files or two WAV files simultaneously.