"SBStudio PAC File Format"

The following file format specification has been adapted to The Sonic Spot's Guide layout with permission from the original author, Henning Hellstrøm. A link to the original specification can be found at the bottom of this page.

This document should be all you need write your own PAC and SOU file load/save routines. If you have any questions, you can e-mail the author at henning.hellstrom@azlan.no.

Overview
Data Format

Overview

SBStudio has its own song file format called PAC or package. A PAC file contains all of the sheets/patterns and sounds belonging to a song. A sound can also be saved separately as a SOU file.

The PAC format was introduced with SBStudio 2, which saved PAC version 1.4 files. SBStudio 3 saves version 1.6 files. This document will describe these two versions.

Data Format

PAC and SOU files are made up of data blocks, similar to chunks found in standard RIFF files, each starting with a block ID and data size. The ID is a four byte string and the data size is a four byte number, also known as a long integer. This makes the file format easy to support and upgrade and loaders can easily skip data they don't recognize.

Offset	Size	Description
0x00	4	Chunk ID
0x04	4	Chunk Data Size
0x08	Chunk Data Bytes
PAC Block Format

One tricky thing about working with blocks in some PAC files is that a couple of block types ("SONG" and "SND ") may have a data size of 0, even though they "contain" sub-chunks of data. It may be inconsistent between PAC and SOU files as well as the different format versions but it isn't a huge problem because a file loader will simply go on and skip following sub-chunks if they are unrecognized. These 0 data sized blocks can be simply thought of as markers, signaling the start of a new set of information. More details about these blocks are discussed below in their corresponding sections below.

Since the PAC and SOU file formats are native to MS-DOS and therefor Intel processors, all data values are stored in Little-Endian (least significant byte first) order.

The rest of this document goes through the different types of blocks, describing the format of their data bytes and what they mean. You can use the table of contents at the beginning of this document to help find the block type you are interested in.

Package ID Block - "PACG"

This block can be used to verify that a file is actually a PAC file. It is always located at the beginning of a PAC file and has a data size of the entire file minus it's 8 bytes of block ID and data size information.

Offset	Size	Description	Value
0x00	4	Block ID	"PACG"
0x04	4	Block Data Size	file size - 8
0x08	PAC file contents

Package ID Block Format

Package Information Block - "PAIN"

This block is usually the first block inside of the Package ID Block. It is used to specify the format and program version numbers as well as the number of sounds in the package file.

Offset	Size	Description	Value
0x00	4	Block ID	"PAIN"
0x04	4	Block Data Size	depends on format version
0x08	2	Format Version	0 - 0xFFFF
0x0A	2	SBStudio Version	0 - 0xFFFF
0x0C	2	Number of Sounds	0 - 0xFFFF

Package Information Block Format

Format Version
The format version specifies the file format version number using two bytes. The first byte defines the major version number and the second byte specifies the minor version number.

SBStudio Version
The SBStudio version specifies the program version number that was used to create the file. Like the Format Version, the first byte defines the major version number and the second byte specifies the minor version number.

Number of Sounds
The number of sounds specifies the number of audio samples included in this file. The actual sounds are specified in "SOU " blocks.

Package Origin Block - "PAOR"

This block contains information about the program used to create the package and usually comes after the Package Information block. It was introduced in with Format Version 1.6.

Offset	Size	Description	Value
0x00	4	Block ID	"PAOR"
0x04	4	Block Data Size	depends on format version
0x08	?	Program Information	program specific

Package Origin Block Format

Song Block - "SONG"

This block marks the start of a song structure which is where the sheets and song settings are stored. SBStudio 2 had the option to save song files with only this structure, but newer versions no longer allow this. This block usually follows the Package Information Block.

Offset	Size	Description	Value
0x00	4	Block ID	"SONG"
0x04	4	Block Data Size	See Below

Song Block Format

Block Data Size
The block data size is the file size - 8 if it's at the beginning of a song file and 0 if it's inside a package.

Song Name Block - "SONA"

This block is used to specify the song name as an ASCII string. SBStudio supports up to 40 bytes, but the file format specification does not place this limit on the length.

Offset	Size	Description	Value
0x00	4	Block ID	"SONA"
0x04	4	Block Data Size	String Length
0x08	ASCII String

Song Name Block Format

Song Order List Block - "SOOR"

This block is used to define the order which the sheets will be played. Two bytes per are used for each entry in the order list.

Offset	Size	Description	Value
0x00	4	Block ID	"SOOR"
0x04	4	Block Data Size	Entries * 2
0x08	Array of Entries

Song Order List Block Format

Song Information Block - "SOIN"

This block is used to specify various information about a song. It's size is format version specific, but all versions share the same previous version information.

Offset	Size	Description	Value
0x00	4	Block ID	"SOIN"
0x04	4	Block Data Size	depends on version
0x08	1	Song Speed	1 - 31
0x09	1	Song BPM	32 - 255
0x0A	2	Number of Sheets	1 - 255
0x0C	1	Number of Audio Channels	4 - 20
0x0D	1	Number of Note Rows per Sheet	64
0x0E	1	Bytes per Channel Cell	5
0x0F	1	Sheet Format	(see below)
0x10	x	Audio Channel Pan Positions	0 - 15 each

Song Information Block Format

Sheet Format
The sheet format specifies how the following sheet data is stored. If the top bit of this byte is 0, the sheet data is unpacked. If the top bit is 1, the sheet data is packed (see sheet data block for details).

