Extended Sound Library (libsnd)
Provides functions for working with sound data on the PlayStation.
| Library | libsnd.lib |
|---|---|
| Header File | libsnd.h |
| SDK | Psy-Q |
Overview
The Extended Sound Library (libsnd) converts sound data so that the PlayStation can use it, and it works with files created by the PlayStation Sound Artist Tool. Its functions access VAB (sound source) data, start and end the sound system and handle music score (SEQ) data. They also produce single sound effects and set the common attributes of the SPU voices. The VAB attribute table can be changed at run time, and effects can be applied to a voice after key on.12
libsnd is designed for MIDI data. For sound effects and music that do not use MIDI data the manual recommends libspu, which is smaller and has less overhead.2
A program that uses libsnd links with libsnd.lib and includes libsnd.h.2
This library is part of the run-time library that Sony distributed with the Psy-Q development tools.3
SEQ Data Format
libsnd defines music in the SEQ and SEP data formats. SEQ is a format 1 Standard MIDI File (SMF) converted for the PlayStation, in which the track and chunk data are merged in time order. Each event is the same as in SMF: a status byte, data of a length fixed by the status and a delta time of up to 4 bytes in variable length form. SEQ data has the following layout:2
| Field | Size |
|---|---|
| Sound ID | 4 bytes |
| Version number | 4 bytes |
| Quarter-note resolution | 2 bytes |
| Tempo | 3 bytes |
| Rhythm | 2 bytes |
| Data | |
| File end | 3 bytes |
SEQ data uses running status, and every note off is written as a note on with velocity 0. SEQ supports note on, note off, program change, pitch bend and the following control changes:24
| Control | Number |
|---|---|
| Bank change | 0 |
| Data entry | 6 |
| Main volume | 7 |
| Panpot | 10 |
| Expression | 11 |
| Damper pedal | 64 |
| External effect depth | 91 |
| NRPN data | 98, 99 |
| RPN data | 100, 101 |
| Reset all controllers | 121 |
SEP Data Format
A SEP (sequence package) holds up to 16 SEQ data files and lets them be managed as one file. A SEQ inside a SEP is accessed with the ID that the SEP returns when it opens and the number of the SEQ. In a SEP, each SEQ has a 2-byte SEQ number, its own resolution, tempo and rhythm, and a 4-byte data size that includes its SEQ end.4
VAB Attributes by Control Change
The NRPN control change sets VAB attribute data from the score. The sequencer sends CC 99 (NRPN MSB) with data1, CC 98 (NRPN LSB) with data2 and CC 6 (data entry) with data3. Data1 is the tone number from 0 to 15, and 16 sets all tones. Values such as reverb depth and feedback apply to the whole SPU and cannot be set for one tone or one MIDI channel.5
The attributes are the following:56
| Attribute | Data1 (CC 99) | Data2 (CC 98) | Data3 (CC 6) |
|---|---|---|---|
| Priority | Tone number | 0 | 0 to 127 |
| Mode | Tone number | 1 | 0 to 4 |
| Limit low | Tone number | 2 | 0 to 127 |
| Limit high | Tone number | 3 | 0 to 127 |
| ADSR (AR-L) | Tone number | 4 | 0 to 127 |
| ADSR (AR-E) | Tone number | 5 | 0 to 127 |
| ADSR (DR) | Tone number | 6 | 0 to 127 |
| ADSR (SL) | Tone number | 7 | 0 to 127 |
| ADSR (SR-L) | Tone number | 8 | 0 to 127 |
| ADSR (SR-E) | Tone number | 9 | 0 to 127 |
| ADSR (RR-L) | Tone number | 10 | 0 to 127 |
| ADSR (RR-E) | Tone number | 11 | 0 to 127 |
| ADSR (SR direction) | Tone number | 12 | 0 to 64: +, 65 to 127: - |
| Reverb type | 16 | 15 | 0 to 9 |
| Reverb depth | 16 | 16 | 0 to 127 |
| Echo feedback | 16 | 17 | 0 to 127 |
| Echo delay time | 16 | 18 | 0 to 127 |
| Delay delay time | 16 | 19 | 0 to 127 |
The vibrato and portamento time and depth parameters are not supported. A value takes effect from the first key on after the data entry is read. The mode and reverb type values are the following:6
| Value | Mode | Reverb type |
|---|---|---|
| 0 | Off | Off |
| 1 | Vibrato | Room |
| 2 | Portamento | Studio A |
| 3 | Portamento and vibrato | Studio B |
| 4 | Reverb | Studio C |
| 5 | Hall | |
| 6 | Space | |
| 7 | Echo | |
| 8 | Delay | |
| 9 | Pipe |
Loops and Marks
NRPN data also marks repeat loops in the music. Data1 = 20 marks the start of a loop with a repeat count from 0 to 127 in data2, where 127 loops continuously, and data1 = 30 marks the end. A loop may be used any number of times but cannot contain another loop, and two loop marks must not share the same delta time.6
Data1 = 40 places a mark that carries any value from 0 to 127 in data2. When the library detects a mark it calls the function registered for it and passes the value. Reverb and repeats are set at one point in the score only and need not be set in each channel.7
VAB Switching
A bank change (CC 0) switches to any VAB ID from 0 to 15, and libsnd ignores CC 32. An incorrect VAB ID can cause faults such as no sound. When a score does not switch VABs, its CC 0 and CC 32 should be deleted, which SMF2SEQ can do during conversion.7
VAG and VAB Formats
libsnd uses two formats for sound data. A VAG is the waveform data of one ADPCM-encoded sampled sound. A piano note or an explosion is one VAG. A VAB manages several VAG files as a single group and holds all the sounds of a scene. Its hierarchical structure supports multi-timbral (multi-sampling) functions.7
A VAB is equivalent to a MIDI bank, and its programs are equivalent to MIDI patch changes. A tone list is the set of attributes of one VAG, and several tone lists may refer to the same waveform with different playback parameters. A VAB has the following limits:7
| Item | Maximum |
|---|---|
| Programs in a VAB | 128 |
| Tone lists in a program | 16 |
| VAG files in a VAB | 254 |
Each attribute in the VAB header can be set at run time through its structure, and the VAB (bank) editor edits all values of the header.8
Function Execution Sequence
The functions are executed in the following order:910
| Step | Functions |
|---|---|
| Initialization | SsInit(), and SsSetTableSize() for the SEQ attribute data area |
| Tick mode setting | SsSetTickMode() |
| Opening data | SsVabOpenHead(), SsVabTransBody() and SsVabTransCompleted() for VAB data. SsSeqOpen() for SEQ data and SsSepOpen() for SEP data. |
| Starting the sound system | SsStart(). Data may also be opened after SsStart(). |
| Required processing | Main volume. CdMix() for CD (DA and XA) stereo or mono. SsSetMono() and SsSetStereo() for the SPU. |
| Closing data | SsVabClose(), SsSeqClose(), SsSepClose() |
| Halting the sound system | SsEnd() |
| Terminating the sound system | SsQuit() |
SEQ playback depends on correct callback timing, and other callback processing such as CD reading can make the tempo uneven. When the program uses VSyncCallback(), it calls SsSeqCalledTByT() inside its own callback function, at a position that matches the processing load. The manual recommends a tick mode below SS_TICK120 for this reason.910
Structures
In the tables below, Introduced is the run-time library version that added the item.11
libsnd has the following structures:11
| Structure | Introduced | Purpose |
|---|---|---|
ProgAtr |
2.x | Program header. |
SndRegisterAttr |
4.1 | SPU register attributes. |
SndVoiceStats |
4.1 | Internal libsnd voice variables. |
SndVolume |
2.x | Volume. |
SndVolume2 |
4.1 | Volume-greater range. |
VabHdr |
2.x | Bank header. |
VagAtr |
2.x | Waveform header. |
_SsFCALL |
3.6 | Function table type referenced in SsSeqOpenJ() and SsSepOpenJ(). |
Functions
libsnd has the following functions:12
| Function | Introduced | Purpose |
|---|---|---|
dmy_Ss... |
3.6 | Test function for low-level MIDI jump table. |
SsAllocateVoices |
4.1 | Compare priorities of a number of voices and allocate them where possible. |
SsBlockVoiceAllocation |
4.1 | Block voice allocation system used by SsUtKeyOn(), SsUtKeyOnV(), and MIDI key on commands. |
SsChannelMute |
3.6 | Select MIDI channels for muting. |
SsEnd |
2.x | Stop the sound system. |
SsGetActualProgFromProg |
4.1 | Convert a program number into a “real” program or offset number. |
SsGetChannelMute |
4.0 | Get muted channel number. |
SsGetCurrentPoint |
3.6 | Get current position in SEQ/SEP data. |
SsGetMute |
2.x | Get mute attribute. |
SsGetMVol |
2.x | Get main volume value. |
SsGetNck, SsSetNck, SsSetNoiseOff, SsSetNoiseOn |
3.1 | Libsnd noise functions (Not supported). |
SsGetRVol |
2.x | Get reverb volume value. |
SsGetSerialAttr |
2.x | Get value of a serial attribute. |
SsGetSerialVol |
3.1 | Get a serial volume value. |
SsGetVoiceMask |
4.1 | Get voices blocked from access by voice allocation system. |
SsInit |
2.x | Initialize sound system. |
SsInitHot |
3.1 | Initialize sound system (hot reset). |
SsIsEos |
3.0 | Determine whether a song is being played. |
SsPitchFromNote |
4.1 | Convert MIDI note information into a pitch playback rate. |
SsPlayBack |
3.0 | Restarts currently playing seq/sep data at beginning. |
SsQueueKeyOn |
4.1 | Set voices in key on queue to be processed at next tick callback. |
SsQueueRegisters |
4.1 | Place values in register queue to be set at next tick callback. |
SsQueueReverb |
4.1 | Set voices in reverb queue to be processed at next tick callback. |
SsQuit |
3.0 | Terminate the sound system. |
SsSepClose |
3.0 | Close SEP data. |
SsSepOpen |
3.0 | Open SEP data. |
SsSepOpenJ |
3.6 | Open SEP data (function table version). |
SsSepPause |
3.0 | Pause the reading of SEP data. |
SsSepPlay |
3.0 | Read (play) SEP data. |
SsSepReplay |
3.0 | Resume (replay) reading SEP data. |
SsSepSetAccelerando |
3.0 | Accelerate the tempo. |
SsSepSetCrescendo |
3.0 | Crescendo (valid for individual SEQ in SEP). |
SsSepSetDecrescendo |
3.0 | Decrescendo (valid for individual SEQ in SEP). |
SsSepSetRitardando |
3.0 | Slow the tempo. |
SsSepSetVol |
3.0 | Set SEP volume (valid for individual SEQ in SEP). |
SsSepStop |
3.0 | Stop reading SEP data. |
SsSeqCalledTbyT |
3.0 | Interpret SEQ/SEP data and carry out playback. |
SsSeqClose |
3.0 | Close SEQ data. |
SsSeqGetVol |
3.0 | Get SEQ volume. |
SsSeqOpen |
3.0 | Open SEQ data. |
SsSeqOpenJ |
3.6 | Open SEQ data (function table version). |
SsSeqPause |
3.0 | Pause SEQ data reading. |
SsSeqPlay |
3.0 | Read (play) SEQ data. |
SsSeqPlayPtoP |
4.2 | Read SEQ data (play interval). |
SsSeqReplay |
3.0 | Resume SEQ data reading (Replay) . |
SsSeqSetAccelerando |
3.0 | Quicken tempo. |
SsSeqSetCrescendo |
3.0 | Crescendo. |
SsSeqSetDecrescendo |
3.0 | Decrescendo. |
SsSeqSetNext |
3.0 | Specify SEQ data to play next after a given SEQ. |
SsSeqSetRitardando |
3.0 | Slow tempo. |
SsSeqSetVol |
3.0 | Set SEQ volume. |
SsSeqSkip |
4.2 | Skip SEQ data. |
SsSeqStop |
2.x | Terminate SEQ data reading. |
SsSetAutoKeyOffMode |
3.0 | Set automatic KeyOff mode. |
SsSetCurrentPoint |
4.2 | Set data address in SEQ/SEP. |
SsSetLoop |
3.0 | Set song repetition count. |
SsSetMarkCallback |
3.0 | Register a function to be called when a mark is detected. |
SsSetMono |
2.x | Set monaural mode. |
SsSetMute |
2.x | Sets Muting. |
SsSetMVol |
2.x | Set main volume value. |
SsSetNext |
3.2 | Set the next SEQ/SEP data. |
SsSetReservedVoice |
3.0 | Declare the number of voices to be allocated by libsnd. |
SsSetRVol |
2.x | Set reverb volume values. |
SsSetSerialAttr |
2.x | Set a serial attribute. |
SsSetSerialVol |
2.x | Set serial volume. |
SsSetStereo |
2.x | Set stereo mode. |
SsSetTableSize |
3.0 | Specify the area of a SEQ/SEP data attribute table. |
SsSetTempo |
3.0 | Set a tempo. |
SsSetTickCallback |
2.x | Set the TickCallBack function called with every TICK. |
SsSetTickMode |
2.x | Set tick mode. |
SsSetVoiceMask |
4.1 | Block voice allocation system from using the specified voices. |
SsSetVoiceSettings |
4.1 | Set internal libsnd variables for a voice. |
SsStart |
2.x | Start the sound system. |
SsStart2 |
3.1 | Start the sound system (VSyncCallback version). |
SsUnBlockVoiceAllocation |
4.1 | Release voice allocation system used by SsUtKeyOn(), SsUtKeyOnV(), and MIDI key on commands. |
SsUtAllKeyOff |
3.0 | Key off all voices. |
SsUtAutoPan |
2.x | Automatically change panning. |
SsUtAutoVol |
2.x | Automatically change voice volume. |
SsUtChangeADSR |
2.x | Change ADSR. |
SsUtChangePitch |
2.x | Change the pitch. |
SsUtFlush |
3.0 | Execute remaining queued KeyOn/KeyOff requests. |
SsUtGetDetVVol |
2.x | Get detailed value of voice volume. |
SsUtGetProgAtr |
2.x | Get a program attribute table. |
SsUtGetReverbType |
3.0 | Get a reverb type. |
SsUtGetVabHdr |
2.x | Get VAB attribute header. |
SsUtGetVagAddr |
3.1 | Get an SPU buffer address stored by VAG. |
SsUtGetVagAddrFromTone |
3.3 | Get SPU buffer address where VAG data is stored. |
SsUtGetVagAtr |
2.x | Get tone attribute table (VagAtr). |
SsUtGetVBaddrInSB |
3.0 | Get address in sound buffer to which VAB data has been transferred. |
SsUtGetVVol |
2.x | Get voice volume. |
SsUtKeyOff |
3.0 | Key off voice. |
SsUtKeyOffV |
3.0 | Key off a voice. |
SsUtKeyOn |
3.0 | Key on a voice. |
SsUtKeyOnV |
3.0 | Key on a voice. |
SsUtPitchBend |
2.x | Apply a pitch bend. |
SsUtReverbOff |
3.0 | Turn off Reverb. |
SsUtReverbOn |
3.0 | Turn on Reverb. |
SsUtSetDetVVol |
3.0 | Set a detailed value of voice volume. |
SsUtSetProgAtr |
2.x | Set a program attribute table. |
SsUtSetReverbDelay |
3.0 | Set a Delay volume. |
SsUtSetReverbDepth |
3.0 | Set a reverb depth. |
SsUtSetReverbFeedback |
3.0 | Set a feedback volume. |
SsUtSetReverbType |
3.0 | Set reverb type. |
SsUtSetVabHdr |
2.x | Set a VAB attribute header. |
SsUtSetVagAtr |
2.x | Set a tone attribute table (VagAtr). |
SsUtSetVVol |
2.x | Set voice volume. |
SsVabClose |
2.x | Close VAB data file. |
SsVabFakeBody |
3.0 | Assign a VAB ID to VAB data in the sound buffer. |
SsVabFakeHead |
3.0 | Open a new VAB header for a given VAB body. |
SsVabOpen |
3.0 | Open VAB data. (Not recommended for use). |
SsVabOpenHead |
3.0 | Open a VAB header. |
SsVabOpenHeadSticky |
3.0 | Open a VAB header and specify transfer address in sound buffer. |
SsVabTransBody |
3.0 | Transfer sound source data. |
SsVabTransBodyPartly |
3.0 | Transfer sound source data in segments. |
SsVabTransCompleted |
3.0 | Get VAB data transfer state. |
SsVabTransfer |
3.0 | Recognize and transfer sound source data. |
SsVoiceCheck |
4.1 | Verify tone information played by a voice that is to be modified. |
SsVoKeyOff |
3.0 | Key off. |
SsVoKeyOn |
3.0 | Key on. |
References
-
^ Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page x.
-
^ a b c d e Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-3.
-
^ Sony Computer Entertainment Inc. Programmer Tools CD (DTL-S2002), README.TXT. 11/26/96. Section "CD-ROM Contents - Highlights", directories \PSX and \PSYQ.
-
^ a b Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-4.
-
^ a b Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-5.
-
^ a b c Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-6.
-
^ a b c d Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-7.
-
^ Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-8.
-
^ a b Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-9.
-
^ a b Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 15-10.
-
^ a b Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 14-5 to 14-12.
-
^ Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 14-14 to 14-133.