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

One-shots & PCM streams

Sound effects, voices and streamed music bypass the MIDI engine entirely. They play on the 16 AICA channels the MIDI engine never touches, through two simpler player types.

Sixteen channels, shared by priority

48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 AICA channels 48-63 (an example moment) one-shot playing stereo stream (left + right, started together) free Each slot records its owner, what kind of player it is and the owner's priority; a new sound may take the slot of a lower-priority one.

There are 8 one-shot ports and 4 stream ports (each mono or stereo), but only 16 channels. A player asks for a slot when it starts: a free slot is taken, or a lower-priority owner is evicted; a player that already owns a slot reuses it.

One-shots

A one-shot bank (tagged SOSB) is a list of entries, each a ready-made AICA channel register image: sample address and format, loop points, envelope, filter, LFO, pan, sends and level, plus a loop count. Nothing is computed from musical parameters; the sound designer's settings go straight to the hardware.

  1. PlaysdShotPlay(port, bank, number, priority): the bank is validated, a slot is obtained, the entry is copied into the channel (with the sample address relocated), the port's volume, pan, pitch and send levels are applied, and the channel is keyed on.
  2. While playingEvery 4 ms the player looks at its channel through the monitor: it runs volume/pan/pitch/speed fades, counts passes through the loop, and when the loop count is used up (or a non-looping sample ends) it keys the channel off and frees the slot.
  3. ControlStop, pause/continue, volume, pan, pitch, speed (all with fades), effect bus and level, direct level, and a loop-count mode (add to, scale or replace the sample's own count).
  4. StatusThe port's status record reports whether it is playing, its levels, the number of samples played and the current play position.
In Soul Calibur

The game's initial data carries two one-shot banks with 61 and 53 entries, all 4-bit ADPCM and none looping, which suits short effects and voice clips (which sound is which was not catalogued here).

PCM streams

Music too long to keep in 2 MB is streamed: the SH-4 reads it from disc and keeps refilling a ring buffer in sound RAM while the AICA plays it.

ring buffer in sound RAM AICA play position SH-4 refills here SH-4 (game / sd library) reads the file from disc, writes fresh blocks into the ring Manatee programs a looping channel over the whole ring, reports the position AICA channel plays round and round; never knows it is a stream
Figure 2. Streaming is a looping sample whose contents the SH-4 keeps replacing just behind the play position.
  • Setup The game allocates the ring(s) in sound RAM and records them in the bank table; sdPstmPlay passes the sample format (16-bit, 8-bit or ADPCM), the frequency, mono or stereo, a base volume and the priority. ADPCM streams use the AICA's special long-stream mode.
  • Stereo Left and right are two channels on two rings. The driver programs both and then executes the key-on once, so they start on exactly the same sample and stay in lock-step.
  • Position Every 4 ms the driver reads the channel's current address through the monitor, counts ring wraps, and publishes the position in the port's status record. The SH-4 uses that to decide how much it can safely overwrite.
  • Control Volume, pan (per channel), pitch and speed with fades, effect send and direct level, stop and reset.

The game's music files (raw 16-, 8- and 4-bit left/right pairs such as *.P16) are exactly the kind of data these stream ports play; how the game schedules the disc reads is SH-4 code outside the driver.

Fades everywhere

All players share one idea: the game sends a target and a time, and the driver moves the value there itself, 4 ms at a time. That keeps the SH-4's work to one command per fade and makes fades smooth regardless of the game's frame rate. The one-shot and stream fades are implemented separately from the MIDI port fades, and their arithmetic differs in small ways (see the quirks page).

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.