Basic Sound Library (libspu)

Provides functions for controlling the SPU (sound processing unit).

This is an old revision of this page, as edited by RemmyLee at 02:58, 23 October 2026. Edit this revision | Latest revision

Overview

The Basic Sound Library (libspu) controls the SPU directly. It forms the lower level of the Extended Sound Library (libsnd) and also provides functions for operations such as transferring data other than music to the sound buffer. libspu has no time control functions, which are provided by libapi. Calls that set the same function must be separated by at least one SPU processing unit of 1/44100 second.¹

A program that uses libspu links with libspu.lib and includes libspu.h.¹

VAG Format

A VAG is compressed audio data arranged in 16-byte blocks. AIFF2VAG on the PC writes little-endian files and AIFF2VAG on the Mac big-endian files. Every VAG has a 48-byte header, which is removed for playback but must remain while VAGs are converted to VABs. The header has the following fields:¹

Every VAG starts with a lead-in of 16 bytes of zero data, which initializes the SPU and prevents clipping noise. AIFF2VAG compresses the body about 3.5 to 1, and the compression method is Sony proprietary information.¹

A one-shot VAG ends with an extra 16-byte block that prevents unnecessary SPU interrupts and SPU free-run, while a looping VAG has no such block. The block matters only to SpuGetIRQ(), SpuGetIRQAddr(), SpuSetIRQ(), SpuSetIRQAddr(), SpuSetIRQCallback() and the SpuSt streaming functions. A program that uses none of them may therefore remove the block, which saves up to 4 KB of SPU RAM in one VAB. The data size in the VAG header must then be corrected before the VAB is built.²

Voices

libspu sets the following attributes independently for each of the 24 ADPCM voices: the volume, with left and right set separately, the pitch, the address of the waveform data in the sound buffer, the envelope (ADSR) and the loop point. Key on and key off are also set for each voice. The attributes may be changed while key on is in effect and the voice sounds. It is therefore possible to vary the pitch during a note, and to repeat a sound while its loop point changes.²

Noise

The SPU has one noise generator, which any voice may play in place of waveform data in the sound buffer. SpuSetNoiseVoice() selects the voices that play the noise generator, and SpuGetNoiseVoice() returns them. The noise has an envelope like other voices, and SpuSetNoiseClock() changes the noise clock while the sound plays to vary the noise tone.²

Pitch LFO

SpuSetPitchLFOVoice() makes two adjoining voices produce a low frequency oscillator (LFO) effect on pitch. Because the volume of one voice modulates the pitch of the next, two voices make one tone. The final pitch is NewPitch(n) = (1 + V(n-1)) x Pitch(n), where V(n-1) is the volume of voice n-1 as it changes with time and Pitch(n) is the pitch originally set for voice n.²³

Reverb

Reverb is provided as templates whose parameters can be adjusted, and only one type of reverb is active at a time. SpuSetReverbVoice() turns reverb on or off for each voice, and SpuSetCommonAttr() applies it to the CD input and the external digital input.³

Reverb uses the sound buffer as its work area, from an offset address that depends on the reverb mode. The area below the offset may hold waveform data. The work area must be cleared before the reverb depth is raised, or noise is produced, and setting the mode sets the depth to 0. The mode is therefore set well in advance with SpuSetReverb() and SpuSetReverbModeParam(), and SpuSetReverbDepth() sets the depth when reverb is needed.³

The size of the work area changes only when SpuSetReverbModeParam() sets a new mode. SpuReserveReverbWorkArea() keeps the work area out of the sound buffer memory management. In that case SpuMalloc() allocates from 0x1010 up to 0x7ffff minus the work area. Without a reserved area SpuMalloc() may use the whole range 0x1010 to 0x7ffff, but SpuSetReverb(SPU_ON) then fails if the needed area is already allocated. A program that uses reverb must set the mode SPU_REV_MODE_OFF with SpuSetReverbModeParam() and call SpuSetReverb(SPU_OFF) when it exits. Otherwise noise may occur the next time a program runs.³⁴

Sound Buffer Transfer

SpuWrite() transfers waveform data from main memory to the sound buffer and SpuRead() transfers it back. SpuSetTransferStartAddr() sets the sound buffer address before each transfer. There are two transfer modes:⁴

DMA transfer is the default, and SpuSetTransferMode() changes the mode. After a DMA transfer the program calls SpuIsTransferCompleted(). An I/O transfer blocks the CPU, so SpuIsTransferCompleted() always returns 1 for it. DMA transfer is required while playback continues, and it is always used from the sound buffer to main memory. The main memory address must then lie in a large global area or in the heap. A stack area or an automatic variable cannot be used. If CdInit() is not called before SpuInit(), the completion of a waveform transfer may fail.⁴