Audio Channel Pan Positions
These bytes specify the pan position for each Audio Channel. One byte is used for each channel and the value may range from 0 - 15 (0 = left, 8 = center, 15 = right). These pan positions are only found in format version 1.4. Later version use the Song Channel Settings Block for defining Pan values.

Song Channel Settings Block - "SOCS"

This block is used to specify the various pan positions and effects levels for each channel. It is always found in a song block and was added is format version 1.6.

Offset	Size	Description	Value
0x00	4	Block ID	"SOCS"
0x04	4	Block Data Size	6
0x08	1	Channel Number	1 - 20
0x09	1	Pan Position	0 - 255
0x0A	1	Reverb Level	0 - 255
0x0B	1	Chorus Level	0 - 255
0x0C	1	Filter Level	0 - 255
0x0D	1	Resonance Level	0 - 255

Song Channel Settings Block Format

Channel Number
The channel number byte specifies which channel the following pan position and effects levels correspond to.

Pan Position
The pan position value 0 = left, 128 = center, 255 = right.

Effect Levels
The effect level 0 = off/minimum, 255 = maximum.

Song Channel Name Block - "SOCN"

This block is used to specify the name of a channel. It is always found in a song block and was added is format version 1.6.

Offset	Size	Description	Value
0x00	4	Block ID	"SOCN"
0x04	4	Block Data Size	string length
0x08	ASCII String

Song Channel Name Block Format

Song Sheet Block - "SOSH"

This block is used to define the contents of all the cells of a sheet. It is always located within a Song Block.

Offset	Size	Description	Value
0x00	4	Block ID	"SOSH"
0x04	4	Block Data Size	depends on format
0x08	Sheet Data

Song Sheet Block Format

Sheet Data
The format of the sheet data depends on the values specified in the Song Information Block.

A sheet consists of 5 bytes per channel in 64 rows. The 5 bytes describe one cell with a note number, sound number, note volume, command and parameter. The format is as follows:

Offset	Size	Description	Value
0x00	1	Note Number	see below
0x01	1	Sound Number	1 - 255, 0 = no change
0x02	1	Volume	1 - 65, 0 = no change
0x03	1	Command	0x00 - 0xFF
0x04	1	Command Parameter	0x00 - 0xFF

Sheet Cell Format

Note Number
A value of 0 means no note. In format version 1.4, a value of 2 - 49 may is used where 2 = C-1, 3 = C#1 ... 49 = B-4. In format version 1.6 2 = note off, 3 = C-1, 4 = C#1 ... 74 = B-5.

SBStudio saves all sheets in a packed format. The packed format is very simple, but may sometimes dramatically reduce the file size.

When loading sheets, you should always assume they are packed. This will make your loader compatible with both packed and unpacked sheets.

In a packed sheet, byte 0 or 2 in the 5 byte channel cell can contain a special byte. The special bytes are:

Value	Meaning
0xFD	End of channel cell. Next byte is the first byte of the next channel cell.
0xFE	End of sheet row. Next byte is the first byte of the next row.
0xFF	End of sheet.

Special Sheet Cell Bytes

Sound Block - "SND "

This block is used to define a sound. It is located after Song Blocks in a PAC or at the start of a SOU file.

Offset	Size	Description	Value
0x00	4	Block ID	"SND "
0x04	4	Block Data Size	see below
0x08	Sound Data (see below)

Sound Block Format

Block Data Size
When found at the beginning of a SOU file, the block data size is equal to the file size - 8. It is 0 if it's inside a package and it simply indicates the start of following sound data blocks.

Sound Name Block - "SNNA"

This block is used to specify the name of a sound. It is located inside or after a Sound Block and may appear in either a PAC or SOU file.

Offset	Size	Description	Value
0x00	4	Block ID	"SNNA"
0x04	4	Block Data Size	string length
0x08	ASCII String

Sound Name Block Format

Sound Information Block - "SNIN"

This block is used to specify sound tuning and format information. It is located inside or after a Sound Block and may appear in either a PAC or SOU file.

Offset	Size	Description	Value
0x00	4	Block ID	"SNIN"
0x04	4	Block Data Size	depends on format
0x08	2	Sound Number (only in PAC)	0 - 0xFFFF
0x0A	2	Middle C Frequency	0 - 0xFFFF
0x0C	1	Fine Tuning	0 - 15
0x0D	2	Sound Volume	0 - 16384
0x0F	2	Sound Type	see below
0x11	4	Loop Start Byte	0 - 0xFFFFFFFF
0x15	4	Loop End Byte	0 - 0xFFFFFFFF
0x19	1	Unused	0

Sound Information Block Format

Sound Data Block - "SNDT"

This block contains raw/uncompressed, signed sample data that makes up the sounds audio waveform signal. It is located inside or after a Sound Block and may appear in either a PAC or SOU file.

Offset	Size	Description	Value
0x00	4	Block ID	"SNDT"
0x04	4	Block Data Size	sample length * (bit depth / 8)
0x08	2	Sample Data

Sound Data Block Format

End Of File Block - "END "

This block signals the end of a PAC or SOU file. It is located at the end of the file.

Offset	Size	Description	Value
0x00	4	Block ID	"END "
0x04	4	Block Data Size	0

End Of File Block Format

Links: The Original PAC and SOU Format Specification
Software: SBStudio