Manatee · Dreamcast audio & sound driver, explained
The Manatee driver

The MIDI engine & voices

Music, and any sound the game chooses to play as notes, goes through a General-MIDI-like engine: 8 ports of 16 MIDI channels each, sharing 48 hardware voices. Instruments come from tone banks whose samples carry complete AICA register settings.

Ports, channels and voices

8 ports 16 MIDI channels per port 48 shared voices port 0 volume · pan · pitch · speed fx send · priority · status port 1 … port 6 port 7 (also external MIDI) channel state program · bank · velocity curve volume · expression · pan modulation · bend · sustain filter / envelope / send offsets × 16 per port = 128 in total voice records which port / channel / note velocity · priority · age current level (monitor) split used · bend offset = AICA channels 0-47 note on A port is what the game controls with host commands (play song, volume, fade…). A MIDI channel is what MIDI events address (program, controllers). A voice is one sounding sample on one AICA channel. One note can use up to four voices (layers).

Tone banks: programs, layers and splits

An instrument bank (tagged SMPB) is a tree:

Bank programs · curves Program up to 4 layers Layer 1bend range · delay Layer 2bend range · delay Layers 3, 4 Split key range · velocity range root key · fine tune · curve sample, loop, envelope, filter, LFO, pan, sends, level more splits (C1-B2, C3-B4 …) A piano might be one layer with a split every few keys; a pad might layer a string sample with a slow-attack choir on a second layer. The first split of each layer whose key and velocity windows fit the note is used.

Everything inside a bank is position-independent: the driver adds the bank's address when it follows offsets, including sample addresses, so the SH-4 can place a bank anywhere in sound RAM. This driver also carries two tiny built-in banks: a default instrument bank (a square and a sawtooth wave) that every channel points at after boot, and a default drum kit built on the noise generator.

What happens on note-on

  1. Find the instrumentThe event names a port, channel, note and velocity. The channel's current program gives up to four layers; muted layers are skipped.
  2. Pick a split per layerThe first split whose key range and velocity range both contain the note wins.
  3. Get a voiceThe allocator returns a free voice or steals one (see below). The voice records who owns it: port, channel, note, velocity and the port's priority.
  4. Program the AICA channelThe split's register image is copied into the channel, with adjustments: sample address relocated by the bank address; envelope and filter-envelope rates offset by the channel's controllers; filter levels offset by the channel's cutoff; LFO depth scaled by the modulation wheel; send bus and send level from the tone, channel and port; pan from the tone or channel plus the port pan; resonance and filter on/off from controllers.
  5. LoudnessThe velocity passes through the bank's velocity curve and is multiplied by the channel level (volume × expression) and the tone's own level; the port volume is added as an offset, and the result becomes the channel's total level.
  6. PitchThe note's distance from the split's root key, the port pitch, the channel's pitch bend and the split's fine tune give a pitch in 1/256 semitones, converted into octave and fraction with two lookup tables.
  7. Key onUnless the layer asks for a delay, the channel is keyed on at once. A delayed layer is keyed on by the 4 ms update when its counter expires, unless a note-off arrives first.

Voice allocation and stealing

With 48 voices shared by eight ports and up to four voices per note, running out is normal. The allocator walks all 48 voices once:

Is the voicecompletely idle? no yes take it immediately Higher priority thanthe new note? yes never steal it no: candidate Keep the best candidate Prefer voices that are already released (key off, fading out) over held notes. Among released voices, the quietest wins, judged by the envelope monitor. Otherwise: lower priority, then older. The steal: the old note is simply overwritten; the AICA restarts the channel on key-on.
Figure 3. The allocation policy, simplified. Priority is the port's priority, carried on every event, so a high-priority sound-effect port can take voices from music but not vice versa.
A real bug in this build

If every one of the 48 voices has a higher priority than the new note, the allocator is supposed to fail. Instead, because of a pointer that is only reset inside the loop, it reads two of its own instruction words as "the chosen voice" and reports success, and note-on then writes to garbage addresses. It only happens when all voices are busy with higher-priority sounds. Details on the quirks page.

Note off and the sustain pedal

Note-off releases every voice playing that port, channel and note (duplicates included) by clearing its key-on, so the AICA moves the voice into its release phase. If the sustain pedal (CC 64) was down, the voice is only marked as released and keeps sounding; lifting the pedal releases all such voices on the channel. The voice's "age" restarts and its level is reset, so the allocator will prefer it once it is quiet.

Controllers

Standard MIDI controllers behave as expected, and Sega added a set of controllers that edit the AICA parameters of the tone in real time. Controllers that change something audible also update voices already sounding on that channel.

GroupControllersEffect
Level & pan7 volume, 11 expression, 10 panchannel level (a curve of volume × expression) and pan; live voices updated
Expression1 modulationscales the tone's vibrato/tremolo depth
Pedal64 damperhold released notes until the pedal is lifted
Parameters6 data entry, 96/97 increment/decrement, 98-101 NRPN/RPN selectRPN sets the pitch-bend range
Bank32 bank selectwhich downloaded tone bank the next program change uses (CC 0 is ignored)
Filter74 cutoff, 75 cutoff range, 110-117 cutoff at fixed ranges, 71/85 resonance, 70 filter on/offbrighter or darker, more or less resonant
Filter levels20-24 (coarse) / 52-56 (fine)offset each of the five filter-envelope levels
Filter envelope25-28filter attack / decay 1 / decay 2 / release rates
Amplitude envelope73/87 attack, 88 decay level, 89 decay rate, 72/86 releaseoffset the tone's envelope
Effects91 reverb send, 76 DSP input bushow much of the voice goes to the DSP, and on which bus
DSP (port 7)77 / 78 output pan / level, 79 effect program, 80 positional pancontrol the DSP from MIDI (see DSP)
Misc48 timing counter, 121 reset all controllersa counter the game can read; reset a whole port's channels
Ignored0, 120, 123, poly and channel pressureno effect in this build

Pitch bend and program change

Pitch bend is scaled by the bend range (from the layer, or an RPN override) and applied at once to every sounding voice of the channel. Program change looks up the current bank (falling back to the built-in bank), and switches only if the program exists; notes already playing are unaffected. For drums, a host command marks a MIDI channel as a drum channel, whose bank select chooses between two drum-kit bank slots.

What happens every 4 ms

  • Delayed key-ons count down and fire.
  • Port changes (volume, pan and pitch fades driven by host commands) are applied to every voice of the port, so a fade-out of the music affects notes already sounding.
  • Envelope monitoring continues in the background every millisecond, keeping each voice's "how loud am I" value fresh for the allocator.
Reference build: the Manatee driver shipped in Soul Calibur (USA), v1.1 build 0x3F. Built from the decompilation in this repository (src/arm/, docs/). Hover diagram elements for details.