SpuWrite0() clears an area of SPU RAM, and SpuWritePartly() transfers in steps. The sound buffer has no active memory management. Data transferred to the following areas cannot be used as waveform data:⁵

Sound Buffer Interrupt

The SPU reads the sound buffer at any time while it decodes. It can therefore generate a hardware interrupt request when a specific address is accessed. SpuSetIRQAddr() sets the address, SpuSetIRQ() enables or disables the interrupt and SpuSetIRQCallback() sets the function called on it. SpuGetIRQ() and SpuGetIRQAddr() return the current settings.⁵

Memory Management

Sound buffer memory management is limited. It keeps a table of occupied memory and reports only that information. SpuInitMalloc() sets up the table, SpuMalloc() allocates an area of SPU RAM, SpuMallocWithStartAddr() allocates an area at a given start address and SpuFree() deletes an area from the table.⁵⁶

External Input

The SPU has two external inputs, the CD input and the external digital input. Both sample at 44.1 kHz, and the SPU mixes them digitally with its own output and may send them to reverb. SpuInit() resets the CD volume to zero. The program therefore calls CdInit() first and SpuInit() second, and sets the CD volume after both.⁶

Decoded Data

The SPU writes the first 0x1000 bytes of the sound buffer 16 bits at a time at each 44.1 kHz clock. It writes the CD input after volume processing and voices 1 and 3 after envelope processing. Each of these buffers is 0x400 bytes in two halves. By reading the half that is not being written, a program can take up to 100 samples (100 / 44100 = 0.0022 seconds) at a time, and SpuReadDecodedData() performs the transfer.⁶

SPU Streaming

The SPU plays only waveform data that fits in SPU RAM, which holds at most 512 KB. The SPU streaming functions play longer waveforms by transferring sections of the data to a stream buffer in SPU RAM while it plays. They are part of libspu and are separate from the streaming functions of libcd.⁷

The data is a VB file holding one VAG without its 48-byte header. A stream buffer is allocated in SPU RAM for each voice, up to 24, and all stream buffers have the same size and pitch. Main memory must always hold at least half a stream buffer of data for each stream. During a transfer the library marks the waveform in main memory and destroys it in units of half the stream buffer. A section used twice is therefore reloaded from the CD before its second transfer.⁷

Streaming has four states. In the idle state no stream is processed and the library puts no load on the CPU. In the preparation state the first half of each stream buffer is filled, so that playback starts without delay. In the transfer state the voices sound and each half of the stream buffer is refilled in turn. In the termination state all streams end and no new requests are accepted. Processing then returns to idle.⁷⁸

Three callbacks report the progress, and their arguments name the streams concerned. The preparation finished callback is called when the initial transfer ends. The transfer finished callback is called each time half a stream buffer has been transferred, and it must set the attributes of the next transfer. The stream finished callback is called when a terminated stream has finished playing.⁸

All streams fill the same half of their buffers at the same time. A stream that is prepared or started during the transfer state therefore waits until the other streams reach the right half, and a larger stream buffer gives a longer lag. A smaller buffer, however, spends more time in callbacks for the SPU DMA and the SPU IRQ.⁹¹⁰¹¹

SpuStInit() initializes the streaming and returns an SpuStEnv structure, whose size member sets the stream buffer size of all streams. Its low_priority member, when SPU_ON, gives the streaming a lower priority than graphics processing. SpuStTransfer(SPU_ST_PREPARE, voices) prepares the streams and SpuStTransfer(SPU_ST_PLAY, voices) starts them with key on.¹⁰¹¹¹²

To end a stream, the transfer finished callback sets voice[].status to SPU_ST_STOP and voice[].last_size to the size of the remaining data. Key off is not automatic and must be performed by the program after the stream ends. The manual recommends setting the volume of the voice to 0 instead, since a key off may lag. SpuStQuit() ends the streaming when all streams are idle.¹⁰¹²

Use With libsnd

SsInit() of libsnd calls SpuInit() and SpuInitMalloc() itself. The memory table then allows 32 areas, and each open VAB uses one, so a program that needs more areas calls SpuInitMalloc() again after SsInit(). libsnd controls all 24 voices dynamically. SsSetReservedVoice() with a value below 24 therefore leaves the remaining voices to libspu.¹³

libspu can transfer VAB data, but the header and attribute information is not kept, so VABs are transferred with libsnd. libsnd cannot use the libspu transfer completion callback, which must be NULL before SsVabTransBody(), and SsVabTransCompleted() reports the end of the transfer instead. libspu has no functions for SEQ and SEP data, so a sequence driver written with libspu uses the root counter and event functions of libapi for timing.¹³

Structures

In the tables below, Introduced is the run-time library version that added the item.¹⁴

libspu has the following structures:¹⁴

Functions

libspu has the following functions:¹⁵

References