ModdingWiki - User contributions [en-gb]

DSIK Module Format

2024-07-10T14:32:15Z

Saga: Effects > 0F in OpenMPT were confused with effects from another .DSM format; and 7-bit panning comes from DSMI.

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 65,535 (only 255 playable)
| NumOrders = 128
| Tags = Title, instrument names, instrument filenames
| Games =
{{Game|Trugg}}
{{Game|Flying Tiger}}
{{Game|Rollin}}
}}

The '''DSIK Module Format''' is the music format used by the ''Digital Sound Interface Kit'' by Carlos Hasan. This was a C and Pascal library for game authors to simplify sound card programming.

== File format ==

The file is a '''non-standard''' [[Resource Interchange File Format (RIFF)]] structure. It is exactly the same as a standard RIFF file, except that the padding bytes between chunks have been omitted. So if the length of a chunk is an odd number, the padding byte should not be included and the following chunk will not start on a word boundary.

The files are composed of the following chunks:

* RIFF (type: DSMF)
** SONG
** INST
** PATT

The data in each chunk is explained below.

=== SONG chunk ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, null-terminated
|-
| UINT16LE || version || File version
|-
| UINT16LE || flags ||
|-
| UINT32LE || pad ||
|-
| UINT16LE || numOrders || Number of valid entries in <tt>orders</tt>
|-
| UINT16LE || numSamples ||
|-
| UINT16LE || numPatterns ||
|-
| UINT16LE || numChannels ||
|-
| UINT8 || volGlobal || Global volume
|-
| UINT8 || volMaster || Master volume
|-
| UINT8 || initialSpeed ||
|-
| UINT8 || initialBPM ||
|-
| UINT8[16] || channelMap ||
|-
| UINT8[128] || orders || Order list. First value is index of first pattern to play, etc.
|}

=== INST chunk ===

This chunk stores all the instruments in the song. There are multiple '''INST''' chunks in the file, one per instrument. The data in each chunk is as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[13] || filename || Instrument filename, null-terminated
|-
| UINT16LE || flags || Zero or more of: 1=loop active, 2=signed PCM, 4=packed PCM, 64=delta PCM
|-
| UINT8 || volume || Default volume of the sample if not volume is given when a note is played. The range is from 0 (silent) to 64 (loudest), note this is 65 different values.
|-
| UINT32LE || length || Length of the sample data, in bytes.
|-
| UINT32LE || loopStart || Position of the loop start point, in bytes, relative to the start of the sample data.
|-
| UINT32LE || loopEnd || Position of the loop end point, in bytes, relative to the start of the sample data.
|-
| UINT32LE || address_ptr || Used internally for holding in-memory address of sample data, ignore when reading and write as zero.
|-
| UINT16LE || midCRate || Default is 8363
|-
| UINT16LE || period || Default for middle-C is 428
|-
| char[28] || title || Sample name, null-terminated
|-
| BYTE[length] || data || Sample data, 8-bit mono PCM
|}

Sample data must be 8-bit mono PCM, signed or unsigned based on <tt>flags</tt> {{TODO|Confirm that signed PCM actually works}}. Other formats are rejected by the DSIK library. Some samples appear to be truncated .wav files and still have the 'data' fourcc visible, however this is not part of the format and these bytes will be played as audio data, causing an audible click at the start of playback.

The period is calculated from a sample rate (in Hertz) as <code>period = 8363 * 428 / Hertz</code>

=== PATT chunk ===

This chunk stores all the patterns in the song. There are multiple '''PATT''' chunks in the file, one per pattern. The data in each chunk is as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || length || Length of pattern data, in bytes, including this length field also
|-
| UINT8[length - 2] || data || Pattern data, see below
|}

The pattern data is comprised of a flag byte, followed by a variable number of data bytes depending on the value of the flag. This is very similar to [[S3M Format]] but the bit fields are different. The flag byte is broken down as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| Note present
| Instrument present
| Volume present
| Command present
|colspan=4 align=center| Channel number
|}

* If the entire value is zero, the row number is incremented and the next flag is read. Otherwise:
* If the flag indicates a note is present, the next byte is the note. Note numbers are semitones, with note 49 being middle C, note 50 being C#4, note 51 being D4, etc. Adding 11 to the note number will turn them into standard MIDI note numbers.
* If an instrument is present, the next byte is the zero-based index of the instrument to use.
* If a volume is present, the next byte is the volume for this note/channel. The range is from 0 (silent) to 64 (loudest), note this is 65 different values.
* If a command is present, the next two bytes are the command and value respectively. Standard .mod commands appear to be used {{TODO|Confirm}}

After these bytes have been read, the next flag byte is read. Once 64 rows have been read, the end of the pattern data should have been reached.

If the instrument is read but it is zero, then the previous instrument on that channel should be used instead (same as S3M).

Effects are the same as in MOD files (i.e. 0x00 through 0x0F are valid effect commands).

Effect 0x08 is 7-bit panning (0x00 = left, 0x80 = right) with parameter 0xA4 enabling surround, as introduced by Dual Module Player and the DSMI library.

=== Timing ===

See [[S3M Format#Timing]] for a discussion on timing using the <tt>initialBPM</tt> and <tt>initialSpeed</tt> values.

=== Design issues ===

The file format suffers from a number of design inconsistencies:

* The '''DSMF''' format should have been registered with Microsoft as it is in uppercase, however this does not appear to have been done
* The '''INST''' and '''PATT''' chunks should have been placed inside '''LIST''' chunks, in the spirit of the RIFF format
* The instrument chunk includes a length field for the sample data, however this is redundant as the chunk itself already has a length. The two length fields do make it possible to store additional data between the end of the sample data and the end of the chunk, which would normally be ignored, however it seems simpler to just define a new chunk type if new data needs to be stored without breaking backwards compatibility.
* The instrument chunk stores an address field even though this is only used during playback and does not need to be stored in the file.
* The pattern chunk also has an extra field to store the length of the pattern data. However the value in this field includes the length of the field itself, making the value identical to the RIFF chunk's length field. The result is that the identical value is written twice, once as a 32-bit value for the RIFF PATT chunk and then immediately again as a 16-bit value.
* The number of instruments and patterns is stored in the '''SONG''' chunk, however this is redundant as the values can be calculated from the number of '''INST''' and '''PATT''' chunks respectively.
* There is a 16-bit value for the number of orders, allowing up to 65,535 orders in the song, yet there is a fixed-length array allowing only 128 orders.
* The pattern count is 16-bit allowing up to 65,536 patterns in the song, but the order list is made up of 8-bit values, meaning only the first 256 patterns can be played.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Many
| canImport = Many
| editHidden = No
| editMetadata = Yes
| notes = Minimal support for effects
}}
{{FileFormatTool
| Name = Chronos Module Converter
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .mtm .dsm .psm
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Most accurate for converting .dsm to .s3m
}}
{{FileFormatTool
| Name = DSIK's <tt>conv.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .669 .mtm
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{FileFormatTool
| Name = ModPlug
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Plays at wrong tempo (no support for effect 0x0F)
}}
{{FileFormatTool
| Name = OpenMPT
| Platform = Any
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{EndFileFormatTools}}

== External links ==

* The original Digital Sound Interface Kit library is available as <tt>dsik_c.zip</tt> or <tt>dsik_pas.zip</tt> for the C and Pascal versions respectively, from various FTP sites such as [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/wgt/ lanet.lv]

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] by reading the DSIK sample code, with the pattern data documented from reading the OpenMPT source code. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

[[Category:DSIK]]

ProTracker Studio Module

2023-03-28T21:16:26Z

Saga: /* Order sub-segment */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop. The format not used in Sinaria will be called "regular" in this document.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "regular" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "Sinaria" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the "regular" variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. You may want to deal with this by first reading for bytes, and if they are equal to "PATT", read four more bytes for the pattern ID.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the regular or Sinara version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0  ", "P12 " in regular format or "PATT0   " in Sinaria format, see above) - join those to get the complete order list.
* $02 (7 Bytes): Play Range: The command appears to take three 16-bit values (PLAY.EXE displays "xx from yy to zz"), however parsing of the next opcode continues at the position of the third parameter, and PLAY.EXE crashes with a division error. This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $03 (4 Bytes): Jump Loop: Works the same as $04 Jump Line, but with another byte following after the 16-bit value. The purpose of that byte is unknown. This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $04 (3 Bytes): Jump Line: This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip (3 Bytes): Changes the channel type without specifying pan position. The first byte is the channel index, the second byte is the channel type (see command $0D). This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $06: Transpose (2 Bytes): Does not appear to do anything, regardless of parameter. This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a type byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [https://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [https://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

SBI Format

2023-03-28T17:28:44Z

Saga:

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 1
| NumTracks = 0
| Tags = Title
}}
The '''SBI (Sound Blaster Instrument) Format''' stores a single instrument suitable for playback on a sound card with an OPL2 or OPL3 chip.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "SBI" followed by 0x1A
|-
| [[char]][32] || name || Instrument title (must be NULL-terminated)
|-
| [[BYTE]][16] || inst || Instrument settings (see below)
|}

Some files generated with JuceOPLVSTi erroneously use byte 0x1D instead of 0x1A in the signature.

=== Instrument settings ===

The instrument is in the following format. This is identical to the format used for each instrument in [[CMF Format]] songs and [[IBK Format]] instrument banks.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[BYTE]][5]
|colspan=3|Padding to bring instrument definition up to 16 bytes. Sometimes a byte is missing, resulting a 51-byte file rather than a 52-byte file. It is probably safer to not expect this padding to exist at all.
|}

==== Percussive instruments ====

In the basic SBI format, there is no indication as to whether a given instrument should be played in melodic or percussive mode. Playing an instrument destined for one mode in the other usually sounds quite bad.

==== SBI format extension ====

The SBTimbre editor takes advantage of the 5-byte padding area to store additional information.
If any percussion-related fields have non-zero values, the timbre can be identified as a drum instrument.

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT8]]||iPercVoc||Percussion voice number (BassDrum=6, Snare=7, Tomtom=8, Cymbal=9, HighHat=10)
|-
|[[INT8]]||iTranspos||Note offset in semitones
|-
|[[UINT8]]||iPercPitch||Fixed percussion pitch (MIDI note 0-127)
|-
|[[BYTE]][2]
|colspan=2|Reserved
|}

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[SBI Format|.sbi]]
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{FileFormatTool
| Name = [[SBANK]]
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Сan convert SBI between [[AdLib Instrument Format|AdLib INS]] format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{EndFileFormatTools}}

ProTracker Studio Module

2023-03-27T21:12:38Z

Saga: /* Order sub-segment */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop. The format not used in Sinaria will be called "regular" in this document.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "regular" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "Sinaria" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the "regular" variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. You may want to deal with this by first reading for bytes, and if they are equal to "PATT", read four more bytes for the pattern ID.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the regular or Sinara version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0  ", "P12 " in regular format or "PATT0   " in Sinaria format, see above) - join those to get the complete order list.
* $02: Play Range: N/A
* $03: Jump Loop: N/A
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip (3 Bytes): Changes the channel type without specifying pan position. The first byte is the channel index, the second byte is the channel type (see command $0D). This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $06: Transpose (2 Bytes): Does not appear to do anything, regardless of parameter. This command is not used in any known soundtrack, and is not written by CONVERT.EXE.
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a type byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

N/A: This chunk is not used in any game soundtrack. The length and meaning of its parameters is unknown.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [https://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [https://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2023-03-27T21:06:03Z

Saga: /* Order sub-segment */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop. The format not used in Sinaria will be called "regular" in this document.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "regular" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "Sinaria" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the "regular" variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. You may want to deal with this by first reading for bytes, and if they are equal to "PATT", read four more bytes for the pattern ID.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the regular or Sinara version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in regular format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $02: Play Range: N/A
* $03: Jump Loop: N/A
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip (3 Bytes): Changes the channel type without specifying pan position. The first byte is the channel index, the second byte is the channel type (see command $0D). This command is not used in any known soundtrack.
* $06: Transpose (2 Bytes): Does not appear to do anything, regardless of parameter.
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a type byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

N/A: This chunk is not used in any game soundtrack. The length and meaning of its parameters is unknown.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [https://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [https://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2023-03-27T20:57:22Z

Saga: /* Order sub-segment */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop. The format not used in Sinaria will be called "regular" in this document.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "regular" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "Sinaria" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the "regular" variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. You may want to deal with this by first reading for bytes, and if they are equal to "PATT", read four more bytes for the pattern ID.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the regular or Sinara version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in regular format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $02: Play Range: N/A
* $03: Jump Loop: N/A
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip (3 Bytes): Changes the channel type without specifying pan position. The first byte is the channel index, the second byte is the channel type (see command $0D). This command is not used in any known soundtrack.
* $06: Transpose: N/A
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a type byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

N/A: This chunk is not used in any game soundtrack. The length and meaning of its parameters is unknown.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [https://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [https://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

AMF Format

2023-03-22T19:00:05Z

Saga: Created page with "{{Music Infobox | Type = Tracked | Instruments = PCM | NumChannels = 32 | NumTracks = n/a | NumPatterns = 256 | NumOrders = 256 | Tags = Title, instrument names | Game..."

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 32
| NumTracks = n/a
| NumPatterns = 256
| NumOrders = 256
| Tags = Title, instrument names
| Games =
{{Game|Disney's Aladdin}}
{{Game|The Lion King}}
{{Game|PowBall}}
{{Game|H2O}}
{{Game|Tronic}}
{{Game|Pinball World}}
}}

There are two different AMF module formats: Ayslum Music Format (used in [[Crusader: No Remorse]] and [[Crusader: No Regret]]) and the music format introduced by the Digital Sound and Music Interface (DSMI) by Otto Chrons. This article describes the latter format. DSMI and its module format was used in a number of games. Some later games, in particular those published by Webfoot, use a slightly different variant of the format identified by its "DMF" magic bytes (instead of "AMF"). This variant uses delta-encoded samples and omits song and sample names, leading to slightly improved compressability with general-purpose compression algorithms (such as DEFLATE). The AMF format is well-supported by a variety of module players, such as libxmp and libopenmpt.

Karl Morton Music Format

2021-12-23T15:29:56Z

Saga:

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 32 (only 4 usable in-game)
| NumTracks = no limit
| NumPatterns = n/a
| NumOrders = n/a
| Tags = Title, instrument names
| Games =
{{Game|Psycho Pinball}}
{{Game|Micro Machines 2}}
}}

The [[Karl Morton Music Format]] is the music format used by Karl Morton's sound engine used in the games [[Psycho Pinball]], [[Micro Machines 2]] and [[Back To Baghdad]], although the latter only uses its sound effect file format, not the music format. This is not the official name of the format, but as no official tooling or documentation seems to be available for this format, a simple name was chosen based on the sound engine author's name.

In general, this format follows the semantics of the ProTracker MOD format. Knowledge of the MOD format and its features is assumed.

A somewhat unique feature of this format is that subsongs can re-use samples with different metadata. For example, one song in a file might use a specific sample with a default volume of 64, while another song might reference the same sample data but with a default volume of 48. This allows for greater flexibility when reusing those samples between songs.

== File format ==

The format follows an IFF-like structure, but with no explicit file header (the file directly starts with the first chunk).

=== Chunk Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || ID || chunk ID ("SONG" or "SMPL")
|-
| [[UINT32LE]] || length || chunk length, including this header (so must be at least 8)
|}

The first chunk in the file must be a SONG chunk, apart from this the chunk order doesn't matter.

Typically, SONG and SMPL chunks are interleaved, each SONG being followed by the SMPLs it adds to the sample pool shared between SONGs.
But this order should not be relied on.

=== SONG chunk ===

Each subsong is represented by its own SONG chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || song name || null-terminated song name
|-
| SAMPLE_REFERENCE[31] || sample map || maps song samples to those samples in the global sample pool
|-
| [[char]][2] || unknown || always 0 (maybe just padding)
|-
| [[UINT32LE]] || number of channels || between 1 and 4 - file will be rejected if this is > 32. If it's more than 4 but less than 33 the extra channels will simply not be played.
|-
| [[UINT32LE]] || restart position || byte offset into music data
|-
| [[UINT32LE]] || size of music data || should be chunk size - 1108
|-
| [[char]][] || music data || format is explained below
|}

<tt>SAMPLE_REFERENCE</tt> maps samples from the SMPL chunk pool to instrument numbers in the pattern editor (the first <tt>SAMPLE_REFERENCE</tt> is instrument 1, and so on). It is defined as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || must reference one of the SMPL chunks
|-
| [[UINT8]] || MOD finetune || 0...15
|-
| [[UINT8]] || default volume || 0...64
|}

Music data is basically one gigantic pattern and stored in row-major order (like most module formats).
The pattern is played in a strictly linear order, there are no jump commands or pattern loops.
There is per-channel state that stores the last used note, instrument, command and parameter as well as a repeat counter.

To decode one pattern cell:

* If repeat counter > 0: Decrement repeat counter by 1 and reuse note, instrument, command and parameter from previous row. Continue with next channel.
* Read [[UINT8]], let's name it NOTE.
* If (NOTE AND 0x80): Reuse note, instrument, command and parameter from previous row and set repeat counter to (NOTE AND 0x7F). Continue with next channel.
* If NOTE is between 1 and 36 (inclusively), it's a regular note (C-1 to B-3 in ProTracker), otherwise no note is present
* Read [[UINT8]], let's name it INSTRUMENT.
* Set instrument number in this cell to INSTRUMENT AND 0x1F
* If (INSTRUMENT AND 0x80): Repeat previous command and parameter for this channel
* Otherwise, read the two [[UINT8]]s, the command and parameter bytes.
* Continue with next channel.

Command bytes and their translation to ProTracker MOD commands:
* <tt>00</tt>: <tt>Cxx</tt>
* <tt>01</tt>: <tt>EAx</tt>
* <tt>02</tt>: <tt>EBx</tt>
* <tt>03</tt>: <tt>E1x</tt>
* <tt>04</tt>: <tt>E2x</tt>
* <tt>05</tt>: <tt>E5x</tt>
* <tt>06</tt>: <tt>9xx</tt>
* <tt>07</tt>: <tt>3xx</tt>
* <tt>08</tt>: <tt>5xx</tt>
* <tt>09</tt>: <tt>4xx</tt>
* <tt>0A</tt>: <tt>6xx</tt>
* <tt>0B</tt>: <tt>0xx</tt>
* <tt>0C</tt>: <tt>1xx</tt>
* <tt>0D</tt>: <tt>2xx</tt>
* <tt>0E</tt>: <tt>Axx</tt>
* <tt>0F</tt>: <tt>E9x</tt>
* <tt>10</tt>: Instant portamento (like 3FF but is always fully executed on first tick)
* <tt>11</tt>: <tt>ECx</tt>
* <tt>12</tt>: <tt>Fxx</tt>
* <tt>13</tt>: <tt>7xx</tt>
* <tt>14</tt>: <tt>000</tt> (empty command)

Missing MOD effects are: 8, B, D, E3, E4, E5, E6, E7, E8, ED, EE, EF.

Most commands that translate to extended Exy commands can take values > 0x0F as parameters (finetune command ignores high nibble).

The player will jump to the restart position once the repeat counter of each channel has reached 0 and no bytes are left to be read.

If no tempo is specified on the first row of the pattern, the MOD defaults of tempo 125 and 6 ticks per row are assumed.

=== SMPL chunk ===

Every sample is described by its own SMPL chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || null-terminated, referenced by SONG chunks
|-
| [[UINT32LE]] || loop start || in bytes
|-
| [[UINT32LE]] || size of sample data || should be chunk size - 48
|-
| [[char]][] || sample data || in 8-bit signed mono PCM format
|}

Note that a SMPL can be shared between songs and use different finetune and volume values between songs.

== A note on the string format ==

The last character of sample names must be a null-terminator (the engine uses a string comparison not limited to 32 characters when matching samples). 
While it is not required by the engine, the following restrictions are proposed for newly created files to keep the life of developers easy that have to support dozens of files and may thus want to employ heuristics whether files are of a specific type:
It is suggested that all strings (i.e. instances of [[char]][32]) do not use byte values 1 to 31 (so only printable ASCII/ANSI), and after the first null terminator, the rest of the string has to be padded with nulls as well.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [https://openmpt.org/ OpenMPT]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = OpenMPT 1.30 or higher is required.
}}
{{FileFormatTool
| Name = [https://github.com/sagamusix/mod2mus mod2mus]
| Platform = Any
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = MOD
| editHidden = No
| editMetadata = No
| notes = Converts 1-4 channel ProTracker MOD files to MUS
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse-engineered by [[User:Saga|Saga]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

DRO Format

2021-11-14T01:08:40Z

Saga: /* Tools */

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 22 (Dual OPL2 and OPL3)
| NumTracks = 1
}}
The DOSBox Raw OPL (DRO) format is used for storing captured OPL data from a game running in the cross-platform DOS emulator [http://dosbox.sourceforge.net DOSBox].

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[8]||cSignature||"DBRAWOPL" (not NULL-terminated)
|-
|UINT16LE||iVersionMajor||Version number (high)
|-
|UINT16LE||iVersionMinor||Version number (low)
|}

The rest of the header depends on the version. If iVersionMajor is 5 and iVersionMinor is 6, then the version would be called "5.6" here.

=== Version 0.1 ===

The first version of the DRO Format was used up to and including DOSBox version 0.72. Note that the major and minor field names were swapped beginning with DOSBox 0.73, so this version used to be 1.0, but after DOSBox 0.73 it became 0.1 instead.

==== Header ====

The version 0.1 header follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthMS||Length of the song in milliseconds
|-
|UINT32LE||iLengthBytes||Length of the song data in bytes
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8[3]||iHardwareExtra||Rest of hardware type or song data (see below)
|}

''iHardwareType'' is one of the following values:

{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||OPL3
|-
|2||Dual OPL2
|}

In early files, the field was a UINT8, however in most common (recent) files it is a UINT32LE with only the first byte used. Unfortunately the version number was not changed between these revisions, so the only way to correctly identify the formats is to check the three <tt>iHardwareExtra</tt> bytes. If these are all zero then they can safely be ignored (iHardwareType was a UINT32.) If any of the three bytes in <tt>iHardwareExtra</tt> are non-zero, then this is an early revision of the format and those three bytes are actually song data<ref>In the [http://adplug.sourceforge.net AdPlug distribution], tests/samurai.dro is the early one-byte format, and doofus.dro is the later four-byte variant.</ref>.

==== Song data ====

Directly following the header is ''iLengthBytes'' bytes of OPL data. The first byte in the song data will be the OPL register, followed by the byte to send to that register. The "register" can also be one of these control values:

{|class="wikitable"
!Register value!!Data size!!Purpose
|-
|0x00||1||Delay. The single data byte following should be incremented by one, and is then the delay in milliseconds.
|-
|0x01||2||Delay. Same as above only there are two bytes following, in the form of a UINT16LE integer.
|-
|0x02||0||Switch to "low" OPL chip (#0)
|-
|0x03||0||Switch to "high" OPL chip (#1)
|-
|0x04||2||Escape - the next two bytes are normal register/value pairs even though the register might be 0x00-0x04
|-
|Other||1||Anything else should be treated as an OPL register, with the byte following being the data to send to that register.
|}

The delays all need to be incremented by one, as having a delay of zero milliseconds would be a waste of space. Codes 0x02 and 0x03 switch between two OPL chips in dual OPL2 mode, or between register banks in OPL3 mode. These should only be used if the hardware flag in the header indicates the file is in dual-OPL2 or OPL3 format.

All delays are in milliseconds (which can be treated as 1000Hz if converting between other formats.)

=== Version 2.0 ===

Version 2.0 of the DRO Format was introduced with DOSBox 0.73.

==== Header ====

The version 2.0 header also follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthPairs||Length of the song in register/value pairs (TODO: confirm - 1 == one register + one value, or two bytes)
|-
|UINT32LE||iLengthMS||Length of the song data ("chunk" -?) in milliseconds
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8||iFormat||Data arrangement
|-
|UINT8||iCompression||Compression type, zero means no compression (currently only zero is used)
|-
|UINT8||iShortDelayCode||Command code for short delay (1-256ms)
|-
|UINT8||iLongDelayCode||Command code for short delay (> 256ms)
|-
|UINT8||iCodemapLength||Number of entries in codemap table
|-
|UINT8[iCodemapLength]||iCodemap||Codemap table (see below)
|}

''iHardwareType'' is one of the following values: (which are different in v1.0 and v2.0)
{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||Dual OPL2
|-
|2||OPL3
|}
''iFormat'' is one of the following values:
{|class="wikitable"
!''iFormat''!!Description
|-
|0||Commands and data are interleaved (default/as per v1.0)
|-
|1||Maybe all commands, followed by all data (unused? - TODO: Confirm)
|}

Notes:
* ''iLengthMS'' is at a different offset in v1.0 and v2.0
* The ''iShortDelayCode'' value must have one added to it, as per v1.0 (so a short delay of 2 == a 3ms delay)
* The ''iLongDelayCode'' value must have one added to it, then be multiplied by 256 (or "<< 8"), so a long delay of 2 == a 768ms delay
* Because the high bit in each codeword is used to refer to the second OPL2 chip (or the second set of registers in an OPL3), there are only 128 possible codewords (0-127). Therefore ''iCodemapLength'' must always be 128 or less.
* DOSBox dumps a snapshot of the current register state at the beginning of a capture. (Any other registers are assumed initialised to zero.) This means that even an OPL2 only song will appear to have some data sent to the second OPL chip, because of this initial snapshot. To really know whether the second OPL chip is in use, you can find out if it is actually making any sound, like so:
** Examine bit 5 (0x20) on registers 0xB0 to 0xB8. If this bit is set, a note is playing and the chip is being used.
** Check whether bitmask 0x1F on register 0xBD is greater than 0x10 (i.e. <code>if (reg[0xBD] & 0x1F > 0x10) ...</code>). If so, the chip is in percussive mode and a rhythm instrument is being played, so the chip is being used.

===== Codemap table =====
The codemap table maps index numbers to OPL registers. As there are 256 possible OPL registers but only a subset of these actually used, the mapping table allows up to 128 OPL registers to be used in a song. The other 128 (with the high bit set) are used for the second OPL2 chip in a dual-OPL2 capture.

The table is a list of ''iCodemapLength'' bytes, with the index used later in the file. For example this code table:

01 04 05 08 BD

Means that when the song references register #0 the data should be sent to OPL register 0x01, when the song references register #4 the data should go to OPL register 0xBD. If the song references register #128 (i.e. register 128+0), data should be sent to OPL register 0x01 on the '''second''' chip (in dual OPL2 mode) or the second set of registers (OPL3 mode). Likewise register #132 (128+4) is OPL register 0xBD on the '''second''' chip.

==== Song data ====

Directly following the header is the song data in register index and value pairs.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iRegisterIndex||Register to write to. This is an index into the codemap table.
|-
|UINT8||iValue||Value to write to the OPL register
|}

This structure is repeated ''iLengthPairs'' times. Note that while ''iRegisterIndex'' is normally an index into the codemap table, it can also match ''iShortDelayCode'' or ''iLongDelayCode'' if ''iValue'' is to be treated as a delay length (see above.) If the high bit is set (<code>iRegisterIndex & 0x80</code>) then it is a register on the second OPL chip in a dual-OPL2 song (so the high bit should be removed and the value looked up as normal, but then sent to the second OPL chip instead.)

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[AdPlug]]
| Platform = Windows/Linux/DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [http://www.dosbox.com/ DOSBox]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v2-only since 0.73. Produces .dro files as a result of capturing Adlib data from DOS games and applications
}}
{{FileFormatTool
| Name = [http://www.jestarjokin.net/apps/drotrimmer DRO Trimmer]
| Platform = Any (Python)
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Edits .dro files to remove unwanted notes from the start and end
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro to .imf
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro and .imf to .mid
}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = OpenMPT 1.30 and newer can export a DRO v1 register dump for songs that use OPL instruments.
}}
{{EndFileFormatTools}}

== Similar formats ==
* [[RAW Format (Adlib)|Rdos' RAW format]] serves the same purpose, only these files were originally created through the RAC (Rdos Adlib Capture) TSR running under native DOS.
* The [[IMF Format|id Software Music Format (IMF)]] stores Adlib data in a similar manner in order to provide background music in many Apogee games.

== References ==
<references/>

DRO Format

2021-11-14T01:08:20Z

Saga: /* Tools */

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 22 (Dual OPL2 and OPL3)
| NumTracks = 1
}}
The DOSBox Raw OPL (DRO) format is used for storing captured OPL data from a game running in the cross-platform DOS emulator [http://dosbox.sourceforge.net DOSBox].

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[8]||cSignature||"DBRAWOPL" (not NULL-terminated)
|-
|UINT16LE||iVersionMajor||Version number (high)
|-
|UINT16LE||iVersionMinor||Version number (low)
|}

The rest of the header depends on the version. If iVersionMajor is 5 and iVersionMinor is 6, then the version would be called "5.6" here.

=== Version 0.1 ===

The first version of the DRO Format was used up to and including DOSBox version 0.72. Note that the major and minor field names were swapped beginning with DOSBox 0.73, so this version used to be 1.0, but after DOSBox 0.73 it became 0.1 instead.

==== Header ====

The version 0.1 header follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthMS||Length of the song in milliseconds
|-
|UINT32LE||iLengthBytes||Length of the song data in bytes
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8[3]||iHardwareExtra||Rest of hardware type or song data (see below)
|}

''iHardwareType'' is one of the following values:

{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||OPL3
|-
|2||Dual OPL2
|}

In early files, the field was a UINT8, however in most common (recent) files it is a UINT32LE with only the first byte used. Unfortunately the version number was not changed between these revisions, so the only way to correctly identify the formats is to check the three <tt>iHardwareExtra</tt> bytes. If these are all zero then they can safely be ignored (iHardwareType was a UINT32.) If any of the three bytes in <tt>iHardwareExtra</tt> are non-zero, then this is an early revision of the format and those three bytes are actually song data<ref>In the [http://adplug.sourceforge.net AdPlug distribution], tests/samurai.dro is the early one-byte format, and doofus.dro is the later four-byte variant.</ref>.

==== Song data ====

Directly following the header is ''iLengthBytes'' bytes of OPL data. The first byte in the song data will be the OPL register, followed by the byte to send to that register. The "register" can also be one of these control values:

{|class="wikitable"
!Register value!!Data size!!Purpose
|-
|0x00||1||Delay. The single data byte following should be incremented by one, and is then the delay in milliseconds.
|-
|0x01||2||Delay. Same as above only there are two bytes following, in the form of a UINT16LE integer.
|-
|0x02||0||Switch to "low" OPL chip (#0)
|-
|0x03||0||Switch to "high" OPL chip (#1)
|-
|0x04||2||Escape - the next two bytes are normal register/value pairs even though the register might be 0x00-0x04
|-
|Other||1||Anything else should be treated as an OPL register, with the byte following being the data to send to that register.
|}

The delays all need to be incremented by one, as having a delay of zero milliseconds would be a waste of space. Codes 0x02 and 0x03 switch between two OPL chips in dual OPL2 mode, or between register banks in OPL3 mode. These should only be used if the hardware flag in the header indicates the file is in dual-OPL2 or OPL3 format.

All delays are in milliseconds (which can be treated as 1000Hz if converting between other formats.)

=== Version 2.0 ===

Version 2.0 of the DRO Format was introduced with DOSBox 0.73.

==== Header ====

The version 2.0 header also follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthPairs||Length of the song in register/value pairs (TODO: confirm - 1 == one register + one value, or two bytes)
|-
|UINT32LE||iLengthMS||Length of the song data ("chunk" -?) in milliseconds
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8||iFormat||Data arrangement
|-
|UINT8||iCompression||Compression type, zero means no compression (currently only zero is used)
|-
|UINT8||iShortDelayCode||Command code for short delay (1-256ms)
|-
|UINT8||iLongDelayCode||Command code for short delay (> 256ms)
|-
|UINT8||iCodemapLength||Number of entries in codemap table
|-
|UINT8[iCodemapLength]||iCodemap||Codemap table (see below)
|}

''iHardwareType'' is one of the following values: (which are different in v1.0 and v2.0)
{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||Dual OPL2
|-
|2||OPL3
|}
''iFormat'' is one of the following values:
{|class="wikitable"
!''iFormat''!!Description
|-
|0||Commands and data are interleaved (default/as per v1.0)
|-
|1||Maybe all commands, followed by all data (unused? - TODO: Confirm)
|}

Notes:
* ''iLengthMS'' is at a different offset in v1.0 and v2.0
* The ''iShortDelayCode'' value must have one added to it, as per v1.0 (so a short delay of 2 == a 3ms delay)
* The ''iLongDelayCode'' value must have one added to it, then be multiplied by 256 (or "<< 8"), so a long delay of 2 == a 768ms delay
* Because the high bit in each codeword is used to refer to the second OPL2 chip (or the second set of registers in an OPL3), there are only 128 possible codewords (0-127). Therefore ''iCodemapLength'' must always be 128 or less.
* DOSBox dumps a snapshot of the current register state at the beginning of a capture. (Any other registers are assumed initialised to zero.) This means that even an OPL2 only song will appear to have some data sent to the second OPL chip, because of this initial snapshot. To really know whether the second OPL chip is in use, you can find out if it is actually making any sound, like so:
** Examine bit 5 (0x20) on registers 0xB0 to 0xB8. If this bit is set, a note is playing and the chip is being used.
** Check whether bitmask 0x1F on register 0xBD is greater than 0x10 (i.e. <code>if (reg[0xBD] & 0x1F > 0x10) ...</code>). If so, the chip is in percussive mode and a rhythm instrument is being played, so the chip is being used.

===== Codemap table =====
The codemap table maps index numbers to OPL registers. As there are 256 possible OPL registers but only a subset of these actually used, the mapping table allows up to 128 OPL registers to be used in a song. The other 128 (with the high bit set) are used for the second OPL2 chip in a dual-OPL2 capture.

The table is a list of ''iCodemapLength'' bytes, with the index used later in the file. For example this code table:

01 04 05 08 BD

Means that when the song references register #0 the data should be sent to OPL register 0x01, when the song references register #4 the data should go to OPL register 0xBD. If the song references register #128 (i.e. register 128+0), data should be sent to OPL register 0x01 on the '''second''' chip (in dual OPL2 mode) or the second set of registers (OPL3 mode). Likewise register #132 (128+4) is OPL register 0xBD on the '''second''' chip.

==== Song data ====

Directly following the header is the song data in register index and value pairs.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iRegisterIndex||Register to write to. This is an index into the codemap table.
|-
|UINT8||iValue||Value to write to the OPL register
|}

This structure is repeated ''iLengthPairs'' times. Note that while ''iRegisterIndex'' is normally an index into the codemap table, it can also match ''iShortDelayCode'' or ''iLongDelayCode'' if ''iValue'' is to be treated as a delay length (see above.) If the high bit is set (<code>iRegisterIndex & 0x80</code>) then it is a register on the second OPL chip in a dual-OPL2 song (so the high bit should be removed and the value looked up as normal, but then sent to the second OPL chip instead.)

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[AdPlug]]
| Platform = Windows/Linux/DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [http://www.dosbox.com/ DOSBox]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v2-only since 0.73. Produces .dro files as a result of capturing Adlib data from DOS games and applications
}}
{{FileFormatTool
| Name = [http://www.jestarjokin.net/apps/drotrimmer DRO Trimmer]
| Platform = Any (Python)
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Edits .dro files to remove unwanted notes from the start and end
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro to .imf
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro and .imf to .mid
}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = OpenMPT 1.30 and newer can export a DRO v1 register dump for songs that use OPL instruments.
}}
{{EndFileFormatTools}}

== Similar formats ==
* [[RAW Format (Adlib)|Rdos' RAW format]] serves the same purpose, only these files were originally created through the RAC (Rdos Adlib Capture) TSR running under native DOS.
* The [[IMF Format|id Software Music Format (IMF)]] stores Adlib data in a similar manner in order to provide background music in many Apogee games.

== References ==
<references/>

DRO Format

2021-11-14T01:07:57Z

Saga: /* Tools */

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 22 (Dual OPL2 and OPL3)
| NumTracks = 1
}}
The DOSBox Raw OPL (DRO) format is used for storing captured OPL data from a game running in the cross-platform DOS emulator [http://dosbox.sourceforge.net DOSBox].

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[8]||cSignature||"DBRAWOPL" (not NULL-terminated)
|-
|UINT16LE||iVersionMajor||Version number (high)
|-
|UINT16LE||iVersionMinor||Version number (low)
|}

The rest of the header depends on the version. If iVersionMajor is 5 and iVersionMinor is 6, then the version would be called "5.6" here.

=== Version 0.1 ===

The first version of the DRO Format was used up to and including DOSBox version 0.72. Note that the major and minor field names were swapped beginning with DOSBox 0.73, so this version used to be 1.0, but after DOSBox 0.73 it became 0.1 instead.

==== Header ====

The version 0.1 header follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthMS||Length of the song in milliseconds
|-
|UINT32LE||iLengthBytes||Length of the song data in bytes
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8[3]||iHardwareExtra||Rest of hardware type or song data (see below)
|}

''iHardwareType'' is one of the following values:

{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||OPL3
|-
|2||Dual OPL2
|}

In early files, the field was a UINT8, however in most common (recent) files it is a UINT32LE with only the first byte used. Unfortunately the version number was not changed between these revisions, so the only way to correctly identify the formats is to check the three <tt>iHardwareExtra</tt> bytes. If these are all zero then they can safely be ignored (iHardwareType was a UINT32.) If any of the three bytes in <tt>iHardwareExtra</tt> are non-zero, then this is an early revision of the format and those three bytes are actually song data<ref>In the [http://adplug.sourceforge.net AdPlug distribution], tests/samurai.dro is the early one-byte format, and doofus.dro is the later four-byte variant.</ref>.

==== Song data ====

Directly following the header is ''iLengthBytes'' bytes of OPL data. The first byte in the song data will be the OPL register, followed by the byte to send to that register. The "register" can also be one of these control values:

{|class="wikitable"
!Register value!!Data size!!Purpose
|-
|0x00||1||Delay. The single data byte following should be incremented by one, and is then the delay in milliseconds.
|-
|0x01||2||Delay. Same as above only there are two bytes following, in the form of a UINT16LE integer.
|-
|0x02||0||Switch to "low" OPL chip (#0)
|-
|0x03||0||Switch to "high" OPL chip (#1)
|-
|0x04||2||Escape - the next two bytes are normal register/value pairs even though the register might be 0x00-0x04
|-
|Other||1||Anything else should be treated as an OPL register, with the byte following being the data to send to that register.
|}

The delays all need to be incremented by one, as having a delay of zero milliseconds would be a waste of space. Codes 0x02 and 0x03 switch between two OPL chips in dual OPL2 mode, or between register banks in OPL3 mode. These should only be used if the hardware flag in the header indicates the file is in dual-OPL2 or OPL3 format.

All delays are in milliseconds (which can be treated as 1000Hz if converting between other formats.)

=== Version 2.0 ===

Version 2.0 of the DRO Format was introduced with DOSBox 0.73.

==== Header ====

The version 2.0 header also follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthPairs||Length of the song in register/value pairs (TODO: confirm - 1 == one register + one value, or two bytes)
|-
|UINT32LE||iLengthMS||Length of the song data ("chunk" -?) in milliseconds
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8||iFormat||Data arrangement
|-
|UINT8||iCompression||Compression type, zero means no compression (currently only zero is used)
|-
|UINT8||iShortDelayCode||Command code for short delay (1-256ms)
|-
|UINT8||iLongDelayCode||Command code for short delay (> 256ms)
|-
|UINT8||iCodemapLength||Number of entries in codemap table
|-
|UINT8[iCodemapLength]||iCodemap||Codemap table (see below)
|}

''iHardwareType'' is one of the following values: (which are different in v1.0 and v2.0)
{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||Dual OPL2
|-
|2||OPL3
|}
''iFormat'' is one of the following values:
{|class="wikitable"
!''iFormat''!!Description
|-
|0||Commands and data are interleaved (default/as per v1.0)
|-
|1||Maybe all commands, followed by all data (unused? - TODO: Confirm)
|}

Notes:
* ''iLengthMS'' is at a different offset in v1.0 and v2.0
* The ''iShortDelayCode'' value must have one added to it, as per v1.0 (so a short delay of 2 == a 3ms delay)
* The ''iLongDelayCode'' value must have one added to it, then be multiplied by 256 (or "<< 8"), so a long delay of 2 == a 768ms delay
* Because the high bit in each codeword is used to refer to the second OPL2 chip (or the second set of registers in an OPL3), there are only 128 possible codewords (0-127). Therefore ''iCodemapLength'' must always be 128 or less.
* DOSBox dumps a snapshot of the current register state at the beginning of a capture. (Any other registers are assumed initialised to zero.) This means that even an OPL2 only song will appear to have some data sent to the second OPL chip, because of this initial snapshot. To really know whether the second OPL chip is in use, you can find out if it is actually making any sound, like so:
** Examine bit 5 (0x20) on registers 0xB0 to 0xB8. If this bit is set, a note is playing and the chip is being used.
** Check whether bitmask 0x1F on register 0xBD is greater than 0x10 (i.e. <code>if (reg[0xBD] & 0x1F > 0x10) ...</code>). If so, the chip is in percussive mode and a rhythm instrument is being played, so the chip is being used.

===== Codemap table =====
The codemap table maps index numbers to OPL registers. As there are 256 possible OPL registers but only a subset of these actually used, the mapping table allows up to 128 OPL registers to be used in a song. The other 128 (with the high bit set) are used for the second OPL2 chip in a dual-OPL2 capture.

The table is a list of ''iCodemapLength'' bytes, with the index used later in the file. For example this code table:

01 04 05 08 BD

Means that when the song references register #0 the data should be sent to OPL register 0x01, when the song references register #4 the data should go to OPL register 0xBD. If the song references register #128 (i.e. register 128+0), data should be sent to OPL register 0x01 on the '''second''' chip (in dual OPL2 mode) or the second set of registers (OPL3 mode). Likewise register #132 (128+4) is OPL register 0xBD on the '''second''' chip.

==== Song data ====

Directly following the header is the song data in register index and value pairs.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iRegisterIndex||Register to write to. This is an index into the codemap table.
|-
|UINT8||iValue||Value to write to the OPL register
|}

This structure is repeated ''iLengthPairs'' times. Note that while ''iRegisterIndex'' is normally an index into the codemap table, it can also match ''iShortDelayCode'' or ''iLongDelayCode'' if ''iValue'' is to be treated as a delay length (see above.) If the high bit is set (<code>iRegisterIndex & 0x80</code>) then it is a register on the second OPL chip in a dual-OPL2 song (so the high bit should be removed and the value looked up as normal, but then sent to the second OPL chip instead.)

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[AdPlug]]
| Platform = Windows/Linux/DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [http://www.dosbox.com/ DOSBox]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v2-only since 0.73. Produces .dro files as a result of capturing Adlib data from DOS games and applications
}}
{{FileFormatTool
| Name = [http://www.jestarjokin.net/apps/drotrimmer DRO Trimmer]
| Platform = Any (Python)
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Edits .dro files to remove unwanted notes from the start and end
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro to .imf
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro and .imf to .mid
}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = OpenMPT 1.30 and newer can export a DRO register dump for songs that use OPL instruments.
}}
{{EndFileFormatTools}}

== Similar formats ==
* [[RAW Format (Adlib)|Rdos' RAW format]] serves the same purpose, only these files were originally created through the RAC (Rdos Adlib Capture) TSR running under native DOS.
* The [[IMF Format|id Software Music Format (IMF)]] stores Adlib data in a similar manner in order to provide background music in many Apogee games.

== References ==
<references/>

User:Saga

2021-05-17T17:43:06Z

Saga:

Hello, I'm [https://sagamusix.de/ Saga Musix] and I'm an OpenMPT developer. I have fixed OpenMPT's PSM loader and corrected the [[ProTracker Studio Module|PSM specs]] while doing so. I also reverse-engineered the [[Karl Morton Music Format|music format]] used in [[Psycho Pinball]] and [[Micro Machines 2]] on PC.

Jazz 2 Music Format

2020-10-16T19:24:14Z

Saga: /* Data body */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 255 (practically limited to 64 by source formats)
| NumTracks = 1
| NumPatterns = 256
| NumOrders = 256
| Tags = Title, instrument names, sample names
| Games =
{{Game|Jazz Jackrabbit 2}}
}}

The J2B format is just a container for the custom format of the Galaxy Sound System, RIFF AMFF or RIFF AM.

== Container Header ==

The file header is 24 bytes long:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || format identifier || "MUSE"
|-
| [[UINT32LE]] || format subtype || 0xDEADBEAF (RIFF AM) or 0xDEADBABE (RIFF AMFF); indicates the file content, but is pretty useless (you should not rely on this at all!)
|-
| [[UINT32LE]] || size || Size of the complete file
|-
| [[UINT32LE]] || checksum || Checksum of the data block (''before'' decompression)
|-
| [[UINT32LE]] || compressed size || Length of the data block ''before'' decompression (should be file size - 24 bytes)
|-
| [[UINT32LE]] || uncompressed size || Length of the data block ''after'' decompression
|-
| [[char]][] || music data || This is the actual music file in either RIFF AMFF or RIFF AM format; It's compressed using standard [[Zlib Compression|zlib compression]]. Simply use zlib's "uncompress" macro to read this.
|}

== Data body ==

The uncompressed data body contains a module in either RIFF AMFF or RIFF AM format. Both formats are rather similar, but RIFF AM follows the RIFF conventions more strictly. RIFF AMFF was only used in early versions of Jazz Jackrabbit 2, which explains why RIFF AM is generally the more advanced format of the two. RIFF AMFF is internally very close to the XM format, with a few additions to support some S3M / IT commands.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [https://openmpt.org/ OpenMPT]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{FileFormatTool
| Name = [https://j2c.jazz2online.com/programs.htm mod2j2b]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = MOD, XM, S3M, IT, MTM, 669
| editHidden = No
| editMetadata = No
| notes = Some formats are converted rather poorly (e.g. MTM, 669). There are two different mod2j2b executables for AM and AMFF files.
}}
{{EndFileFormatTools}}

Jazz 2 Music Format

2020-10-16T19:21:49Z

Saga: /* Data body */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 255 (practically limited to 64 by source formats)
| NumTracks = 1
| NumPatterns = 256
| NumOrders = 256
| Tags = Title, instrument names, sample names
| Games =
{{Game|Jazz Jackrabbit 2}}
}}

The J2B format is just a container for the custom format of the Galaxy Sound System, RIFF AMFF or RIFF AM.

== Container Header ==

The file header is 24 bytes long:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || format identifier || "MUSE"
|-
| [[UINT32LE]] || format subtype || 0xDEADBEAF (RIFF AM) or 0xDEADBABE (RIFF AMFF); indicates the file content, but is pretty useless (you should not rely on this at all!)
|-
| [[UINT32LE]] || size || Size of the complete file
|-
| [[UINT32LE]] || checksum || Checksum of the data block (''before'' decompression)
|-
| [[UINT32LE]] || compressed size || Length of the data block ''before'' decompression (should be file size - 24 bytes)
|-
| [[UINT32LE]] || uncompressed size || Length of the data block ''after'' decompression
|-
| [[char]][] || music data || This is the actual music file in either RIFF AMFF or RIFF AM format; It's compressed using standard [[Zlib Compression|zlib compression]]. Simply use zlib's "uncompress" macro to read this.
|}

== Data body ==

The uncompressed data body contains a module in either RIFF AMFF or RIFF AM format. Both formats are rather similar, but RIFF AM follows the RIFF conventions more strictly. RIFF AMFF was only used in early versions of Jazz Jackrabbit 2, which explains why RIFF AM is generally the more advanced format of the two. RIFF AMFF is internally very close to the XM format, with a few additions to support some S3M / IT commands.

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [https://openmpt.org/ OpenMPT]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{FileFormatTool
| Name = [https://j2c.jazz2online.com/programs.htm mod2j2b]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = MOD, XM, S3M, IT, MTM, 669
| editHidden = No
| editMetadata = No
| notes = Some formats are converted rather poorly (e.g. MTM, 669)
}}
{{EndFileFormatTools}}

Jazz 2 Music Format

2020-10-16T19:20:36Z

Saga: Add format template and tools

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 255 (practically limited to 64 by source formats)
| NumTracks = 1
| NumPatterns = 256
| NumOrders = 256
| Tags = Title, instrument names, sample names
| Games =
{{Game|Jazz Jackrabbit 2}}
}}

The J2B format is just a container for the custom format of the Galaxy Sound System, RIFF AMFF or RIFF AM.

== Container Header ==

The file header is 24 bytes long:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || format identifier || "MUSE"
|-
| [[UINT32LE]] || format subtype || 0xDEADBEAF (RIFF AM) or 0xDEADBABE (RIFF AMFF); indicates the file content, but is pretty useless (you should not rely on this at all!)
|-
| [[UINT32LE]] || size || Size of the complete file
|-
| [[UINT32LE]] || checksum || Checksum of the data block (''before'' decompression)
|-
| [[UINT32LE]] || compressed size || Length of the data block ''before'' decompression (should be file size - 24 bytes)
|-
| [[UINT32LE]] || uncompressed size || Length of the data block ''after'' decompression
|-
| [[char]][] || music data || This is the actual music file in either RIFF AMFF or RIFF AM format; It's compressed using standard [[Zlib Compression|zlib compression]]. Simply use zlib's "uncompress" macro to read this.
|}

== Data body ==

The uncompressed data body contains a module in either RIFF AMFF or RIFF AM format. Both formats are rather similar, but RIFF AM follows the RIFF conventions more strictly. RIFF AMFF was only used in early versions of Jazz Jackrabbit 2, which explains why RIFF AM is generally the more advanced format of the two. RIFF AMFF is internally very close to the XM format, with a few additions to support some S3M / IT commands.

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [https://openmpt.org/ OpenMPT]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{FileFormatTool
| Name = [https://j2c.jazz2online.com/programs.htm mod2j2b]
| Platform = Any
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = MOD, XM, S3M, IT, MTM, 669
| editHidden = No
| editMetadata = No
| notes = Some formats are converted rather poorly (e.g. MTM, 669)
}}
{{EndFileFormatTools}}

MID Format

2020-10-15T16:46:14Z

Saga: A note on the signedness of delay values

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Blood}}
{{Game|Boppin'}}
{{Game|Duke Nukem 3D}}
{{Game|Hi Octane}}
{{Game|Hocus Pocus}}
{{Game|Magic Pockets}}
{{Game|Prince of Persia}}
{{Game|Rise of the Triad}}
{{Game|Sango Fighter}}
{{Game|Shadow Warrior}}
{{Game|SimCity 2000}}
{{Game|Wacky Wheels}}
{{Game|Where In the World Is Carmen Sandiego?}}
}}
The Musical Instrument Digital Interface (MIDI) file format is used for storing the notes required to accurately reproduce a song. Commercial instruments are available that "speak" the MIDI protocol, and a MIDI file (.mid) simply stores the data sent over the wire, with a few headers on the front.

== File format ==

A MIDI file starts with an overall ''MThd'' header, followed by one or more ''MTrk'' headers for each "track" (a track is normally created for each instrument, for simplicity when the song is being composed.)

=== MThd Header ===
The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MThd" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of MThd block (usually 6)
|-
|UINT16BE||iType||0, 1 or 2 (for format-0, 1 or 2)
|-
|UINT16BE||iNumTracks||Number of tracks (will be 1 for format-0)
|-
|UINT16BE||iTicksPerQuarterNote||Number of MIDI delay ticks in a quarter-note
|}

If the high bit in <tt>iTicksPerQuarterNote</tt> is set (0x8000) then the file uses SMPTE timing instead, which is rare and not covered here.

=== MTrk block ===

The ''MTrk'' block is repeated once for each track in the song (the '''iNumTracks''' field in the MThd header.)

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MTrk" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of block
|-
|BYTE[iLength]||cData||MIDI data
|}

=== MIDI data ===

The MIDI data consists of a delay value (in MIDI variable-length integer notation), followed by a MIDI event byte (see [[#MIDI events]] below.) The event data follows, and will be different depending on the event. It then starts again with the delay value for the next event.

==== MIDI lengths ====

MIDI lengths are stored as variable length integers, between one and four bytes long. Each byte only uses the lower 7-bits, with the MSB set if there is another length byte following. The bytes are in big endian order. Some examples of these length bytes are:

50 // Hex value 0x50
81 50 // Hex value 0xD0 ((0x81 & 0x7F) << 7) | (0x50 & 0x7F)

Here is some C code to read these values:

<source lang="c">
const char *midi_data = "\x81\x50";
unsigned long val = 0;

for (int i = 0; i < 4; i++) {

// Include the lower 7-bits of this byte into the value
val |= midi_data[i] & 0x7F;

// If the high bit is set, shift the value up
// seven bits to make room for the next value
if (midi_data[i] & 0x80) val <<= 7;
else break; // High bit unset means end of value
}

printf("Value is %lu\n", val);
</source>

Generally variable-length integers are defined to be unsigned numbers. However, some MIDI files in the wild assume that delays are measured as signed 32-bit integers, which is used to shift some MIDI events at the start of the file into the negative range. For this reason, if the first delay value on a channel is 2,147,483,648 or greater, it should be treated as a signed number instead.

Generally speaking, MIDI data that can be sent over the wire uses these values (e.g. delays), whereas data only used to write .mid files on disk (e.g. MTrk lengths in bytes) use normal big-endian fixed-length values.

==== MIDI events ====

This table lists the different MIDI events that can occur in a song. The events are listed as channel zero (e.g. 0x80, which would become 0x85 for channel five.) Removing the high bit (<code>(byte & 0x7F) >> 4</code>) will give the 'event number'.

{|class="wikitable"
!Register value!!Event number!!Data size!!Purpose
|-
|0x80||0||2||Note off
|-
|0x90||1||2||Note on
|-
|0xA0||2||2||Polyphonic key pressure
|-
|0xB0||3||2||Controller
|-
|0xC0||4||1||Instrument change
|-
|0xD0||5||1||Channel pressure
|-
|0xE0||6||2||Pitch bend
|-
|0xF0||7||Any||Sysex
|-
|0xFF||N/A||Any||Meta-event
|}

The data bytes for each event are described in the sections below.

Each event is preceded by a delay (as a MIDILEN variable-length integer, see [[#MIDI lengths]] above) which specifies the number of MIDI ticks until the event should be actioned.

To convert the number of MIDI ticks into a usable time value, the <tt>iTicksPerQuarterNote</tt> field from the header will allow the tick count to be converted into a fractional number of quarter notes, then the song's tempo (in microseconds per quarter note) will allow this fractional number of quarter notes to be converted into microseconds.

The default tempo of 500,000 microseconds per quarter note applies until overridden by a [[#0x51: Set tempo|set-tempo]] event.

===== Running-status =====

Any event values without the high-bit set (i.e. less than 0x80) are so-called "running status" values. If one of these bytes is encountered as a MIDI event, it is actually the first data byte of the event instead. The actual event is the same as the previous one. For example, these two lines are equivalent: (delay bytes omitted for clarity)

90 40 7F 91 44 7F 91 47 7F 81 44 7F (full syntax)
90 40 7F 91 44 7F 47 7F 44 00 (with running status)

This means:
* 90 40 7F: Turn note 0x40 on channel 0 at maximum velocity
* 91 44 7F: Then turn note 0x44 on channel 1 at maximum velocity
* 47 7F: Turn note 0x47 on the same channel (running status means use event 0x91 from before)
* 44 00: Turn note 0x44 off on the same channel (running status uses event 0x91 again, and takes advantage of note-on at zero velocity being the same as note-off)

Meta-events do not affect running status, so any event from 0xF0 to 0xFF can appear in the middle of data without affecting the running status. For example the following line is equivalent to the two lines above:

90 40 7F 91 44 7F FF 01 02 AA BB 47 7F F0 02 AA F7 44 00

===== 0x80: Note off =====
Stops the specified note from sounding on this channel. Does not affect any other notes currently being played on the same channel. A note-on event with a velocity of zero is the same as a note-off event.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-off (0-127)
|-
|UINT8 iVelocity||How hard to release the note (0-127)
|}

===== 0x90: Note on =====
Plays the specified note on the given channel. Multiple notes can be sounding at the same time on the same channel. A velocity of zero is the same as a note-off event (this is often used with running status to minimise the amount of data used.)
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-on (0-127)
|-
|UINT8 iVelocity||How hard to press the note (0-127)
|}

===== 0xA0: Polyphonic key pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|-
|UINT8 iNote||MIDI note number to affect (0-127)
|}

Like [[#0xD0: Channel pressure|channel pressure]], but applies to individual notes on the channel.

===== 0xB0: Controller =====
Set a MIDI controller to the specified value. TODO: List of standard controllers
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iController||Controller index (0-127)
|-
|UINT8 iValue||Value to set (0-127)
|}

===== 0xC0: Instrument change =====
Set the channel to the specified instrument.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iInstrument||Instrument number (0-127)
|}

===== 0xD0: Channel pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|}

Also known as "channel aftertouch", it is designed for instruments that can have their volume/intensity changed after the initial velocity set in the note-on event, such as woodwind instruments where a note can start softly and then become louder. The exact meaning is implementation-defined. For example, this event may set the volume of the notes currently playing on the channel in a similar way as velocity in a note-on event, but other possibilites include applying a filter change or vibrato to the notes.

===== 0xE0: Pitch bend =====
Bend all notes on the channel up or down by the specified amount. The value is between 0 and 16384. The value 8192 is in the middle and means no bend, thus 8192 can be subtracted from this the value to create a signed integer between -8192 and +8191, with zero meaning "no bend." The actual pitch resulting from the bend depends on the range, which is set (usually at the start of the song) by a MIDI controller message.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iLSB||Least significant byte (0-127)
|-
|UINT8 iMSB||Most significant byte (0-127)
|}

The value is calculated by combining the lower seven bits from each of the two bytes into a single 14-bit value: <code>value = (iMSB << 7) | iLSB</code>

===== 0xF0: System exclusive =====
These messages are used to send proprietary commands to various MIDI devices. They are essentially a list of raw bytes to send. The channel is not used, so 0xF0 through 0xFF are different "sysex" messages. Since 0xFF is used as a reset it would have no use in a .mid file on disk, so this event is used for meta-events described below.

The event type (0xF0 to 0xFE) is followed by this structure:

{|class="wikitable"
!Data bytes!!Purpose
|-
|MIDILEN iLength||Length of data
|-
|UINT8 cData[iLength]||Block of data, iLength bytes long
|}

Event 0xFF has a different structure and is covered below. The event types are defined as follows:

{|class="wikitable"
!Event type!!Purpose
|-
|0xF0||Start system exclusive event
|-
|0xF1||MIDI time code
|-
|0xF2||Song position pointer
|-
|0xF3||Song select
|-
|0xF4||(Unused)
|-
|0xF5||(Unused)
|-
|0xF6||Tune request
|-
|0xF7||End system exclusive event (EOX)
|-
|0xF8||Timing clock
|-
|0xF9||(Unused)
|-
|0xFA||Start playback
|-
|0xFB||Continue playback
|-
|0xFC||Stop playback
|-
|0xFD||(Unused)
|-
|0xFE||Active sensing
|-
|0xFF||System reset (used for meta-event in a MIDI file)
|}

==== Meta events ====

Meta events are events specific to MIDI files themselves. They are not transmitted to MIDI devices. A meta event is signalled by the 0xFF system exclusive event. The following table lists the format of the bytes following the 0xFF.

{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iType||Meta-event type
|-
|MIDILEN iLength||Length of event data
|-
|UINT8 cData[iLength]||Event data
|}

The following section lists the meaning of various values of <tt>iType</tt>.

===== 0x01 - 0x0F: Text =====
These events set various types of text. The event data is the text to set.

{|class="wikitable"
!Event type!!Text use
|-
|0x01||Generic text event. Often the first text event in a song is used as its title.
|-
|0x02||Copyright notice
|-
|0x03||Track name. Often the first event (format-0) or the first track (format-1) is the song title.
|-
|0x04||Instrument name
|-
|0x05||Lyric
|-
|0x06||Marker
|-
|0x07||Cue point (e.g. stage instructions)
|}

===== 0x2F: End of track =====
Mandatory event at the end of each MTrk track. The length field is always zero, so there are no bytes of event data.

===== 0x51: Set tempo =====
This event should always have a length of three. The event data is a big-endian integer ('''not''' in MIDI variable-length notation) indicating the number of microseconds in a quarter note. Together with the <tt>iTicksPerQuarterNote</tt> value from the header, this allows MIDI ticks to be converted into microseconds for correct playback speed of the MIDI file.

Unless overridden by this event, the number of microseconds in a quarter note defaults to 500,000.

===== 0x7F: Manufacturer-specific =====
The first data byte of this event is a manufacturer ID. If it is 0x00, then the following [[UINT16BE]] is the actual manufacturer ID. This means either one or three bytes total will be read to obtain the manufacturer ID.

If the manufacturer ID is 0x3F then it is an Ad Lib, Inc. event, and the file format is technically <tt>.mdi</tt> (an Ad Lib MIDI file with embedded OPL instruments), see [[MDI Format]] for details.

===== Additional meta-events =====

Other meta-events (not so important for playing back game music) are listed on various web sites:

* http://www.omega-art.com/midi/mfiles.html#meta

== Tools ==
* [[DRO2MIDI]] - converts .dro files into [[MID Format|.mid files]]

== Similar formats ==
* [[MDI Format|MDI files]] have the same container format, but with different event specification.
* [[CMF Format|CMF files]] store their song data in MIDI format.
* [[MUS Format|MUS files]] are single-track MIDI files made by id Software.
* [[XMI Format|XMI files]] are Extended MIDI files.

== External links ==
* https://web.archive.org/web/20070104033706/http://www.cybermuff.cz/music/MIDIspec.htm - great reference for the MIDI spec

[[Category:Build engine]]

MID Format

2020-10-15T16:42:08Z

Saga: /* 0xA0: Polyphonic key pressure */

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Blood}}
{{Game|Boppin'}}
{{Game|Duke Nukem 3D}}
{{Game|Hi Octane}}
{{Game|Hocus Pocus}}
{{Game|Magic Pockets}}
{{Game|Prince of Persia}}
{{Game|Rise of the Triad}}
{{Game|Sango Fighter}}
{{Game|Shadow Warrior}}
{{Game|SimCity 2000}}
{{Game|Wacky Wheels}}
{{Game|Where In the World Is Carmen Sandiego?}}
}}
The Musical Instrument Digital Interface (MIDI) file format is used for storing the notes required to accurately reproduce a song. Commercial instruments are available that "speak" the MIDI protocol, and a MIDI file (.mid) simply stores the data sent over the wire, with a few headers on the front.

== File format ==

A MIDI file starts with an overall ''MThd'' header, followed by one or more ''MTrk'' headers for each "track" (a track is normally created for each instrument, for simplicity when the song is being composed.)

=== MThd Header ===
The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MThd" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of MThd block (usually 6)
|-
|UINT16BE||iType||0, 1 or 2 (for format-0, 1 or 2)
|-
|UINT16BE||iNumTracks||Number of tracks (will be 1 for format-0)
|-
|UINT16BE||iTicksPerQuarterNote||Number of MIDI delay ticks in a quarter-note
|}

If the high bit in <tt>iTicksPerQuarterNote</tt> is set (0x8000) then the file uses SMPTE timing instead, which is rare and not covered here.

=== MTrk block ===

The ''MTrk'' block is repeated once for each track in the song (the '''iNumTracks''' field in the MThd header.)

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MTrk" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of block
|-
|BYTE[iLength]||cData||MIDI data
|}

=== MIDI data ===

The MIDI data consists of a delay value (in MIDI variable-length integer notation), followed by a MIDI event byte (see [[#MIDI events]] below.) The event data follows, and will be different depending on the event. It then starts again with the delay value for the next event.

==== MIDI lengths ====

MIDI lengths are stored as variable length integers, between one and four bytes long. Each byte only uses the lower 7-bits, with the MSB set if there is another length byte following. The bytes are in big endian order. Some examples of these length bytes are:

50 // Hex value 0x50
81 50 // Hex value 0xD0 ((0x81 & 0x7F) << 7) | (0x50 & 0x7F)

Here is some C code to read these values:

<source lang="c">
const char *midi_data = "\x81\x50";
unsigned long val = 0;

for (int i = 0; i < 4; i++) {

// Include the lower 7-bits of this byte into the value
val |= midi_data[i] & 0x7F;

// If the high bit is set, shift the value up
// seven bits to make room for the next value
if (midi_data[i] & 0x80) val <<= 7;
else break; // High bit unset means end of value
}

printf("Value is %lu\n", val);
</source>

Generally speaking, MIDI data that can be sent over the wire uses these values (e.g. delays), whereas data only used to write .mid files on disk (e.g. MTrk lengths in bytes) use normal big-endian fixed-length values.

==== MIDI events ====

This table lists the different MIDI events that can occur in a song. The events are listed as channel zero (e.g. 0x80, which would become 0x85 for channel five.) Removing the high bit (<code>(byte & 0x7F) >> 4</code>) will give the 'event number'.

{|class="wikitable"
!Register value!!Event number!!Data size!!Purpose
|-
|0x80||0||2||Note off
|-
|0x90||1||2||Note on
|-
|0xA0||2||2||Polyphonic key pressure
|-
|0xB0||3||2||Controller
|-
|0xC0||4||1||Instrument change
|-
|0xD0||5||1||Channel pressure
|-
|0xE0||6||2||Pitch bend
|-
|0xF0||7||Any||Sysex
|-
|0xFF||N/A||Any||Meta-event
|}

The data bytes for each event are described in the sections below.

Each event is preceded by a delay (as a MIDILEN variable-length integer, see [[#MIDI lengths]] above) which specifies the number of MIDI ticks until the event should be actioned.

To convert the number of MIDI ticks into a usable time value, the <tt>iTicksPerQuarterNote</tt> field from the header will allow the tick count to be converted into a fractional number of quarter notes, then the song's tempo (in microseconds per quarter note) will allow this fractional number of quarter notes to be converted into microseconds.

The default tempo of 500,000 microseconds per quarter note applies until overridden by a [[#0x51: Set tempo|set-tempo]] event.

===== Running-status =====

Any event values without the high-bit set (i.e. less than 0x80) are so-called "running status" values. If one of these bytes is encountered as a MIDI event, it is actually the first data byte of the event instead. The actual event is the same as the previous one. For example, these two lines are equivalent: (delay bytes omitted for clarity)

90 40 7F 91 44 7F 91 47 7F 81 44 7F (full syntax)
90 40 7F 91 44 7F 47 7F 44 00 (with running status)

This means:
* 90 40 7F: Turn note 0x40 on channel 0 at maximum velocity
* 91 44 7F: Then turn note 0x44 on channel 1 at maximum velocity
* 47 7F: Turn note 0x47 on the same channel (running status means use event 0x91 from before)
* 44 00: Turn note 0x44 off on the same channel (running status uses event 0x91 again, and takes advantage of note-on at zero velocity being the same as note-off)

Meta-events do not affect running status, so any event from 0xF0 to 0xFF can appear in the middle of data without affecting the running status. For example the following line is equivalent to the two lines above:

90 40 7F 91 44 7F FF 01 02 AA BB 47 7F F0 02 AA F7 44 00

===== 0x80: Note off =====
Stops the specified note from sounding on this channel. Does not affect any other notes currently being played on the same channel. A note-on event with a velocity of zero is the same as a note-off event.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-off (0-127)
|-
|UINT8 iVelocity||How hard to release the note (0-127)
|}

===== 0x90: Note on =====
Plays the specified note on the given channel. Multiple notes can be sounding at the same time on the same channel. A velocity of zero is the same as a note-off event (this is often used with running status to minimise the amount of data used.)
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-on (0-127)
|-
|UINT8 iVelocity||How hard to press the note (0-127)
|}

===== 0xA0: Polyphonic key pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|-
|UINT8 iNote||MIDI note number to affect (0-127)
|}

Like [[#0xD0: Channel pressure|channel pressure]], but applies to individual notes on the channel.

===== 0xB0: Controller =====
Set a MIDI controller to the specified value. TODO: List of standard controllers
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iController||Controller index (0-127)
|-
|UINT8 iValue||Value to set (0-127)
|}

===== 0xC0: Instrument change =====
Set the channel to the specified instrument.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iInstrument||Instrument number (0-127)
|}

===== 0xD0: Channel pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|}

Also known as "channel aftertouch", it is designed for instruments that can have their volume/intensity changed after the initial velocity set in the note-on event, such as woodwind instruments where a note can start softly and then become louder. The exact meaning is implementation-defined. For example, this event may set the volume of the notes currently playing on the channel in a similar way as velocity in a note-on event, but other possibilites include applying a filter change or vibrato to the notes.

===== 0xE0: Pitch bend =====
Bend all notes on the channel up or down by the specified amount. The value is between 0 and 16384. The value 8192 is in the middle and means no bend, thus 8192 can be subtracted from this the value to create a signed integer between -8192 and +8191, with zero meaning "no bend." The actual pitch resulting from the bend depends on the range, which is set (usually at the start of the song) by a MIDI controller message.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iLSB||Least significant byte (0-127)
|-
|UINT8 iMSB||Most significant byte (0-127)
|}

The value is calculated by combining the lower seven bits from each of the two bytes into a single 14-bit value: <code>value = (iMSB << 7) | iLSB</code>

===== 0xF0: System exclusive =====
These messages are used to send proprietary commands to various MIDI devices. They are essentially a list of raw bytes to send. The channel is not used, so 0xF0 through 0xFF are different "sysex" messages. Since 0xFF is used as a reset it would have no use in a .mid file on disk, so this event is used for meta-events described below.

The event type (0xF0 to 0xFE) is followed by this structure:

{|class="wikitable"
!Data bytes!!Purpose
|-
|MIDILEN iLength||Length of data
|-
|UINT8 cData[iLength]||Block of data, iLength bytes long
|}

Event 0xFF has a different structure and is covered below. The event types are defined as follows:

{|class="wikitable"
!Event type!!Purpose
|-
|0xF0||Start system exclusive event
|-
|0xF1||MIDI time code
|-
|0xF2||Song position pointer
|-
|0xF3||Song select
|-
|0xF4||(Unused)
|-
|0xF5||(Unused)
|-
|0xF6||Tune request
|-
|0xF7||End system exclusive event (EOX)
|-
|0xF8||Timing clock
|-
|0xF9||(Unused)
|-
|0xFA||Start playback
|-
|0xFB||Continue playback
|-
|0xFC||Stop playback
|-
|0xFD||(Unused)
|-
|0xFE||Active sensing
|-
|0xFF||System reset (used for meta-event in a MIDI file)
|}

==== Meta events ====

Meta events are events specific to MIDI files themselves. They are not transmitted to MIDI devices. A meta event is signalled by the 0xFF system exclusive event. The following table lists the format of the bytes following the 0xFF.

{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iType||Meta-event type
|-
|MIDILEN iLength||Length of event data
|-
|UINT8 cData[iLength]||Event data
|}

The following section lists the meaning of various values of <tt>iType</tt>.

===== 0x01 - 0x0F: Text =====
These events set various types of text. The event data is the text to set.

{|class="wikitable"
!Event type!!Text use
|-
|0x01||Generic text event. Often the first text event in a song is used as its title.
|-
|0x02||Copyright notice
|-
|0x03||Track name. Often the first event (format-0) or the first track (format-1) is the song title.
|-
|0x04||Instrument name
|-
|0x05||Lyric
|-
|0x06||Marker
|-
|0x07||Cue point (e.g. stage instructions)
|}

===== 0x2F: End of track =====
Mandatory event at the end of each MTrk track. The length field is always zero, so there are no bytes of event data.

===== 0x51: Set tempo =====
This event should always have a length of three. The event data is a big-endian integer ('''not''' in MIDI variable-length notation) indicating the number of microseconds in a quarter note. Together with the <tt>iTicksPerQuarterNote</tt> value from the header, this allows MIDI ticks to be converted into microseconds for correct playback speed of the MIDI file.

Unless overridden by this event, the number of microseconds in a quarter note defaults to 500,000.

===== 0x7F: Manufacturer-specific =====
The first data byte of this event is a manufacturer ID. If it is 0x00, then the following [[UINT16BE]] is the actual manufacturer ID. This means either one or three bytes total will be read to obtain the manufacturer ID.

If the manufacturer ID is 0x3F then it is an Ad Lib, Inc. event, and the file format is technically <tt>.mdi</tt> (an Ad Lib MIDI file with embedded OPL instruments), see [[MDI Format]] for details.

===== Additional meta-events =====

Other meta-events (not so important for playing back game music) are listed on various web sites:

* http://www.omega-art.com/midi/mfiles.html#meta

== Tools ==
* [[DRO2MIDI]] - converts .dro files into [[MID Format|.mid files]]

== Similar formats ==
* [[MDI Format|MDI files]] have the same container format, but with different event specification.
* [[CMF Format|CMF files]] store their song data in MIDI format.
* [[MUS Format|MUS files]] are single-track MIDI files made by id Software.
* [[XMI Format|XMI files]] are Extended MIDI files.

== External links ==
* https://web.archive.org/web/20070104033706/http://www.cybermuff.cz/music/MIDIspec.htm - great reference for the MIDI spec

[[Category:Build engine]]

MID Format

2020-10-15T16:41:06Z

Saga: Clarify that channel pressure behaviour is not standardized

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Blood}}
{{Game|Boppin'}}
{{Game|Duke Nukem 3D}}
{{Game|Hi Octane}}
{{Game|Hocus Pocus}}
{{Game|Magic Pockets}}
{{Game|Prince of Persia}}
{{Game|Rise of the Triad}}
{{Game|Sango Fighter}}
{{Game|Shadow Warrior}}
{{Game|SimCity 2000}}
{{Game|Wacky Wheels}}
{{Game|Where In the World Is Carmen Sandiego?}}
}}
The Musical Instrument Digital Interface (MIDI) file format is used for storing the notes required to accurately reproduce a song. Commercial instruments are available that "speak" the MIDI protocol, and a MIDI file (.mid) simply stores the data sent over the wire, with a few headers on the front.

== File format ==

A MIDI file starts with an overall ''MThd'' header, followed by one or more ''MTrk'' headers for each "track" (a track is normally created for each instrument, for simplicity when the song is being composed.)

=== MThd Header ===
The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MThd" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of MThd block (usually 6)
|-
|UINT16BE||iType||0, 1 or 2 (for format-0, 1 or 2)
|-
|UINT16BE||iNumTracks||Number of tracks (will be 1 for format-0)
|-
|UINT16BE||iTicksPerQuarterNote||Number of MIDI delay ticks in a quarter-note
|}

If the high bit in <tt>iTicksPerQuarterNote</tt> is set (0x8000) then the file uses SMPTE timing instead, which is rare and not covered here.

=== MTrk block ===

The ''MTrk'' block is repeated once for each track in the song (the '''iNumTracks''' field in the MThd header.)

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"MTrk" (not NULL-terminated)
|-
|UINT32BE||iLength||Length of block
|-
|BYTE[iLength]||cData||MIDI data
|}

=== MIDI data ===

The MIDI data consists of a delay value (in MIDI variable-length integer notation), followed by a MIDI event byte (see [[#MIDI events]] below.) The event data follows, and will be different depending on the event. It then starts again with the delay value for the next event.

==== MIDI lengths ====

MIDI lengths are stored as variable length integers, between one and four bytes long. Each byte only uses the lower 7-bits, with the MSB set if there is another length byte following. The bytes are in big endian order. Some examples of these length bytes are:

50 // Hex value 0x50
81 50 // Hex value 0xD0 ((0x81 & 0x7F) << 7) | (0x50 & 0x7F)

Here is some C code to read these values:

<source lang="c">
const char *midi_data = "\x81\x50";
unsigned long val = 0;

for (int i = 0; i < 4; i++) {

// Include the lower 7-bits of this byte into the value
val |= midi_data[i] & 0x7F;

// If the high bit is set, shift the value up
// seven bits to make room for the next value
if (midi_data[i] & 0x80) val <<= 7;
else break; // High bit unset means end of value
}

printf("Value is %lu\n", val);
</source>

Generally speaking, MIDI data that can be sent over the wire uses these values (e.g. delays), whereas data only used to write .mid files on disk (e.g. MTrk lengths in bytes) use normal big-endian fixed-length values.

==== MIDI events ====

This table lists the different MIDI events that can occur in a song. The events are listed as channel zero (e.g. 0x80, which would become 0x85 for channel five.) Removing the high bit (<code>(byte & 0x7F) >> 4</code>) will give the 'event number'.

{|class="wikitable"
!Register value!!Event number!!Data size!!Purpose
|-
|0x80||0||2||Note off
|-
|0x90||1||2||Note on
|-
|0xA0||2||2||Polyphonic key pressure
|-
|0xB0||3||2||Controller
|-
|0xC0||4||1||Instrument change
|-
|0xD0||5||1||Channel pressure
|-
|0xE0||6||2||Pitch bend
|-
|0xF0||7||Any||Sysex
|-
|0xFF||N/A||Any||Meta-event
|}

The data bytes for each event are described in the sections below.

Each event is preceded by a delay (as a MIDILEN variable-length integer, see [[#MIDI lengths]] above) which specifies the number of MIDI ticks until the event should be actioned.

To convert the number of MIDI ticks into a usable time value, the <tt>iTicksPerQuarterNote</tt> field from the header will allow the tick count to be converted into a fractional number of quarter notes, then the song's tempo (in microseconds per quarter note) will allow this fractional number of quarter notes to be converted into microseconds.

The default tempo of 500,000 microseconds per quarter note applies until overridden by a [[#0x51: Set tempo|set-tempo]] event.

===== Running-status =====

Any event values without the high-bit set (i.e. less than 0x80) are so-called "running status" values. If one of these bytes is encountered as a MIDI event, it is actually the first data byte of the event instead. The actual event is the same as the previous one. For example, these two lines are equivalent: (delay bytes omitted for clarity)

90 40 7F 91 44 7F 91 47 7F 81 44 7F (full syntax)
90 40 7F 91 44 7F 47 7F 44 00 (with running status)

This means:
* 90 40 7F: Turn note 0x40 on channel 0 at maximum velocity
* 91 44 7F: Then turn note 0x44 on channel 1 at maximum velocity
* 47 7F: Turn note 0x47 on the same channel (running status means use event 0x91 from before)
* 44 00: Turn note 0x44 off on the same channel (running status uses event 0x91 again, and takes advantage of note-on at zero velocity being the same as note-off)

Meta-events do not affect running status, so any event from 0xF0 to 0xFF can appear in the middle of data without affecting the running status. For example the following line is equivalent to the two lines above:

90 40 7F 91 44 7F FF 01 02 AA BB 47 7F F0 02 AA F7 44 00

===== 0x80: Note off =====
Stops the specified note from sounding on this channel. Does not affect any other notes currently being played on the same channel. A note-on event with a velocity of zero is the same as a note-off event.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-off (0-127)
|-
|UINT8 iVelocity||How hard to release the note (0-127)
|}

===== 0x90: Note on =====
Plays the specified note on the given channel. Multiple notes can be sounding at the same time on the same channel. A velocity of zero is the same as a note-off event (this is often used with running status to minimise the amount of data used.)
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iNote||MIDI note number to key-on (0-127)
|-
|UINT8 iVelocity||How hard to press the note (0-127)
|}

===== 0xA0: Polyphonic key pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|-
|UINT8 iNote||MIDI note number to affect (0-127)
|}

===== 0xB0: Controller =====
Set a MIDI controller to the specified value. TODO: List of standard controllers
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iController||Controller index (0-127)
|-
|UINT8 iValue||Value to set (0-127)
|}

===== 0xC0: Instrument change =====
Set the channel to the specified instrument.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iInstrument||Instrument number (0-127)
|}

===== 0xD0: Channel pressure =====
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iPressure||Pressure value (0-127)
|}

Also known as "channel aftertouch", it is designed for instruments that can have their volume/intensity changed after the initial velocity set in the note-on event, such as woodwind instruments where a note can start softly and then become louder. The exact meaning is implementation-defined. For example, this event may set the volume of the notes currently playing on the channel in a similar way as velocity in a note-on event, but other possibilites include applying a filter change or vibrato to the notes.

===== 0xE0: Pitch bend =====
Bend all notes on the channel up or down by the specified amount. The value is between 0 and 16384. The value 8192 is in the middle and means no bend, thus 8192 can be subtracted from this the value to create a signed integer between -8192 and +8191, with zero meaning "no bend." The actual pitch resulting from the bend depends on the range, which is set (usually at the start of the song) by a MIDI controller message.
{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iLSB||Least significant byte (0-127)
|-
|UINT8 iMSB||Most significant byte (0-127)
|}

The value is calculated by combining the lower seven bits from each of the two bytes into a single 14-bit value: <code>value = (iMSB << 7) | iLSB</code>

===== 0xF0: System exclusive =====
These messages are used to send proprietary commands to various MIDI devices. They are essentially a list of raw bytes to send. The channel is not used, so 0xF0 through 0xFF are different "sysex" messages. Since 0xFF is used as a reset it would have no use in a .mid file on disk, so this event is used for meta-events described below.

The event type (0xF0 to 0xFE) is followed by this structure:

{|class="wikitable"
!Data bytes!!Purpose
|-
|MIDILEN iLength||Length of data
|-
|UINT8 cData[iLength]||Block of data, iLength bytes long
|}

Event 0xFF has a different structure and is covered below. The event types are defined as follows:

{|class="wikitable"
!Event type!!Purpose
|-
|0xF0||Start system exclusive event
|-
|0xF1||MIDI time code
|-
|0xF2||Song position pointer
|-
|0xF3||Song select
|-
|0xF4||(Unused)
|-
|0xF5||(Unused)
|-
|0xF6||Tune request
|-
|0xF7||End system exclusive event (EOX)
|-
|0xF8||Timing clock
|-
|0xF9||(Unused)
|-
|0xFA||Start playback
|-
|0xFB||Continue playback
|-
|0xFC||Stop playback
|-
|0xFD||(Unused)
|-
|0xFE||Active sensing
|-
|0xFF||System reset (used for meta-event in a MIDI file)
|}

==== Meta events ====

Meta events are events specific to MIDI files themselves. They are not transmitted to MIDI devices. A meta event is signalled by the 0xFF system exclusive event. The following table lists the format of the bytes following the 0xFF.

{|class="wikitable"
!Data bytes!!Purpose
|-
|UINT8 iType||Meta-event type
|-
|MIDILEN iLength||Length of event data
|-
|UINT8 cData[iLength]||Event data
|}

The following section lists the meaning of various values of <tt>iType</tt>.

===== 0x01 - 0x0F: Text =====
These events set various types of text. The event data is the text to set.

{|class="wikitable"
!Event type!!Text use
|-
|0x01||Generic text event. Often the first text event in a song is used as its title.
|-
|0x02||Copyright notice
|-
|0x03||Track name. Often the first event (format-0) or the first track (format-1) is the song title.
|-
|0x04||Instrument name
|-
|0x05||Lyric
|-
|0x06||Marker
|-
|0x07||Cue point (e.g. stage instructions)
|}

===== 0x2F: End of track =====
Mandatory event at the end of each MTrk track. The length field is always zero, so there are no bytes of event data.

===== 0x51: Set tempo =====
This event should always have a length of three. The event data is a big-endian integer ('''not''' in MIDI variable-length notation) indicating the number of microseconds in a quarter note. Together with the <tt>iTicksPerQuarterNote</tt> value from the header, this allows MIDI ticks to be converted into microseconds for correct playback speed of the MIDI file.

Unless overridden by this event, the number of microseconds in a quarter note defaults to 500,000.

===== 0x7F: Manufacturer-specific =====
The first data byte of this event is a manufacturer ID. If it is 0x00, then the following [[UINT16BE]] is the actual manufacturer ID. This means either one or three bytes total will be read to obtain the manufacturer ID.

If the manufacturer ID is 0x3F then it is an Ad Lib, Inc. event, and the file format is technically <tt>.mdi</tt> (an Ad Lib MIDI file with embedded OPL instruments), see [[MDI Format]] for details.

===== Additional meta-events =====

Other meta-events (not so important for playing back game music) are listed on various web sites:

* http://www.omega-art.com/midi/mfiles.html#meta

== Tools ==
* [[DRO2MIDI]] - converts .dro files into [[MID Format|.mid files]]

== Similar formats ==
* [[MDI Format|MDI files]] have the same container format, but with different event specification.
* [[CMF Format|CMF files]] store their song data in MIDI format.
* [[MUS Format|MUS files]] are single-track MIDI files made by id Software.
* [[XMI Format|XMI files]] are Extended MIDI files.

== External links ==
* https://web.archive.org/web/20070104033706/http://www.cybermuff.cz/music/MIDIspec.htm - great reference for the MIDI spec

[[Category:Build engine]]

Karl Morton Music Format

2020-10-14T21:30:46Z

Saga: Add mod2mus

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 32 (only 4 usable in-game)
| NumTracks = no limit
| NumPatterns = n/a
| NumOrders = n/a
| Tags = Title, instrument names
| Games =
{{Game|Psycho Pinball}}
{{Game|Micro Machines 2}}
}}

The [[Karl Morton Music Format]] is the music format used by Karl Morton's sound engine used in the games [[Psycho Pinball]], [[Micro Machines 2]] and [[Back To Baghdad]], although the latter only uses its sound effect file format, not the music format. This is not the official name of the format, but as no official tooling or documentation seems to be available for this format, a simple name was chosen based on the sound engine author's name.

In general, this format follows the semantics of the ProTracker MOD format. Knowledge of the MOD format and its features is assumed.

A somewhat unique feature of this format is that subsongs can re-use samples with different metadata. For example, one song in a file might use a specific sample with a default volume of 64, while another song might reference the same sample data but with a default volume of 48. This allows for greater flexibility when reusing those samples between songs.

== File format ==

The format follows an IFF-like structure, but with no explicit file header (the file directly starts with the first chunk).

=== Chunk Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || ID || chunk ID ("SONG" or "SMPL")
|-
| [[UINT32LE]] || length || chunk length, including this header (so must be at least 8)
|}

The first chunk in the file must be a SONG chunk, apart from this the chunk order doesn't matter.

Typically, SONG and SMPL chunks are interleaved, each SONG being followed by the SMPLs it adds to the sample pool shared between SONGs.
But this order should not be relied on.

=== SONG chunk ===

Each subsong is represented by its own SONG chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || song name || null-terminated song name
|-
| SAMPLE_REFERENCE[31] || sample map || maps song samples to those samples in the global sample pool
|-
| [[char]][2] || unknown || always 0 (maybe just padding)
|-
| [[UINT32LE]] || number of channels || between 1 and 4 - file will be rejected if this is > 32. If it's more than 4 but less than 33 the extra channels will simply not be played.
|-
| [[UINT32LE]] || restart position || byte offset into music data
|-
| [[UINT32LE]] || size of music data || should be chunk size - 1108
|-
| [[char]][] || music data || format is explained below
|}

<tt>SAMPLE_REFERENCE</tt> maps samples from the SMPL chunk pool to instrument numbers in the pattern editor (the first <tt>SAMPLE_REFERENCE</tt> is instrument 1, and so on). It is defined as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || must reference one of the SMPL chunks
|-
| [[UINT8]] || MOD finetune || 0...15
|-
| [[UINT8]] || default volume || 0...64
|}

Music data is basically one gigantic pattern and stored in row-major order (like most module formats).
The pattern is played in a strictly linear order, there are no jump commands or pattern loops.
There is per-channel state that stores the last used note, instrument, command and parameter as well as a repeat counter.

To decode one pattern cell:

* If repeat counter > 0: Decrement repeat counter by 1 and reuse note, instrument, command and parameter from previous row. Continue with next channel.
* Read [[UINT8]], let's name it NOTE.
* If (NOTE AND 0x80): Reuse note, instrument, command and parameter from previous row and set repeat counter to (NOTE AND 0x7F). Continue with next channel.
* If NOTE is between 1 and 36 (inclusively), it's a regular note (C-1 to B-3 in ProTracker), otherwise no note is present
* Read [[UINT8]], let's name it INSTRUMENT.
* Set instrument number in this cell to INSTRUMENT AND 0x1F
* If (INSTRUMENT AND 0x80): Repeat previous command and parameter for this channel
* Otherwise, read the two [[UINT8]]s, the command and parameter bytes.
* Continue with next channel.

Command bytes and their translation to ProTracker MOD commands:
* <tt>00</tt>: <tt>Cxx</tt>
* <tt>01</tt>: <tt>EAx</tt>
* <tt>02</tt>: <tt>EBx</tt>
* <tt>03</tt>: <tt>E1x</tt>
* <tt>04</tt>: <tt>E2x</tt>
* <tt>05</tt>: <tt>E5x</tt>
* <tt>06</tt>: <tt>9xx</tt>
* <tt>07</tt>: <tt>3xx</tt>
* <tt>08</tt>: <tt>5xx</tt>
* <tt>09</tt>: <tt>4xx</tt>
* <tt>0A</tt>: <tt>6xx</tt>
* <tt>0B</tt>: <tt>0xx</tt>
* <tt>0C</tt>: <tt>1xx</tt>
* <tt>0D</tt>: <tt>2xx</tt>
* <tt>0E</tt>: <tt>Axx</tt>
* <tt>0F</tt>: <tt>E9x</tt>
* <tt>10</tt>: Instant portamento (like 3FF but is always fully executed on first tick)
* <tt>11</tt>: <tt>ECx</tt>
* <tt>12</tt>: <tt>Fxx</tt>
* <tt>13</tt>: <tt>7xx</tt>
* <tt>14</tt>: <tt>000</tt> (empty command)

Missing MOD effects are: 8, B, D, E3, E4, E5, E6, E7, E8, ED, EE, EF.

Most commands that translate to extended Exy commands can take values > 0x0F as parameters (finetune command ignores high nibble).

The player will jump to the restart position once the repeat counter of each channel has reached 0 and no bytes are left to be read.

If no tempo is specified on the first row of the pattern, the MOD defaults of tempo 125 and 6 ticks per row are assumed.

=== SMPL chunk ===

Every sample is described by its own SMPL chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || null-terminated, referenced by SONG chunks
|-
| [[UINT32LE]] || loop start || in bytes
|-
| [[UINT32LE]] || size of sample data || should be chunk size - 48
|-
| [[char]][] || sample data || in 8-bit signed mono PCM format
|}

Note that a SMPL can be shared between songs and use different finetune and volume values between songs.

== A note on the string format ==

The last character of sample names must be a null-terminator (the engine uses a string comparison not limited to 32 characters when matching samples). 
While it is not required by the engine, the following restrictions are proposed for newly created files to keep the life of developers easy that have to support dozens of files and may thus want to employ heuristics whether files are of a specific type:
It is suggested that all strings (i.e. instances of [[char]][32]) do not use byte values 1 to 31 (so only printable ASCII/ANSI), and after the first null terminator, the rest of the string has to be padded with nulls as well.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [https://openmpt.org/ OpenMPT]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = At the time of writing, OpenMPT 1.30 (which adds support for this format) is not released yet.
}}
{{FileFormatTool
| Name = [https://github.com/sagamusix/mod2mus mod2mus]
| Platform = Any
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = MOD
| editHidden = No
| editMetadata = No
| notes = Converts 1-4 channel ProTracker MOD files to MUS
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse-engineered by [[User:Saga|Saga]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

Karl Morton Music Format

2020-10-14T16:16:58Z

Saga: Link data types

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 32 (only 4 usable in-game)
| NumTracks = no limit
| NumPatterns = n/a
| NumOrders = n/a
| Tags = Title, instrument names
| Games =
{{Game|Psycho Pinball}}
{{Game|Micro Machines 2}}
}}

The [[Karl Morton Music Format]] is the music format used by Karl Morton's sound engine used in the games [[Psycho Pinball]], [[Micro Machines 2]] and [[Back To Baghdad]], although the latter only uses its sound effect file format, not the music format. This is not the official name of the format, but as no official tooling or documentation seems to be available for this format, a simple name was chosen based on the sound engine author's name.

In general, this format follows the semantics of the ProTracker MOD format. Knowledge of the MOD format and its features is assumed.

A somewhat unique feature of this format is that subsongs can re-use samples with different metadata. For example, one song in a file might use a specific sample with a default volume of 64, while another song might reference the same sample data but with a default volume of 48. This allows for greater flexibility when reusing those samples between songs.

== File format ==

The format follows an IFF-like structure, but with no explicit file header (the file directly starts with the first chunk).

=== Chunk Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][4] || ID || chunk ID ("SONG" or "SMPL")
|-
| [[UINT32LE]] || length || chunk length, including this header (so must be at least 8)
|}

The first chunk in the file must be a SONG chunk, apart from this the chunk order doesn't matter.

Typically, SONG and SMPL chunks are interleaved, each SONG being followed by the SMPLs it adds to the sample pool shared between SONGs.
But this order should not be relied on.

=== SONG chunk ===

Each subsong is represented by its own SONG chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || song name || null-terminated song name
|-
| SAMPLE_REFERENCE[31] || sample map || maps song samples to those samples in the global sample pool
|-
| [[char]][2] || unknown || always 0 (maybe just padding)
|-
| [[UINT32LE]] || number of channels || between 1 and 4 - file will be rejected if this is > 32. If it's more than 4 but less than 33 the extra channels will simply not be played.
|-
| [[UINT32LE]] || restart position || byte offset into music data
|-
| [[UINT32LE]] || size of music data || should be chunk size - 1108
|-
| [[char]][] || music data || format is explained below
|}

<tt>SAMPLE_REFERENCE</tt> maps samples from the SMPL chunk pool to instrument numbers in the pattern editor (the first <tt>SAMPLE_REFERENCE</tt> is instrument 1, and so on). It is defined as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || must reference one of the SMPL chunks
|-
| [[UINT8]] || MOD finetune || 0...15
|-
| [[UINT8]] || default volume || 0...64
|}

Music data is basically one gigantic pattern and stored in row-major order (like most module formats).
The pattern is played in a strictly linear order, there are no jump commands or pattern loops.
There is per-channel state that stores the last used note, instrument, command and parameter as well as a repeat counter.

To decode one pattern cell:

* If repeat counter > 0: Decrement repeat counter by 1 and reuse note, instrument, command and parameter from previous row. Continue with next channel.
* Read [[UINT8]], let's name it NOTE.
* If (NOTE AND 0x80): Reuse note, instrument, command and parameter from previous row and set repeat counter to (NOTE AND 0x7F). Continue with next channel.
* If NOTE is between 1 and 36 (inclusively), it's a regular note (C-1 to B-3 in ProTracker), otherwise no note is present
* Read [[UINT8]], let's name it INSTRUMENT.
* Set instrument number in this cell to INSTRUMENT AND 0x1F
* If (INSTRUMENT AND 0x80): Repeat previous command and parameter for this channel
* Otherwise, read the two [[UINT8]]s, the command and parameter bytes.
* Continue with next channel.

Command bytes and their translation to ProTracker MOD commands:
* <tt>00</tt>: <tt>Cxx</tt>
* <tt>01</tt>: <tt>EAx</tt>
* <tt>02</tt>: <tt>EBx</tt>
* <tt>03</tt>: <tt>E1x</tt>
* <tt>04</tt>: <tt>E2x</tt>
* <tt>05</tt>: <tt>E5x</tt>
* <tt>06</tt>: <tt>9xx</tt>
* <tt>07</tt>: <tt>3xx</tt>
* <tt>08</tt>: <tt>5xx</tt>
* <tt>09</tt>: <tt>4xx</tt>
* <tt>0A</tt>: <tt>6xx</tt>
* <tt>0B</tt>: <tt>0xx</tt>
* <tt>0C</tt>: <tt>1xx</tt>
* <tt>0D</tt>: <tt>2xx</tt>
* <tt>0E</tt>: <tt>Axx</tt>
* <tt>0F</tt>: <tt>E9x</tt>
* <tt>10</tt>: Instant portamento (like 3FF but is always fully executed on first tick)
* <tt>11</tt>: <tt>ECx</tt>
* <tt>12</tt>: <tt>Fxx</tt>
* <tt>13</tt>: <tt>7xx</tt>
* <tt>14</tt>: <tt>000</tt> (empty command)

Missing MOD effects are: 8, B, D, E3, E4, E5, E6, E7, E8, ED, EE, EF.

Most commands that translate to extended Exy commands can take values > 0x0F as parameters (finetune command ignores high nibble).

The player will jump to the restart position once the repeat counter of each channel has reached 0 and no bytes are left to be read.

If no tempo is specified on the first row of the pattern, the MOD defaults of tempo 125 and 6 ticks per row are assumed.

=== SMPL chunk ===

Every sample is described by its own SMPL chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][32] || sample name || null-terminated, referenced by SONG chunks
|-
| [[UINT32LE]] || loop start || in bytes
|-
| [[UINT32LE]] || size of sample data || should be chunk size - 48
|-
| [[char]][] || sample data || in 8-bit signed mono PCM format
|}

Note that a SMPL can be shared between songs and use different finetune and volume values between songs.

== A note on the string format ==

The last character of sample names must be a null-terminator (the engine uses a string comparison not limited to 32 characters when matching samples). 
While it is not required by the engine, the following restrictions are proposed for newly created files to keep the life of developers easy that have to support dozens of files and may thus want to employ heuristics whether files are of a specific type:
It is suggested that all strings (i.e. instances of [[char]][32]) do not use byte values 1 to 31 (so only printable ASCII/ANSI), and after the first null terminator, the rest of the string has to be padded with nulls as well.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = At the time of writing, OpenMPT 1.30 (which adds support for this format) is not released yet.
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse-engineered by [[User:Saga|Saga]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

Karl Morton Music Format

2020-10-13T21:42:08Z

Saga: Created page with "{{Music Infobox | Type = Tracked | Instruments = PCM | NumChannels = 1-32 (only 4 usable in-game) | NumTracks = no limit | NumPatterns = n/a | NumOrders = n/a | Tags =..."

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-32 (only 4 usable in-game)
| NumTracks = no limit
| NumPatterns = n/a
| NumOrders = n/a
| Tags = Title, instrument names
| Games =
{{Game|Psycho Pinball}}
{{Game|Micro Machines 2}}
}}

The [[Karl Morton Music Format]] is the music format used by Karl Morton's sound engine used in the games [[Psycho Pinball]], [[Micro Machines 2]] and [[Back To Baghdad]], although the latter only uses its sound effect file format, not the music format. This is not the official name of the format, but as no official tooling or documentation seems to be available for this format, a simple name was chosen based on the sound engine author's name.

In general, this format follows the semantics of the ProTracker MOD format. Knowledge of the MOD format and its features is assumed.

A somewhat unique feature of this format is that subsongs can re-use samples with different metadata. For example, one song in a file might use a specific sample with a default volume of 64, while another song might reference the same sample data but with a default volume of 48. This allows for greater flexibility when reusing those samples between songs.

== File format ==

The format follows an IFF-like structure, but with no explicit file header (the file directly starts with the first chunk).

=== Chunk Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[4] || ID || chunk ID ("SONG" or "SMPL")
|-
| UINT32LE || length || chunk length, including this header (so must be at least 8)
|}

The first chunk in the file must be a SONG chunk, apart from this the chunk order doesn't matter.

Typically, SONG and SMPL chunks are interleaved, each SONG being followed by the SMPLs it adds to the sample pool shared between SONGs.
But this order should not be relied on.

=== SONG chunk ===

Each subsong is represented by its own SONG chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[32] || song name || Null-terminated song name
|-
| SAMPLE_REFERENCE[31] || sample map || maps song samples to those samples in the global sample pool
|-
| char[2] || unknown || always 0 (maybe just padding)
|-
| UINT32LE || number of channels || between 1 and 4 - file will be rejected if this is > 32. If it's more than 4 but less than 33 the extra channels will simply not be played.
|-
| UINT32LE || restart position || byte offset into music data
|-
| UINT32LE || size of music data || should be chunk size - 1108
|-
| char[] || music data || format is explained below
|}

<tt>SAMPLE_REFERENCE</tt> maps samples from the SMPL chunk pool to instrument numbers in the pattern editor (the first <tt>SAMPLE_REFERENCE</tt> is instrument 1, and so on). It is defined as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[32] || sample name || must reference one of the SMPL chunks
|-
| UINT8 || MOD finetune || 0...15
|-
| UINT8 || default volume || 0...64
|}

Music data is basically one gigantic pattern and stored in row-major order (like most module formats).
The pattern is played in a strictly linear order, there are no jump commands or pattern loops.
There is per-channel state that stores the last used note, instrument, command and parameter as well as a repeat counter.

To decode one pattern cell:

* If repeat counter > 0: Decrement repeat counter by 1 and reuse note, instrument, command and parameter from previous row. Continue with next channel.
* Read uint8, let's name it NOTE.
* If (NOTE AND 0x80): Reuse note, instrument, command and parameter from previous row and set repeat counter to (NOTE AND 0x7F). Continue with next channel.
* If NOTE is between 1 and 36 (inclusively), it's a regular note (C-1 to B-3 in ProTracker), otherwise no note is present
* Read uint8, let's name it INSTRUMENT.
* Set instrument number in this cell to INSTRUMENT AND 0x1F
* If (INSTRUMENT AND 0x80): Repeat previous command and parameter for this channel
* Otherwise, read the two uint8s, the command and parameter bytes.
* Continue with next channel.

Command bytes and their translation to ProTracker MOD commands:
* <tt>00</tt>: <tt>Cxx</tt>
* <tt>01</tt>: <tt>EAx</tt>
* <tt>02</tt>: <tt>EBx</tt>
* <tt>03</tt>: <tt>E1x</tt>
* <tt>04</tt>: <tt>E2x</tt>
* <tt>05</tt>: <tt>E5x</tt>
* <tt>06</tt>: <tt>9xx</tt>
* <tt>07</tt>: <tt>3xx</tt>
* <tt>08</tt>: <tt>5xx</tt>
* <tt>09</tt>: <tt>4xx</tt>
* <tt>0A</tt>: <tt>6xx</tt>
* <tt>0B</tt>: <tt>0xx</tt>
* <tt>0C</tt>: <tt>1xx</tt>
* <tt>0D</tt>: <tt>2xx</tt>
* <tt>0E</tt>: <tt>Axx</tt>
* <tt>0F</tt>: <tt>E9x</tt>
* <tt>10</tt>: Instant portamento (like 3FF but is always fully executed on first tick)
* <tt>11</tt>: <tt>ECx</tt>
* <tt>12</tt>: <tt>Fxx</tt>
* <tt>13</tt>: <tt>7xx</tt>
* <tt>14</tt>: <tt>000</tt> (empty command)

Missing MOD effects are: 8, B, D, E3, E4, E5, E6, E7, E8, ED, EE, EF.

Most commands that translate to extended Exy commands can take values > 0x0F as parameters (finetune command ignores high nibble).

The player will jump to the restart position once the repeat counter of each channel has reached 0 and no bytes are left to be read.

If no tempo is specified on the first row of the pattern, the MOD defaults of tempo 125 and 6 ticks per row are assumed.

=== SMPL chunk ===

Every sample is described by its own SMPL chunk.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[32] || sample name || Null-terminated, referenced by SONG chunks
|-
| UINT32LE || loop start || in bytes
|-
| UINT32LE || size of sample data || should be chunk size - 48
|-
| char[] || sample data || in 8-bit signed mono PCM format
|}

Note that a SMPL can be shared between songs and use different finetune and volume values between songs.

== A note on the string format ==

The last character of sample names must be a null-terminator (the engine uses a string comparison not limited to 32 characters when matching samples). 
While it is not required by the engine, the following restrictions are proposed for newly created files to keep the life of developers easy that have to support dozens of files and may thus want to employ heuristics whether files are of a specific type:
It is suggested that all strings (i.e. instances of char[32]) do not use byte values 1 to 31 (so only printable ASCII/ANSI), and after the first null terminator, the rest of the string has to be padded with nulls as well.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = At the time of writing, OpenMPT 1.30 (which adds support for this format) is not released yet.
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse-engineered by [[User:Saga|Saga]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2020-07-13T14:35:12Z

Saga:

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] (alternatively: 670 Format) was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

Note that for FM channels, the channel number modulo 4 is added to the resulting [[OPL_chip#A0-A8:_Frequency_Number|FNUM]] OPL parameter. This causes the note to be slightly detuned, which is used in the Zone 66 soundtrack to fatten some sounds by playing them on two neighbouring FM channels.

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}

Note: CDFM Tracker cannot not directly edit 670 files. However, it comes with a tool to convert them back into editable C67 files.

{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2020-07-13T14:30:26Z

Saga: /* 0x00-0x0C: Play note */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

Note that for FM channels, the channel number modulo 4 is added to the resulting [[OPL_chip#A0-A8:_Frequency_Number|FNUM]] OPL parameter. This causes the note to be slightly detuned, which is used in the Zone 66 soundtrack to fatten some sounds by playing them on two neighbouring FM channels.

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2020-07-13T14:28:25Z

Saga: Revert previous changes; they only apply to C67, the source format used by CDFM Tracker. Add information about detuned voices.

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

Note that for FM channels, the channel number modulo 4 is added to the resulting fnum OPL parameter. This causes the note to be slightly detuned, which is used in the Zone 66 soundtrack to fatten some sounds by playing them on two neighbouring FM channels.

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2020-07-13T13:54:09Z

Saga:

{{NeedMoreInfo}}
{{Music Infobox
| Type = Tracked
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [https://openmpt.org OpenMPT]
| Platform = Windows/Wine
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = Yes
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2020-07-13T13:53:47Z

Saga: Change from Custom to Tracker type; add OpenMPT to list of tools

{{NeedMoreInfo}}
{{Music Infobox
| Type = Tracked
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [OpenMPT https://openmpt.org]
| Platform = Windows/Wine
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = Yes
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

S3M Format

2020-07-07T08:44:24Z

Saga: /* File format */

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2xyy || Imago Orpheus x.yy
|-
| 0x3xyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker (old BeRoTracker version from between 2004 and 2012 identify as 0x4100)
|-
| 0x5xyy || OpenMPT x.yy
|-
| 0x6xyy || BeRoTracker x.yy
|-
| 0x7xyy || CreamTracker x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255. If the high bit is set, a channel is disabled (muted). Note that Scream Tracker 3 does not even process global effects (such as tempo changes) on muted channels.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Same as above + 128 (disabled)
|-
| 255 || Channel unused
|}

Adlib percussion channels are not implemented in Scream Tracker 3. All they do is showing a different channel type in the channel setup, but they don't do anything. There is no percussion instrument format defined, either.

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It translates the note freq just like with PCM instruments. The default value of 8363 (as with PCM instruments) means that middle-C plays at about 261.63 Hz (A440 pitch standard), and e.g. doubling it also doubles the middle-C frequency, as with samples.

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

S3M Format

2020-07-07T08:40:24Z

Saga: Clarify Adlib percussion channels

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2nyy || Imago Orpheus x.yy
|-
| 0x3nyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker (old BeRoTracker version from between 2004 and 2012 identify as 0x4100)
|-
| 0x5nyy || OpenMPT x.yy
|-
| 0x6nyy || BeRoTracker x.yy
|-
| 0x7nyy || CreamTracker x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255. If the high bit is set, a channel is disabled (muted). Note that Scream Tracker 3 does not even process global effects (such as tempo changes) on muted channels.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Same as above + 128 (disabled)
|-
| 255 || Channel unused
|}

Adlib percussion channels are not implemented in Scream Tracker 3. All they do is showing a different channel type in the channel setup, but they don't do anything. There is no percussion instrument format defined, either.

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It translates the note freq just like with PCM instruments. The default value of 8363 (as with PCM instruments) means that middle-C plays at about 261.63 Hz (A440 pitch standard), and e.g. doubling it also doubles the middle-C frequency, as with samples.

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

S3M Format

2020-07-07T08:37:30Z

Saga: Properly document disabled/mued channels

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2nyy || Imago Orpheus x.yy
|-
| 0x3nyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker (old BeRoTracker version from between 2004 and 2012 identify as 0x4100)
|-
| 0x5nyy || OpenMPT x.yy
|-
| 0x6nyy || BeRoTracker x.yy
|-
| 0x7nyy || CreamTracker x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255. If the high bit is set, a channel is disabled (muted). Note that Scream Tracker 3 does not even process global effects (such as tempo changes) on muted channels.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Same as above + 128 (disabled)
|-
| 255 || Channel unused
|}

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It translates the note freq just like with PCM instruments. The default value of 8363 (as with PCM instruments) means that middle-C plays at about 261.63 Hz (A440 pitch standard), and e.g. doubling it also doubles the middle-C frequency, as with samples.

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

S3M Format

2018-06-12T21:31:54Z

Saga: Update trackerVersion table

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2nyy || Imago Orpheus x.yy
|-
| 0x3nyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker (old BeRoTracker version from between 2004 and 2012 identify as 0x4100)
|-
| 0x5nyy || OpenMPT x.yy
|-
| 0x6nyy || BeRoTracker x.yy
|-
| 0x7nyy || CreamTracker x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Unused/invalid (but channel disabled)
|-
| 255 || Channel unused
|}

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It translates the note freq just like with PCM instruments. The default value of 8363 (as with PCM instruments) means that middle-C plays at about 261.63 Hz (A440 pitch standard), and e.g. doubling it also doubles the middle-C frequency, as with samples.

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

S3M Format

2018-06-12T21:30:09Z

Saga: Clarify how pitch works for AdLib instruments.

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2nyy || Imago Orpheus x.yy
|-
| 0x3nyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker
|-
| 0x5nyy || OpenMPT x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Unused/invalid (but channel disabled)
|-
| 255 || Channel unused
|}

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It translates the note freq just like with PCM instruments. The default value of 8363 (as with PCM instruments) means that middle-C plays at about 261.63 Hz (A440 pitch standard), and e.g. doubling it also doubles the middle-C frequency, as with samples.

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

CDFM Format

2018-06-12T21:23:36Z

Saga: Add pattern/order limits from Composer 670

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| NumPatterns = 128
| NumOrders = 256
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit '''unsigned''' PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2018-06-09T23:04:51Z

Saga: /* Pattern data (SB/AdLib) */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit unsigned PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|stereo? Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2 for digital channels (they have 4 octaves). FM channels have 7 octaves, and the middle-C is in octave 4.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is almost silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands. Volume is linear for both digital and FM channels, which needs to be translated for FM channels (the OPL chip has a logarithmic volume curve).

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

CDFM Format

2018-06-08T23:43:16Z

Saga: Can access more than 16 instruments (source: 670 to C67 conversion source)

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| Instruments2 = PCM
| NumChannels = 13
| NumTracks = 1
| Tags = None
| Games =
{{Game|Zone 66}}
}}

[[CDFM Format]] was developed by the demogroup Renaissance for their Amnesia demo, and was later used in their game [[Zone 66]]. It consists of either nine Adlib channels (for Adlib hardware), nine OPL and four PCM channels (for Sound Blaster hardware) or patches to be played as MIDI instruments (for GUS hardware.)

In Zone 66, most songs have hardware-specific versions, even where the SB song could drop the PCM channels and be played on Adlib. In these cases the PCM drum channels have been replaced with OPL instruments.

== File format ==

The file begins with a header. Those fields marked <nowiki>[</nowiki>GUS only] are missing entirely in SoundBlaster/AdLib songs, and those fields marked <nowiki>[</nowiki>AdLib/SB only] are missing entirely in the GUS variant of the song format.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || sampleOffset || '''[GUS only]''' Offset of instrument samples from start of file
|-
| BYTE || tempo || '''[Adlib/SB only]''' Playback speed, larger is slower '''[GUS only]''' Unknown, always 0x66, changing has no effect
|-
| BYTE || patternListSize || Size of pattern list
|-
| BYTE || numPatterns || Number of patterns in song
|-
| BYTE || numDigInst || Number of PCM or GUS instruments in song
|-
| BYTE || numOPLInst || '''[Adlib/SB only]''' Number of OPL instruments in song
|-
| BYTE || loopDest || Index into <tt>patternOrder</tt> for next pattern to play after the final one when looping the song
|-
| UINT32LE || sampleOffset || '''[Adlib/SB only]''' Offset of instrument samples from start of file
|-
| UINT8[patternListSize] || patternOrder || Order of patterns in the song, <tt>patternListSize</tt> bytes in length
|-
| UINT32LE[numPatterns] || patternOffset || Offset of each pattern's data, relative to the start of the pattern data
|-
| PCM_INST[numDigInst] || pcmInst || '''[Adlib/SB only]''' 16 bytes of info for each digital (PCM) instrument
|-
| OPL_INST[numOPLInst] || oplInst || '''[Adlib/SB only]''' 11-byte instrument patch for each FM (OPL) instrument
|-
| GUS_INST[numDigInst] || gusInst || '''[GUS only]''' 11 bytes of info for each GUS patch
|}

The pattern data immediately follows. The <tt>patternOffset</tt> values are relative to this position, so a value of 0x00000000 corresponds to the first byte here.

<tt>PCM_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT32LE || address_ptr || Used to place address of sample start in memory - ignore when reading, write as 0x00000000
|-
| UINT32LE || length || Length of sample, in bytes
|-
| UINT32LE || loopStart || Offset of loop return, in bytes, relative to start of sample
|-
| UINT32LE || loopEnd || Offset of loop trigger, in bytes, relative to start of sample. Use 0x00FFFFFF for no loop.
|}

The PCM instruments begin at <tt>sampleOffset</tt> and are raw (no header) 8-bit unsigned PCM data. If the sample loops, as soon as playback reaches <tt>loopEnd</tt> (which could be before the end of the sample), playback will immediately jump to <tt>loopStart</tt>. The middle-C frequency for all PCM instruments is fixed at 8287 Hz (ProTracker standard).

<tt>OPL_INST</tt> is:

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|}

The OPL base registers in this list are for the two operators controlling the first OPL channel. Adjust them accordingly for the relevant OPL channel.

<tt>GUS_INST</tt> is:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || flags || Bitfield: 1={{TODO|stereo? Makes pitch higher}}, 2=loop, 16={{TODO|unknown - mutes instrument}}
|-
| UINT16LE || rate || Playback sampling rate for pitch to be middle-C
|-
| UINT32LE || loopStart || Sample offset, in bytes, of loop start
|-
| UINT32LE || length || Length of sample, in bytes
|}

All sample data is 8-bit '''signed'''. If the loop bit is set (i.e. <tt>flags & 2</tt>) then when the end of the sample is reached playback jumps immediately to the byte offset indicated by <tt>loopStart</tt>.

== Tempo ==

All songs use the standard module speed/tempo system. The tempo is fixed at 144, and the speed can be changed per song. For SB/AdLib songs, the speed is set once with the value obtained from the file header, while GUS songs include a 'set speed' command at the start of each pattern.

== Pattern data (SB/AdLib) ==

The musical score data for SoundBlaster/AdLib files consists of a sequence of variable-length commands, in the following format:

=== 0x00-0x0C: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3
|-
| 0x00 || <tt>jfffnnnn</tt> || <tt>iiiivvvv</tt>
|}

Play a note on the given channel.

* The command byte is 0x00 through 0x0C. The value controls the channel used for the note:
** 0x00: digital 1
** 0x03: digital 4
** 0x04: FM 1
** 0x0C: FM 9
** 0x0D-0x0F: Invalid
* <tt>j</tt>: High (fifth) bit of instrument number.
* <tt>fff</tt>: The octave of the note to play. Middle-C is within octave 2.
* <tt>nnnn</tt>: The number of the note to play within the octave (0-11).
* <tt>iiii</tt>: The lower four bits of the instrument to use. A value of zero uses the first instrument. This is the first PCM instrument on a digital channel, and the first OPL instrument on an FM channel.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume. Notes can be played with zero velocity and then faded in with subsequent volume change commands.

=== 0x20-0x2C: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x20 || <tt>0000vvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x20 through 0x2C, with the lower four bits representing the channel number as with playing a note.
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

=== 0x40: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x40 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x60: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x60
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x80: Unknown ===

This command is not used in any known files and crashes Zone 66. Its purpose, or perhaps incomplete intended purpose, is unknown.

== Pattern data (GUS) ==

The musical score data for GUS files also consists of a sequence of variable-length commands, however the commands are different from the ones used in SB/AdLib files. The commands are in the following format:

=== 0x00: Delay ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>tttttttt</tt>
|}

Delay for the given number of ticks before continuing with the next event.

* <tt>tttttttt</tt>: Number of ticks to wait

=== 0x01: Set speed ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x01 || <tt>ssssssss</tt>
|}

Adjust the song playback speed.

* <tt>ssssssss</tt>: New speed. This is the same as the 'speed' in standard .mod files (i.e. the number of frames per row), with the module tempo fixed at 144.

=== 0x02: End of pattern ===

{|class="wikitable"
! Command
|-
| 0x02
|}

This must be the last command in each pattern. Playback will jump to the next pattern in the sequence specified in the song header.

=== 0x40-0x4F: Play note ===

{|class="wikitable"
! Command !! Byte 2 !! Byte 3 !! Byte 4
|-
| 0x00 || <tt>ffffffff</tt> || <tt>ppppvvvv</tt> || <tt>iiiiiiii</tt>
|}

Play a note on the given channel.

* The command byte is always 0x40 through 0x4F. The value controls the channel used for the note:
** 0x00: GUS channel 1
** 0x01: GUS channel 2
** 0x0F: GUS channel 16 {{TODO|Assumed, please confirm}}
* <tt>ffffffff</tt>: Note. Add 25 to this value (i.e. transpose up by two octaves and one note) to obtain standard MIDI note numbers.
* <tt>pppp</tt>: Panning, 0=centre, 1=full right, 15=full left
* <tt>vvvv</tt>: Velocity, logarithmic, 0=silent, 1=1%, 2=4%, 3=7% ... 12=49.8%, 13=60%, 14=74.9%, 15=100%
* <tt>iiiiiiii</tt>: Instrument, 0=first, 1=second, etc.

=== 0x80-0x8F: Set volume ===

{|class="wikitable"
! Command !! Byte 2
|-
| 0x80 || <tt>ppppvvvv</tt>
|}

Set the volume of the playing note on the given channel.

* The command byte is 0x80 through 0x8F, with the lower four bits representing the channel number as with playing a note.
* <tt>pppp</tt>: {{TODO|Assumed pan value, same as for note-on}}
* <tt>vvvv</tt>: Note volume/velocity. 0x0 is silent, 0xF is full volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes; except GUS
| canModify = Yes; except GUS
| canExport = Yes
| canImport = Yes; except GUS
| editHidden = N/A
| editMetadata = N/A
}}
{{FileFormatTool
| Name = [http://sbfmdrv.blogspot.com.au/2015/12/renaissance-cdfm-music.html CDFM Tracker]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
}}
{{EndFileFormatTools}}

== Credits ==

This file format was reverse engineered by [[User:Malvineous|Malvineous]]. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

S3M Format

2018-05-31T18:04:28Z

Saga: Clarification on Sustain value

{{Stub}}
{{Music Infobox
| Type = Tracked
| Instruments = PCM
| Instruments2 = OPL
| NumChannels = 32
| NumTracks = 255
| NumPatterns = 65,536
| NumOrders = 65,536
| Tags = Title, instrument names
| Games =
{{Game|Unreal Tournament}}
}}

[[S3M Format]] is used to save modules composed in ScreamTracker 3. A number of games support music in this format, however it is primarily used for composing independent songs unrelated to games.

The format is notable both for its popularity, as well as for being one of the few that support both FM/OPL and sampled instruments.

== File format ==

The file begins with a header.

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, must be null-terminated
|-
| UINT8 || sig1 || Signature byte, always 0x1A
|-
| UINT8 || type || Song type, always 0x10 for S3M
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT16LE || orderCount || Number of entries in the order table, should be even
|-
| UINT16LE || instrumentCount || Number of instruments in the song
|-
| UINT16LE || patternPtrCount || Number of pattern parapointers in the song
|-
| UINT16LE || flags || See below
|-
| UINT16LE || trackerVersion || upper four bits is tracker ID, lower 12 bits is tracker version
|-
| UINT16LE || sampleType || 1=signed samples [deprecated], 2=unsigned samples
|-
| char[4] || sig2 || Signature: "SCRM"
|-
| UINT8 || globalVolume ||
|-
| UINT8 || initialSpeed || Frames per row, can be changed later with <tt>A</tt> command
|-
| UINT8 || initialTempo || Frames per second, can be changed later with <tt>T</tt> command
|-
| UINT8 || masterVolume || bit 7: 1=stereo, 0=mono, bits 6-0: volume
|-
| UINT8 || ultraClickRemoval || Number of channels to use for click removal on real GUS hardware
|-
| UINT8 || defaultPan || 252=read pan values in header, anything else ignores pan values in header
|-
| BYTE[8] || reserved || Unused, some trackers store data here
|-
| UINT16LE || ptrSpecial || Parapointer to additional data, if <tt>flags</tt> has bit 7 set
|-
| UINT8[32] || channelSettings || See below
|-
| UINT8[orderCount] || orderList || Which order patterns are played in
|-
| UINT16LE[instrumentCount] || ptrInstruments || List of parapointers to each instrument's data
|-
| UINT16LE[patternPtrCount] || ptrPatterns || List of parapointers to each pattern's data
|}

Flags are one or more values below:

{|class="wikitable"
! Bit !! Value !! Description
|-
| 0 || 1 || ST2 vibrato [deprecated]
|-
| 1 || 2 || ST2 tempo [deprecated]
|-
| 2 || 4 || Amiga slides [deprecated]
|-
| 3 || 8 || 0vol optimisations - automatically turn off looping notes when the volume is zero for more than two rows
|-
| 4 || 16 || Amiga limits - ignore notes beyond Amiga hardware limits (as Amiga does.) Sliding up stops at B#5. Also affects other Amiga compatibility issues.
|-
| 5 || 32 || Enable SoundBlaster filter/sfx [deprecated]
|-
| 6 || 64 || ST3.00 volume slides - perform volume slides on first row as well. Set implicitly if <tt>trackerVersion</tt> is 0x1300.
|-
| 7 || 128 || <tt>ptrSpecial</tt> is valid
|}

Known <tt>trackerVersion</tt> values are:

{|class="wikitable"
! Value !! Description
|-
| 0x1300 || ScreamTracker 3.00
|-
| 0x1301 || ScreamTracker 3.01
|-
| 0x1303 || ScreamTracker 3.03
|-
| 0x1320 || ScreamTracker 3.20
|-
| 0x2nyy || Imago Orpheus x.yy
|-
| 0x3nyy || Impulse Tracker x.yy
|-
| 0x4nnn || Schism Tracker
|-
| 0x5nyy || OpenMPT x.yy
|-
| 0xCA00 || Camoto/libgamemusic
|}

<tt>channelSettings</tt> is 32 values indicating the audio channel assignments for each of the 32 S3M channels. Unused channels should be set to 255.

{|class="wikitable"
! Value !! Description
|-
| 0 to 7 || Left PCM channels 1 to 8
|-
| 8 to 15 || Right PCM channels 1 to 8
|-
| 16 to 24 || Adlib melody channel 1-9
|-
| 25 || Adlib percussion channel: bass drum
|-
| 26 || Adlib percussion channel: snare drum
|-
| 27 || Adlib percussion channel: tom tom
|-
| 28 || Adlib percussion channel: top cymbal
|-
| 29 || Adlib percussion channel: hi-hat
|-
| 30 to 127 || Unused/invalid
|-
| 128 to 254 || Unused/invalid (but channel disabled)
|-
| 255 || Channel unused
|}

<tt>orderList</tt> contains the index of each pattern to be played. The first entry in this array is the index of the first pattern to play, the second entry is the second pattern, etc. If an entry is 0xFE then it is a "marker pattern" and is skipped during playback, and an entry of 0xFF signifies the end of the song.

<tt>ptrInstruments</tt> and <tt>ptrPatterns</tt> are arrays of parapointers to the start of the instrument and pattern data. Each parapointer is an offset from the start of the file, in units of 16 bytes (a "paragraph"). To convert this into a normal byte-level file offset, multiply it by 16 (or shift-left by 4.)

By convention these blocks follow the header above, but this is not a requirement and they can occur at any point in the file.

=== Timing ===

The <tt>initialTempo</tt> and <tt>initialSpeed</tt> values are the ones to use until optionally changed during playback, with the A and T effects respectively.

The <tt>initialTempo</tt> value controls how many audio frames are generated per second. If this value is 50, then there should be 50 audio frames per second. Obviously the more audio frames per second, the shorter each frame is going to be. To calculate the length of each frame, a formula like this can be used:

frame length in seconds = 1 / initialTempo
0.02 seconds per frame = 1 / 50

The <tt>initialSpeed</tt> value controls how many audio frames comprise a single row of the song. If the value is 3, then there are three audio frames per row. For certain effects, they are updated once per frame (i.e. the effect changes between rows.)

To calculate playback speed, both these values need to be taken into account. The tempo value controls the length of each audio frame, while the speed value controls how quickly the rows are turned into those audio frames. For example, to calculate the number of rows per second:

rowsPerSecond = initialTempo / initialSpeed

=== Instruments ===

At the offset given by an instrument's parapointer, the data has a header as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || type || 0=empty instrument (message only), 1=PCM instrument
|-
| char[12] || filename || Original instrument filename in DOS 8.3 format, no terminating null
|}

{|class="wikitable"
! Value !! Description
|-
| 0 || empty instrument (message only)
|-
| 1 || PCM instrument
|-
| 2 || Adlib melody instrument
|-
| 3 || Adlib percussive: bass drum
|-
| 4 || Adlib percussive: snare
|-
| 5 || Adlib percussive: tom tom
|-
| 6 || Adlib percussive: top cymbal
|-
| 7 || Adlib percussive: hi-hat
|}

The data following the header depends on whether the instrument is PCM or Adlib.
{{TODO|What if the instrument is empty, is there any trailing data?}}

==== PCM ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || ptrDataH || Upper eight bits of parapointer to sample data, relative to start of S3M file
|-
| UINT16LE || ptrDataL || Lower 16 bits of parapointer to sample data, relative to start of S3M file
|-
| UINT32LE || length || Sample data length, in bytes. S3M is limited to 64000 and ignores upper 16 bits.
|-
| UINT32LE || loopStart || Offset of loop start in bytes, relative to start of sample data.
|-
| UINT32LE || loopEnd || Offset of loop end in bytes, relative to start of sample data.
|-
| UINT8 || volume || Default volume of sample, 0-63 inclusive.
|-
| UINT8 || reserved || Always 0x00
|-
| UINT8 || pack || 0=unpacked, 1=DP30ADPCM [deprecated]
|-
| UINT8 || flags || Sum: 1=loop on, 2=stereo (data is <tt>length</tt> bytes for left channel then <tt>length</tt> bytes for right channel), 4=16-bit little-endian sample
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4)
|-
| BYTE[12] || internal || Always zero, used in-memory during playback
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRS"
|}

ScreamTracker stores the above instrument structures at the start of the file, but stores the sample data at the end of the file (after the pattern data.) This is not the only way to store it though.

==== Adlib ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8[3] || reserved || Always 0x00 0x00 0x00
|-
| UINT8[12] || oplValues || See below
|-
| UINT8 || volume || Default volume of instrument, 0-63 inclusive.
|-
| UINT8 || dsk || {{TODO|Unknown}}
|-
| UINT16LE || reserved || Always 0x0000
|-
| UINT32LE || c2spd || Sample rate for middle-C note (C-4), see below.
|-
| BYTE[12] || unused || Always zero
|-
| char[28] || title || Sample title, for display to user. Must be null-terminated.
|-
| char[4] || sig || Signature: "SCRI"
|}

The <tt>oplValues</tt> are stored as follows:

{|class="wikitable"
!rowspan=2| Byte index !!rowspan=2| Operator !!rowspan=2| OPL base register !!colspan=8| Bits
|-
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| 0 || Modulator || 0x20 ||align=center rowspan=2| Tremolo? ||align=center rowspan=2| Vibrato? ||align=center rowspan=2| Sustain? ||align=center rowspan=2| KSR? ||align=center rowspan=2 colspan=4| Freq. mult.
|-
| 1 || Carrier || 0x23
|-
| 2 || Modulator || 0x40 ||align=center rowspan=2| Scale level (bit 0) ||align=center rowspan=2| Scale level (bit 1) ||align=center rowspan=2 colspan=6| Output level (0=loudest, 63=silent)
|-
| 3 || Carrier || 0x43
|-
| 4 || Modulator || 0x60 ||align=center rowspan=2 colspan=4| Attack rate ||align=center rowspan=2 colspan=4| Decay rate
|-
| 5 || Carrier || 0x63
|-
| 6 || Modulator || 0x80 ||align=center rowspan=2 colspan=4| Sustain rate ||align=center rowspan=2 colspan=4| Release rate
|-
| 7 || Carrier || 0x83
|-
| 8 || Modulator || 0xE0 ||align=center rowspan=2 colspan=8| Wave select
|-
| 9 || Carrier || 0xE3
|-
| 10 || Modulator || 0xC0 ||align=center colspan=7| Feedback ||align=center| Connection
|-
| 11 || - || - ||align=center colspan=8| Unused, set to 0x00
|}

<tt>c2spd</tt> sets the instrument tuning. It scales the note freq {{TODO|somehow}} - the exact formula is unknown. The default value is 8363 as with PCM instruments, and increasing this by roughly 10 tunes the note up by one OPL F-num (approx 0.7Hz in OPL block 2).

Notes:
* The value packing is almost identical to that used in the [[SBI Format]], just the bytes are in a different order.
* The ST3 docs say bytes 2-3 bits 5-0 are "63-volume" but this is to make the values match PCM samples. The value in the file matches the value sent to the OPL chip.
* The Scale Level bits in bytes 2-3 are swapped. The ST3 technical docs have a typo that suggest Scale Level (bit 1) actually overflows into "bit 8" of the OPL register, but testing this in ST3 shows this is not the case and the bit order is merely swapped.
* The ST3 docs say bytes 6-7 have the sustain rate stored as "15-sustain", which is from a editor UI perspective - the value can be sent as-is to the OPL chip.

=== Patterns ===

At the offset given by a pattern's parapointer, packed data is present and will need to be unpacked. The following structure appears at the start of each pattern's data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || packed_len || Length of packed data for all 64 rows, in bytes
|-
| BYTE[packed_len - 2] || packed_data || Packed row data, described below
|}

<tt>packed_len</tt> includes its own length, so as it is two bytes long, the length of the packed data will be two bytes less than this value. The first byte in <tt>packed_data</tt> is a bitfield called <tt>what</tt>, and it is broken up as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| <tt>command</tt> and <tt>info</tt> present
| <tt>volume</tt> present
| <tt>note</tt> and <tt>instrument</tt> present
|colspan=5 align=center| Channel number
|}

If the whole byte is zero then it signals the end of the row. This byte and the ones following are further described in the following table.

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || what || 0=end of row, lower five bits (<tt>what & 0x1F</tt>) are channel number
|-
| UINT8 || note || Note number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || instrument || Instrument number (only present if <tt>what & 0x20</tt>)
|-
| UINT8 || volume || Volume level (only present if <tt>what & 0x40</tt>)
|-
| UINT8 || command || Effect type (only present if <tt>what & 0x80</tt>)
|-
| UINT8 || info || Effect value (only present if <tt>what & 0x80</tt>)
|}

After these bytes the process repeats with another <tt>what</tt> value. When <tt>what</tt> is 0x00 the end of the row has been reached. After the 64th row has been reached, the pattern ends and <tt>packed_len</tt> bytes will have been read.

Be aware that <tt>channel</tt> is a value between 0 and 31 inclusive, which corresponds to an entry in the <tt>channelSettings</tt> field in the header.

The <tt>volume</tt> field is 0 for silent, 64 for full volume (note this is 65 unique values), or 255 for 'ignore' (shown as ".." in the tracker.) If the value is 255 or missing entirely, the instrument's default volume is used (the <tt>volume</tt> value from the instrument settings.)

The upper four bits of <tt>note</tt> store the octave, and the lower four bits store the semitone (with 0=C, 1=C#, up to 11=B)

=== Effects ===

==== 0x01/A: Set speed ====

Set ''speed'' (one of the two tempo variables.) Data byte is new speed. A value of 0 causes the event to be ignored.

==== 0x02/B: Order jump ====

After the current row has finished playing, the next row is the first row in order given by the data byte. 0 means the start of the song {{TODO|Confirm this}}.

==== 0x03/C: Jump to row ====

After the current row has finished playing, the next row is played from the next pattern in the order sequence. The row in this next pattern is given by the data byte, but the data byte is decimal-as-hex. So a value of 0x12 should be treated as decimal 12. These formulae will calculate the correct row (to/from the S3M value):

row = (data >> 4) * 10 + (data & 0x0f) // Read S3M into variable
data = ((row / 10) << 4) | (row % 10) // Write variable to S3M

The first row in the pattern is 0. If the decoded data value is larger than 63, the effect is ignored.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://schismtracker.org/ SchismTracker]
| Platform = Windows/Linux
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = .it + more
| canImport = [[MOD Format|.mod]] .it + more
| editHidden = No
| editMetadata = Yes
| notes = Can play OPL and PCM simultaneously
}}
{{FileFormatTool
| Name = ScreamTracker 3
| Platform = DOS
| canPlay = Yes
| canModify = Yes
| canCreate = Yes
| canExport = [[MOD Format|.mod]]
| canImport = [[MOD Format|.mod]]
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{EndFileFormatTools}}

== External links ==

Much of this information was combined from the following sites:

* TECH.DOC distributed with ScreamTracker 3
* [http://wiki.multimedia.cx/index.php?title=Scream_Tracker_3_Module S3M on the MultimediaWiki]
* [http://schismtracker.org/wiki/FS3MDOC.TXT FS3MDOC.TXT] - S3M Player Tutorial

SBI Format

2018-05-31T18:01:43Z

Saga: /* Instrument settings */

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 1
| NumTracks = 0
| Tags = Title
}}
The '''SBI (Sound Blaster Instrument) Format''' stores a single instrument suitable for playback on a sound card with an OPL2 or OPL3 chip.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "SBI" followed by 0x1A
|-
| [[char]][32] || name || Instrument title (must be NULL-terminated)
|-
| [[BYTE]][16] || inst || Instrument settings (see below)
|}

=== Instrument settings ===

The instrument is in the following format. This is identical to the format used for each instrument in [[CMF Format]] songs and [[IBK Format]] instrument banks.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[BYTE]][5]
|colspan=3|Padding to bring instrument definition up to 16 bytes. Sometimes a byte is missing, resulting a 51-byte file rather than a 52-byte file. It is probably safer to not expect this padding to exist at all.
|}

==== Percussive instruments ====

There is no indication as to whether a given instrument should be played in melodic or percussive mode. Playing an instrument destined for one mode in the other usually sounds quite bad.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[SBI Format|.sbi]]
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{FileFormatTool
| Name = [[SBANK]]
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Сan convert SBI between [[AdLib Instrument Format|AdLib INS]] format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{EndFileFormatTools}}

SBI Format

2018-05-31T18:01:19Z

Saga:

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 1
| NumTracks = 0
| Tags = Title
}}
The '''SBI (Sound Blaster Instrument) Format''' stores a single instrument suitable for playback on a sound card with an OPL2 or OPL3 chip.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "SBI" followed by 0x1A
|-
| [[char]][32] || name || Instrument title (must be NULL-terminated)
|-
| [[BYTE]][16] || inst || Instrument settings (see below)
|}

=== Instrument settings ===

The instrument is in the following format. This is identical to the format used for each instrument in [[CMF Format]] songs and [[IBK Format]] instrument banks.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[BYTE]][5]
|colspan=3|Padding to bring instrument definition up to 16 bytes. Sometimes a byte is missing, resulting a 51-byte file rather than a 52-byte file. It is probably the safer to not expect this padding to exist at all.
|}

==== Percussive instruments ====

There is no indication as to whether a given instrument should be played in melodic or percussive mode. Playing an instrument destined for one mode in the other usually sounds quite bad.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[SBI Format|.sbi]]
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{FileFormatTool
| Name = [[SBANK]]
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Сan convert SBI between [[AdLib Instrument Format|AdLib INS]] format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{EndFileFormatTools}}

DSIK Module Format

2018-03-12T19:13:21Z

Saga: Some corrections

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 65,535 (only 255 playable)
| NumOrders = 128
| Tags = Title, instrument names, instrument filenames
| Games =
{{Game|Trugg}}
{{Game|Flying Tiger}}
{{Game|Rollin}}
}}

The [[DSIK Module Format]] is the music format used by the ''Digital Sound Interface Kit'' by Carlos Hasan. This was a C and Pascal library for game authors to simplify sound card programming.

== File format ==

The file is a '''non-standard''' [[Resource Interchange File Format (RIFF)]] structure. It is exactly the same as a standard RIFF file, except that the padding bytes between chunks have been omitted. So if the length of a chunk is an odd number, the padding byte should not be included and the following chunk will not start on a word boundary.

The files are composed of the following chunks:

* RIFF (type: DSMF)
** SONG
** INST
** PATT

The data in each chunk is explained below.

=== SONG chunk ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[28] || title || Song title, null-terminated
|-
| UINT16LE || version || File version
|-
| UINT16LE || flags ||
|-
| UINT32LE || pad ||
|-
| UINT16LE || numOrders || Number of valid entries in <tt>orders</tt>
|-
| UINT16LE || numSamples ||
|-
| UINT16LE || numPatterns ||
|-
| UINT16LE || numChannels ||
|-
| UINT8 || volGlobal || Global volume
|-
| UINT8 || volMaster || Master volume
|-
| UINT8 || initialSpeed ||
|-
| UINT8 || initialBPM ||
|-
| UINT8[16] || channelMap ||
|-
| UINT8[128] || orders || Order list. First value is index of first pattern to play, etc.
|}

=== INST chunk ===

This chunk stores all the instruments in the song. There are multiple '''INST''' chunks in the file, one per instrument. The data in each chunk is as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[13] || filename || Instrument filename, null-terminated
|-
| UINT16LE || flags || Zero or more of: 1=loop active, 2=signed PCM, 4=packed PCM, 64=delta PCM
|-
| UINT8 || volume || Default volume of the sample if not volume is given when a note is played. The range is from 0 (silent) to 64 (loudest), note this is 65 different values.
|-
| UINT32LE || length || Length of the sample data, in bytes.
|-
| UINT32LE || loopStart || Position of the loop start point, in bytes, relative to the start of the sample data.
|-
| UINT32LE || loopEnd || Position of the loop end point, in bytes, relative to the start of the sample data.
|-
| UINT32LE || address_ptr || Used internally for holding in-memory address of sample data, ignore when reading and write as zero.
|-
| UINT16LE || midCRate || Default is 8363
|-
| UINT16LE || period || Default for middle-C is 428
|-
| char[28] || title || Sample name, null-terminated
|-
| BYTE[length] || data || Sample data, 8-bit mono PCM
|}

Sample data must be 8-bit mono PCM, signed or unsigned based on <tt>flags</tt> {{TODO|Confirm that signed PCM actually works}}. Other formats are rejected by the DSIK library. Some samples appear to be truncated .wav files and still have the 'data' fourcc visible, however this is not part of the format and these bytes will be played as audio data, causing an audible click at the start of playback.

The period is calculated from a sample rate (in Hertz) as <code>period = 8363 * 428 / Hertz</code>

=== PATT chunk ===

This chunk stores all the patterns in the song. There are multiple '''PATT''' chunks in the file, one per pattern. The data in each chunk is as follows:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || length || Length of pattern data, in bytes, including this length field also
|-
| UINT8[length - 2] || data || Pattern data, see below
|}

The pattern data is comprised of a flag byte, followed by a variable number of data bytes depending on the value of the flag. This is very similar to [[S3M Format]] but the bit fields are different. The flag byte is broken down as follows:

{|class="wikitable"
!width=100| 7 !!width=100| 6 !!width=100| 5 !!width=100| 4 !!width=100| 3 !!width=100| 2 !!width=100| 1 !!width=100| 0
|-
| Note present
| Instrument present
| Volume present
| Command present
|colspan=4 align=center| Channel number
|}

* If the entire value is zero, the row number is incremented and the next flag is read. Otherwise:
* If the flag indicates a note is present, the next byte is the note. Note numbers are semitones, with note 49 being middle C, note 50 being C#4, note 51 being D4, etc. Adding 11 to the note number will turn them into standard MIDI note numbers.
* If an instrument is present, the next byte is the zero-based index of the instrument to use.
* If a volume is present, the next byte is the volume for this note/channel. The range is from 0 (silent) to 64 (loudest), note this is 65 different values.
* If a command is present, the next two bytes are the command and value respectively. Standard .mod commands appear to be used {{TODO|Confirm}}

After these bytes have been read, the next flag byte is read. Once 64 rows have been read, the end of the pattern data should have been reached.

If the instrument is read but it is zero, then the previous instrument on that channel should be used instead (same as S3M).

Effects 0x00 through 0x0F are the same as in MOD files. The OpenMPT code references effect IDs greater than 0x0F but no such commands have been found in the wild.

Effect 0x08 is 7-bit panning (0x00 = left, 0x80 = right) with parameter 0xA4 enabling surround. DSIK is quite possibly the origin of this panning scheme which was later adopted by other S3M players.

=== Timing ===

See [[S3M Format#Timing]] for a discussion on timing using the <tt>initialBPM</tt> and <tt>initialSpeed</tt> values.

=== Design issues ===

The file format suffers from a number of design inconsistencies:

* The '''DSMF''' format should have been registered with Microsoft as it is in uppercase, however this does not appear to have been done
* The '''INST''' and '''PATT''' chunks should have been placed inside '''LIST''' chunks, in the spirit of the RIFF format
* The instrument chunk includes a length field for the sample data, however this is redundant as the chunk itself already has a length. The two length fields do make it possible to store additional data between the end of the sample data and the end of the chunk, which would normally be ignored, however it seems simpler to just define a new chunk type if new data needs to be stored without breaking backwards compatibility.
* The instrument chunk stores an address field even though this is only used during playback and does not need to be stored in the file.
* The pattern chunk also has an extra field to store the length of the pattern data. However the value in this field includes the length of the field itself, making the value identical to the RIFF chunk's length field. The result is that the identical value is written twice, once as a 32-bit value for the RIFF PATT chunk and then immediately again as a 16-bit value.
* The number of instruments and patterns is stored in the '''SONG''' chunk, however this is redundant as the values can be calculated from the number of '''INST''' and '''PATT''' chunks respectively.
* There is a 16-bit value for the number of orders, allowing up to 65,535 orders in the song, yet there is a fixed-length array allowing only 128 orders.
* The pattern count is 16-bit allowing up to 65,536 patterns in the song, but the order list is made up of 8-bit values, meaning only the first 256 patterns can be played.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Many
| canImport = Many
| editHidden = No
| editMetadata = Yes
| notes = Minimal support for effects
}}
{{FileFormatTool
| Name = Chronos Module Converter
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .mtm .dsm .psm
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Most accurate for converting .dsm to .s3m
}}
{{FileFormatTool
| Name = DSIK's <tt>conv.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .669 .mtm
| editHidden = No
| editMetadata = Yes
| notes = Official tool
}}
{{FileFormatTool
| Name = ModPlug
| Platform = Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Plays at wrong tempo (no support for effect 0x0F)
}}
{{FileFormatTool
| Name = OpenMPT
| Platform = Any
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Many
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{EndFileFormatTools}}

== External links ==

* The original Digital Sound Interface Kit library is available as <tt>dsik_c.zip</tt> or <tt>dsik_pas.zip</tt> for the C and Pascal versions respectively, from various FTP sites such as [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/wgt/ lanet.lv]

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] by reading the DSIK sample code, with the pattern data documented from reading the OpenMPT source code. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

[[Category:DSIK]]

ProTracker Studio Module

2017-05-19T11:48:47Z

Saga: Do not call it "old" format when it in fact appears to be newer.

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop. The format not used in Sinaria will be called "regular" in this document.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "regular" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "Sinaria" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the "regular" variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. You may want to deal with this by first reading for bytes, and if they are equal to "PATT", read four more bytes for the pattern ID.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the regular or Sinara version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in regular format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $02: Play Range: N/A
* $03: Jump Loop: N/A
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip: N/A
* $06: Transpose: N/A
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

N/A: This chunk does nothing or freezes MASI. There is no need to implement this.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [https://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [https://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-12-12T23:48:16Z

Saga:

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the most common variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

The order list describes how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. In most module formats, the order list only consists of pattern indices, but in the PSM format it resembles a tiny scripting language that can do more than just list patterns. For example, It typically contains chunks that set the tempo of the song and the channel panning. In theory, these chunks can occur between two pattern chunks, changing the tempo or panning of a pattern without having to duplicate the pattern data, but in practice this feature is not used, so it can be ignored when writing a PSM loader.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by its first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $02: Play Range: N/A
* $03: Jump Loop: N/A
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (not 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $05: Channel Flip: N/A
* $06: Transpose: N/A
* $07 (2 Bytes): Next byte sets the speed (ticks/row) for this subtune
* $08 (2 Bytes): Next byte sets the tempo for this subtune
* $0C (7 Bytes): Sample map table: This chunk is always $0C $00 $FF $00 $00 $01 $00. This seems to be an unfinished feature of the order list scripting language. It appears that this maps e.g. what is "I0" in the file to sample 1. Only the fourth and fifth byte ($00 $00) actually seem to do something: They translate the sample number in the pattern to different instruments in the file.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

N/A: This chunk does nothing or freezes MASI. There is no need to implement this.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-08-03T01:53:10Z

Saga:

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

There are actually two slightly different variants of the new formats: A common one used in several games, and one used in the game Sinaria. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format. But Sinaria was released later than or around the same time as most other games using the new PSM format, so maybe it just took really long to develop.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the most common variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-08-03T01:24:45Z

Saga:

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' There are two variants of the format. In the most common variant, the pattern ID is 4 bytes long and starts with a 'P', followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value.
In the format used in the game Sinaria, This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '. It is not entirely clear if the format used in Sinaria is newer or older - in some ways, like the effect interpretation, it resembles PSM16 more than the new format, so it could be an earlier version of the new PSM format.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is slightly different in Sinaria's format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in Sinaria format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be finetune in Sinaria, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate). MASI ignores the upper 16 bits, even if they are non-zero.
19 $00-bytes follow (padding?)
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes (so that the struct is 96 bytes large in both formats).

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-08-03T00:35:26Z

Saga: /* Patterns */

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Flags Contains four flags that indicate which pattern data follows
+1 1 Chan The channel this data belongs to.
+2 1 Note Present if bit 7 in Flags is set. Pitch, $01 is C-1, etc... The octaves
are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Present if bit 6 in Flags is set. Instrument used, 0-31
+4 1 Vol Present if bit 5 in Flags is set. Volume change to, 0-63 = 0-127; optional
+5 1 Effect Present if bit 4 in Flags is set. Effect to use, volume slide, Portamanto...
+6 x Eff Am Present if bit 4 in Flags is set. Parameter of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The highest four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect parameter ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present depending on their flag and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect parameter.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (xx corresponds to the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes Bxx - position jump - ignored by PLAY.EXE
34 1 Byte Cxx - break to row
PLAY.EXE entirely ignores the parameter (it always breaks to the first
row), so it is maybe best to do this in your own player as well.
If the original file was an S3M, the parameter is double-BCD-encoded,
i.e. on top of the original format's BCD encoding, the same encoding
is applied again. to translate into the correct target row in binary,
apply this twice: param = (param & 0xF0) * 10 + (param & 0x0F)
For MOD files, the parameter is a normal binary number.
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format. Slide command parameters are more like in PSM16.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate)
19 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-08-02T23:12:47Z

Saga: Mention encryption, clarify channel volume, fix sample rate field

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-255, each filled only once per tick, this is
what, by absence, identifies empty channels. It is possible that actual PSM implementations will support less channels and crash if a file contains too many channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most cases. Some OMF 2097 tracks use a lower volume.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown (but apparently always $00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-31 is frequency (Sample rate)
19 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

== Encryption ==

CONVERT.EXE can produce "encrypted" PSM files with the /K command line switch. The encryption scheme is simple: It adds 1 to the first byte, 2 to the second, 3 to the third, and so until, for the entire file. It does not appear like any game made use of this feature, though.

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2016-06-07T23:19:12Z

Saga: Remove bogus info

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Games =
{{Game|Epic Pinball}}
{{Game|Extreme Pinball}}
{{Game|Jazz Jackrabbit}}
{{Game|One Must Fall}}
{{Game|Silverball}}
{{Game|Sinaria}}
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-255, each filled only once per tick, this is
what, by absence, identifies empty channels. It is possible that actual PSM implementations will support less channels and crash if a file contains too many channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like in S3M, sample headers are stored separately from the raw sample data.

A type of sample storage used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte, often making them compress better using general-purpose file compression tools. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2015-08-10T14:11:30Z

Saga: Actually PSM16 looks a lot like S3M internally, not MOD.

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Game1 = Epic Pinball
| Game2 = Extreme Pinball
| Game3 = Jazz Jackrabbit
| Game4 = One Must Fall
| Game5 = Silverball
| Game6 = Sinaria
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ScreamTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-255, each filled only once per tick, this is
what, by absence, identifies empty channels. It is possible that actual PSM implementations will support less channels and crash if a file contains too many channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like S3M, sample headers are stored separately from the raw sample data. Unlike S3M, the number of sample headers doesn't have to be 31, but rather is the number of samples in the header. Sample headers are usually stored at then end of the file, after the raw sample data.

A type of sample compression used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the new PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to new PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2014-07-13T14:31:50Z

Saga: New PSM format has subsongs. Change some other information to make more sense

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) / 1-32 (PSM16)
| NumTracks = unlimited (PSM) / 1 (PSM16)
| Game1 = Epic Pinball
| Game2 = Extreme Pinball
| Game3 = Jazz Jackrabbit
| Game4 = One Must Fall
| Game5 = Silverball
| Game6 = Sinaria
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are two file types that use the extension .PSM; they are both used by Epic Megagames' MASI sound system, but are used by different versions of the system. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ProTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to interpret PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.)

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-255, each filled only once per tick, this is
what, by absence, identifies empty channels. It is possible that actual PSM implementations will support less channels and crash if a file contains too many channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc... For example, in Extreme Pinball, all the different jingles and mission songs are stored as separate SONG chunks. It is up to the developer to find a clever way of managing / playing several sub songs.

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

This can also be used as a way to heuristically detect if the new version of the format is being used. Sinaria's song dates are: 800211, 940902, 940903, 940906, 940914, 941213

=== Order sub-segment ===

Orders describe how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (e.g. a chorus). without the pattern data having to be duplicated. There should be only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00. The purpose is unknown.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like S3M, sample headers are stored separately from the raw sample data. Unlike S3M, the number of sample headers doesn't have to be 31, but rather is the number of samples in the header. Sample headers are usually stored at then end of the file, after the raw sample data.

A type of sample compression used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

It is unknown which of the two PSM formats the following utilities support, unless stated otherwise.

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format documentation was found on Wotsit and written up by Levellass (this appears to be an official document from the MASI developer). More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2012-11-03T16:36:09Z

Saga: Channel count was wrong

{{Music Infobox
| Type = Tracked
| Instruments = PCM
| NumChannels = 1-256 (PSM) 1-32 (PSM16)
| NumTracks = 1
| Game1 = Epic Pinball
| Game2 = Extreme Pinball
| Game3 = Jazz Jackrabbit
| Game4 = One Must Fall
| Game5 = Silverball
| Game6 = Sinaria
}}
The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are currently two file types that use the extension .PSM; they seem to be related to a certain extent, though how is currently unknown. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ProTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to run PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.) Most PSM songs have no title.

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-255, each filled only once per tick, this is
what, by absence, identifies empty channels. It is possible that actual PSM implementations will support less channels and crash if a file contains too many channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song, as well as a lot of unimportant data that is no longer used. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc...

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

=== Order sub-segment ===

Orders are how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (E.g. a chorus.) without the pattern having to be repeated. There is usually only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-32
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like S3M, sample headers are stored separately from the raw sample data. Unlike S3M, the number of sample headers doesn't have to be 31, but rather is the number of samples in the header. Sample headers are usually stored at then end of the file, after the raw sample data.

A type of sample compression used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

It is unknown which of the two PSM formats the following utilities support, unless stated otherwise.

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format was reverse engineered by Wotsit and written up by Levellass. More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

ProTracker Studio Module

2012-04-24T16:10:57Z

Saga: Removed irrelevant information, added clarifications

The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are currently two file types that use the extension .PSM; they seem to be related to a certain extent, though how is currently unknown. The two formats are:

* PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
* PSM 16: Used by Silverball, an older version of the format which is closer to ProTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to run PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.) Most PSM songs have no title.

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-3, each filled only once per tick, this is
what, by absence, identifies empty channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-64 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song, as well as a lot of unimportant data that is no longer used. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc...

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

=== Order sub-segment ===

Orders are how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (E.g. a chorus.) without the pattern having to be repeated. There is usually only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. Filename of the original module (without extension)
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown (second byte could be default pan, but seems to be unused)
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use delta-encoded samples, something to make the file smaller when zipped. 'Deltas', convert a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It has the effect that if a single byte in the sample is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]], early versions of Epic Pinball and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the ProTracker MOD format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-31
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like S3M, sample headers are stored separately from the raw sample data. Unlike S3M, the number of sample headers doesn't have to be 31, but rather is the number of samples in the header. Sample headers are usually stored at then end of the file, after the raw sample data.

A type of sample compression used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

It is unknown which of the two PSM formats the following utilities support, unless stated otherwise.

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://openmpt.org/legacy_software ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The PSM16 format was reverse engineered by Wotsit and written up by Levellass. More info is needed.

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

[[Category:Music Files]]
[[Category:Jazz Jackrabbit]]
[[Category:File Formats]]

ProTracker Studio Module

2011-09-11T15:48:23Z

Saga: Format

The '''ProTracker Studio Module''' (PSM) file format is used for the music in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. The file format is named after ProTracker, an Amiga program, though this program was probably actually not used to write PSM files. One Must Fall's music was written in Multitracker, and the music for Jazz Jackrabbit, Epic Pinball and Extreme Pinball probably in Scream Tracker.

There are currently two file types that use the extension .PSM; they seem to be related to a certain extent, though how is currently unknown. The two formats are:

PSM New Format: Used by Jazz Jackrabbit, Epic Pinball, Extreme Pinball, One Must Fall, Sinaria (in this game with slight differences, see below), newest PSM format
PSM 16: Used by Silverball, an older version of the format which is closer to ProTracker-style modules.

The most common of the two PSM formats is the new format, and most programs that try to run PSM files will be expecting this. For example, ModPlug Player cannot open Silverball files as these are in the PSM 16 format.

= PSM New Format =

This format is used by [[:Category:Epic Megagames|Epic]] games in [[Jazz Jackrabbit]], [[Epic Pinball]], [[Extreme Pinball]], [[Silverball]], [[Sinaria]] and [[One Must Fall]]. It is notable for consisting of a number of segments (chunks) and sub segments. It bears the 4-byte signature 'PSM ' at the file start.

File structure:
Header
Pattern segment
Song segment
Samples

== Header ==

The file header is 12 bytes long:

File header:
0 4 ID 'PSM '; indicates file is PSM format
4 4 Size Filesize - 12
8 4 ID2 'FILE'; indicates start of file info

After the header, some chunks follow in IFF-style. You should not expect chunks to come up in the same order as they are described here. A good way to handle chunks is to read the 4-Byte ID and the 4-Byte size field first, then evaluate the ID and decide what to do next based on this ID. Note that the size field does not include the ID and itself; it only holds the size of the chunk ''content''.

== Title segment ==

This segment is optional, and one of the few segments that can be absent when playing PSM files in most programs. (Most programs expect all other segments to exist, even if they are not vital.) Most PSM songs have no title.

0 4 ID 'TITL'; indicates a title follows
4 4 Size Size of title as dword after this dword
8 ? Title Song title

== Song info segment ==

This segment seems to indicate the beginning of the song data and is not really relevant when parsing.

12 4 ID 'SDFT'; indicates start of format info
16 4 Size Size of next header as dword, (8)
20 8 Song 'MAINSONG'; indicates song type. No other song types are known.

== Patterns ==

Each pattern is stored in its own PBOD chunk. Note that there are two possible formats for this chunk; one is used in the "old" format (as used in Epic Pinball, Extreme Pinball, Jazz Jackrabbit, One Must Fall) and the other in the "new" format (as used in Sinaria)

Pattern segment:
0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy)
4 4 Size Length of pattern data as dword, after this dword
4 4 Size Same value again.

Pattern:
0 4/8 Number Pattern ID. See note below.
4 2 Row n Number of rows in ALL channels in pattern (64 usually, but can differ.) as word.
6 ? Data Contains pattern data as a number of rows of interlaced channels (12341234...)
''Usual'' settings is 64 rows of 4 channels. Epic Pinball has shorter patterns for example, but they also include a "break to row" command at the end of the pattern.

'''Note:''' In the old format, this starts with a 'P' and is followed by an integer number which is the pattern number, padded to 4 bytes with spaces. Caution: This number might or might not be zero-padded; In some files, the ID of the first pattern could be 'P0 ', but there are also files where it is 'P00 '!. In C/C++, you could use atoi() to parse this value. In the new format (Sinaria), This field is 8 bytes long instead of 4 bytes, and the first 4 bytes read "PATT", so the first pattern could be for example 'PATT0 '.

Pattern row channel entry:
? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four
values
+1 1 chan What channel this belongs to, 0-3, each filled only once per tick, this is
what, by absence, identifies empty channels.
+2 1 Note Pitch, $01 is C-1, etc... The octaves are aligned by 16, i.e. B-1 is $0C but the next note, C-2, is $10.
+3 1 Ins Instrument used, 0-31
+4 1 Vol Volume change to, 0-63 = 0-127; optional
+5 1 Effect Effect to use, volume slide, Portamanto...
+6 1 Eff Am Strength of effect, e.g amount of slide

Each row consists of a word giving the size of the row (Including the word) followed by the channel data. A channel is only included if it has data in it, but a totally empty row is still included. So an 'empty' row (Where none of the channels have data.) thus consists of just a word of value 2.

Each channel entry consists of between 3-7 bytes. The first byte is a flag that shows what data follows. (The first four bits indicate whether there are bytes for the following four variables; Note ($80), Instrument ($40), Volume ($20), Effect AND Effect magnitude ($10). Thus 5 bytes are represented by a combination of 4 possibilities.) The next byte identifies the channel (Since each channel may or may not be present.) starting at 0 for channel 1. The remaining 5 bytes may or may not be present and contain data for Note, Instrument(Sample) used, Volume change for channel, Effect and Effect magnitude.

There are several things to note about this; Effect and Effect magnitude MUST occur together. Sample numbers, like channels are numbered starting at 0, not 1. Magnitudes (For effect AND volume) are from 0-127, not 0-63 as in other formats.

=== Effect conversion ===

Note that this table is guaranteed to be correct; Most effects seem to be converted correctly, though. Note that these values are not correct for the PSM files that can be found in the game Sinaria. Leave out all divisions and it will be correct again.

PSM Command Param length S3M Command

Volume commands
1 1 Byte DxF - fine volside up
2 1 Byte Dx0 - volslide up
3 1 Byte DFx - fine volslide down
4 1 Byte D0x - volslide down

Portamento commands
B 1 Byte FFx - fine porta up (divide x by 4)
C 1 Byte Fxx - porta up (if x < 4, use FFx, else divide x by 4)
D 1 Byte EFx - fine porta down (divide x by 4)
E 1 Byte Exx - porta down (if x < 4, use EFx, else divide x by 4)
F 1 Byte Gxx - portamento (divide x by 4)
10 1 Byte S1x - glissando control
11 1 Byte Lx0 - tone porta + volslide up
12 1 Byte L0x - tone porta + volslide down

Vibrato
15 1 Byte Hxy - vibrato
16 1 Byte S3x - vibrato waveform
17 1 Byte K0x - vibrato + volslide up
18 1 Byte Kx0 - vibrato + volslide down

Tremolo
1F 1 Byte Rxy - tremolo
20 1 Byte S4x - tremolo waveform

Sample commands
29 3 Bytes Oxx - offset (only take the 2nd byte)
2A 1 Byte Q0x - retrigger
2B 1 Byte SCx - note cut
2C 1 Byte SDx - note delay

Position change
33 2 Bytes(?) Bxx - position jump (divide by 2)
34 1 Byte Cxx - break to row (divide by 2)
35 1 Byte SBx - pattern loop
36 1 Byte SEx - pattern delay

Speed change
3D 1 Byte Axx - set speed
3E 1 Byte Txx - set tempo

Misc. commands
47 1 Byte Jxy - arpeggio
48 1 Byte S2x - set finetune
49 1 Byte S8x - set balance

Effect interpretation is different in Sinaria's new format.

== Song segment ==

This segment contains most of the important data used to play the song, as well as a lot of unimportant data that is no longer used. It contains several sub-segments, each of the same format as a normal segment, but contained in the song segment. Note that there might be more than one song segment and thus, more than one order list, default speed, default tempo, etc...

Segment structure:
0 4 ID 'SONG' indicates start of song structure
4 4 Size Size of song structure, including all sub-segments
8 9 Type Type of song this is for; This is 'MAINSONG ' in almost all PSM files. Extreme Pinball has several SONG items with different types!
17 1 Comp Compression, for PSM = 1 (Uncompressed)
18 1 Chan Number of channels, usually, but not always, 4

=== Date sub-segment ===

This dates the file and is used by some programs. It is usually the first sub-segment.

0 4 ID 'DATE' indicates date data
4 4 Size Size of date segment (6)
8 6 Date Date as text, YYMMDD

=== Order sub-segment ===

Orders are how patterns are arranged in the song. This allows the same pattern of instruments to be played more than once in a song (E.g. a chorus.) without the pattern having to be repeated. There is usually only one order. This section also contains basic song information. It usually follows the date sub-segment.

0 4 ID 'OPLH' indicates start of pattern placement order
4 4 Size Size of order segment
8 2 Cnt. Number of following chunks

Now, the following chunks may follow until the end of the "OPLH" chunk is reached. Every chunk is identified by the first byte:
* $00 (1 Byte): End (Nothing follows)
* $01 (5/9 Bytes): Order list item follows (e.g. "P0 ", "P12 " in old format or "PATT0 " in new format, see above) - join those to get the complete order list.
* $04 (3 Bytes): This 16-bit value indicates the "restart chunk". If the end of the subsong is reached, it will jump back to this chunk. In many cases, this would be 4th chunk (no 3rd chunk, as the chunk index is starting at 0!), which is a panning index in most PSMs - So you would just go to the nearest order list item that's following this chunk. However, this can also point to a valid order list chunk.
* $07 (2 Bytes): Next byte is default speed for this subtune
* $08 (2 Bytes): Next byte is default tempo for this subtune
* $0C (7 Bytes): Sample map table(?): This chunk is always $0C $00 $FF $00 $00 $01 $00.
* $0D (4 Bytes): Channel panning index. Next byte is channel number (Start at 0), then initial pan ($00 ... $FF) and a byte follow. The byte seems to tell what to do with the previous pan position (0 - use it, 2 - ignore it, make this channel surround, 4 - set to center).
* $0E (3 Bytes): Channel volume index. Next byte is channel number (Start at 0), then volume ($00 ... $FF). $FF in most (all?) cases.

=== Pattern list ===

This is simply a list of all the patterns used in the file. You do not really need to parse this, it seems to be a purely informational chunk.

0 4 ID 'PATT' indicates start of pattern list
4 4 Size Size of pattern list after this
8 4 Size Same as above
12 4x Pat An ordered list 'P0 ', 'P1 '... for all patterns in the file, each entry 4 bytes

=== Sample list sub-segment ===

Similar to the above, this is a list of all the samples used in the file. It is usually the last sub-segment in the song segment and you do not really need to parse this.

0 4 ID 'DSAM'; indicates start of sample list, used to say what samples are 'full'
Any samples not on this list will be ignored, even if they have data
4 4 Size Size of list after this
8 4 Size Same value as above
12 15x Entry Sample entries, one for each sample in the file, each entry 15 bytes

Sample entry:
0 8 Format Sample format, padded with spaces (END, RAG2...) This is important to some programs
8 4 ID 'I0 ', 'I1 '... the sample ID ('I' means 'Instrument'). Again, be sure to accept both 'I0 ' and 'I00 '!
12 2 Num The sample number, 0,1,2... for the sample

== Samples ==

Samples are the raw sound data that makes up the instruments on the song. The actual format depends on the sample format. For example, XM2 is identical to wave format data, but signed, END is 'delta' format and RAG2 may be plain wave data. Samples have information in their headers which allows data to be played at different pitches (Speeds.) and to loop from and to various points in the data. This is by far the largest part of the file, since the raw data takes up so much space.

There are several sample formats, which can be used by other modules than PSM. The following is the format of the 'END' sample. The XM2 format sample has a header that is 7 bytes longer (Padded with nulls at the end.) and is labeled 'Ix ' instead of 'INSx' Most sample formats are poorly known.

0 4 ID 'DSMP' indicates start of sample
4 4 Size Size of following sample as 'DSMP' + dword from end of word
8 9 Flags If highest bit is set, then sample is looped
9 8 Songn. This seems to be a song name or something
17 4 INSx Last digit of sample (Instrument) number, 0-9; with 31 instruments possible
Only last digit is shown. E.g 1st, 11th, 21st and 31st sample is 'INS0'
21 33 Name Defines the instrument name or file, usually a .st or line of text
54 51 Header Sample parameters (Can also 58 bytes long, padded with nuls)
Byte 1-6 are unknown ($00 $00 $00 $00 $00 $FF)
Bytes 7-8 is instrument number
Bytes 9-12 are sample length
Bytes 13-16 are loop start
Bytes 17-20 are loop end (all $FF means at end of sample)
Bytes 21-22 are unknown
Byte 23 is default volume
Bytes 24-27 are unknwon
Bytes 28-29 is frequency (Sample rate)
21 $00-bytes follow
105 ? Data Music data in 8-bit mono format

The sample header is slightly different in Sinaria's new format: INSx is 8 bytes long (like the PATT IDs), and the last 21 $00-bytes are just 16 bytes.

The PSM new format, along with the PSM 16 format use a form of 'compression' (Actually something to make the file smaller when zipped.) is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. It is used in END format samples and has the effect that if a single byte is changed, the entire sample will be degraded. This use of deltas varies slightly from that of the PSM 16. The 'start value' of the string is assumed to be $80 (128) and the first byte will thus turn this into the first desired value, the second delta converts the first value to the second, and so on.) All deltas are signed, 1-byte values, but loop (Thus 10 - 20 = -10 can also be considered as 10 + 236 = 246). An example of this is as follows:

RAW: (128) 64 66 67 68 69 70 71 73 75 77 76
DELTAS: -64 0 2 1 1 1 1 1 2 2 2 -1

= PSM 16 =

This is the format used in [[Silverball]] and possibly other games. The designation 'Protracker Studio 16 format' was given to it by the only reliable source of information on this format, and may not be the official designation. Earlier versions of this format may also exist, but if so, they have not been identified as yet.

The format bears many similarities to the S3M format; the file is set out roughly the same, patterns and samples are similar, indeed, near identical and the functionality is similar. It also shows many similarities to the PSM Old format and retains vestiges of Amiga compatibility.

This format can be identified by its signature 'PSMþ', though files may lack this and still function.

File structure:
Header
Order
Pan segment
Pattern segment
Sample data
Sample headers

== Header ==

0 4 Sig Signature, 'PSMþ'
4 59 Title Song title, padded with nulls. Unlike other formats, this must also be terminated
with a null byte. (It sometimes is not terminated, though.)
62 1 This must be $1A to end the song name, like in S3M format.
64 1 Type Song type, First bit: 0 - Module (w/samp.), 1 - Song (w/o samples)
Second bit: 0 - 3 octave Protracker, 1 - 5 octave; remaining bits reserved.
65 1 PSM v PSM format version, $10 for this format (Hence the name PSM 16) = 'v1.00'.
Sometimes, this is also $01, but there's no difference in the format itself.
66 1 Patt v Pattern version, 0 or 1. 0 means the pattern is stored in the module are in the 32
channel file format. A 1 signifies the patterns as being stored as a 255
channel format. (I have not found any PSM16 modules that have this format.)
67 1 Speed Song speed
68 1 BPM Beats per minute, the default Amiga BPM value. (The only reason that the Amiga BPM
format is still followed here is that it allows more control over the final hz value.)
Range: 32 to 255.
69 1 Vol Master volume of song, 0-255
70 2 Len Song length, 0-255. The number of patterns to play in the song, in total.
72 2 Ordlen The number of orders actually stored at the order offset. It was hoped that the
PSM 16 format would allow multiple orders, so this would be the length of the first
order. This doesn't appea to ahve happened, and is usually the same as the previous value.
74 2 Patnum Number of patterns in the song. 1-255
76 2 Sampnum Number of samples and 'sample structures' in song, 1-255
78 2 NCIS Number of channels in song to PLAY. 1-32.
80 2 NCP Number of Channels to Process; describes the MAXIMUM number of channels to process.
As an example, when converting 669 files, NCP = 9 because some track information
is in Channel 8, but the Number of Channels to Play was set to 8, (Channel numbers
to play from 0 to 7.) 1-32
82 4 Ordoff Location of order in header
86 4 Panoff Location of pan positions in header
90 4 Patoff Location of patterns in header
94 4 Sampoff Location of sample headers in header
98 4 Commoff Location of comments in header
102 4 Patsiz Total pattern size; the total size of all the patterns loaded from the pattern offset.
106 40 Fillers 10 fillers, to be used for any possible expansions.

It is important to notice that the offsets point to the first byte '''after''' the chunk ID, i.e. "Ordoff" points to the first byte after "PORD".

== Order and Pan positions ==

These are two separate segments, pointed to in the header. They may be anywhere, but usually follow the header sometimes after an amount of blank space. They are often padded with blank space. They are basically lists.

Order: This segment is pointed to in the header, and sets the PSM 16 format apart. The PSM 16 format was designed to be much more like the MOD format, allowing game designers to set flags to switch from one set of patterns to another, in effect allowing one file to contain more than one song. (For example a boss flag might make the music switch from a clam patterns 1-4 to a racy and dangerous patterns 5-7.)

0 4 Sig Signature, not needed, 'PORD'
4 ? Ords Pattern numbers and order. There will be [Ordlen] bytes of patterns
? 2 Lang Order language, not implemented, so left blank.

Pan Positions:

0 4 Sig 'PPAN'
4 12 Pan Pan positions; empty positions left blank.

== Patterns ==

0 2 Size Size of pattern, including these bytes
2 1 Len Length of pattern, in rows. Max length is 64 rows.
3 1 Chan Number of channels in pattern, 1-31
4 ? Data Pattern data

This is similar to the previous two segments, except actual pattern data is stored here. Patterns are very similar to the S3M format, and consist of y rows of x channels. Each row contains a number of channels and ends with a byte of value 0. Each channel is between 2-6+ bytes long. A totally empty channel is represented by a single byte of value 0.

Each channel starts with a flag byte, abcddddd, where a,b and c indicate whether there is a note and instrument, volume or special effect and effect magnitude in the following data, and dddd is the channel number (0-31, used since a given channel may or may not be present in a row.)

The usual maximum length of a channel entry is 6 bytes (1 flag byte, 2 Note AND instrument bytes, 1 volume byte and two Effect and Effect magnitude bytes.) Thus Note&ins\Eff&Eff mag must always occur together.

Like S3M, volume range is 0-64, as is special magnitude. However, special effects range from 0-255, like PSM New Format.

=== Effects conversion ===

### Co MOD Description Arguments
--- -- --- ----------- ---------
Volume Commands
1 A1 EA Fine Volume Slide Up B xx xx=speed
2 A2 A Volume Slide Up B xx xx=speed
3 A3 EB Fine Volume Slide Down B xx xx=speed
4 A4 A Volume Slide Down B xx xx=speed

Portamento Commands
10 B0 E1 Fine Porta Up B xx xx=speed
11 B1 1 Portamento Up B xx xx=speed
12 B2 E2 Fine Porta Down B xx xx=speed
13 B3 2 Portamento Down B xx xx=speed
14 B4 3 Tone Portamento B xx xx=speed
15 B5 E3 Set Glissando Control B xx xx=0 - Off, 1 - On
16 B6 5 Tone Port+Vol Slide Up B xx xx=speed
17 B7 5 Tone Port+Vol Slide Down B xx xx=speed

Vibrato Commands
20 C0 4 Vibrato B xy x=speed, y=depth
21 C1 E4 Set Vibrato Waveform B x x=Waveform
21 C2 6 Vibrato+Vol Slide Up B xx xx=speed
22 C3 6 Vibrato+Vol Slide Down B xx xx=speed

Tremolo Commands
30 D0 7 Tremolo B xy x=speed, y=depth
31 D1 E7 Set Tremolo Control B x x=Waveform

Sample Commands
40 E0 9 Sample Offset 3B Position for offset change (0-1,048,575)
41 E1 E9 Retrig Note B xx xx=tick to retrigger sample
42 E2 EC Note Cut B xx xx=tick to cut note
43 E3 ED Note Delay B xx xx=ticks to delay note

Pos. Change Commands
50 F0 B Position Jump B xx xx=order position
51 F1 D Pattern Break B xx Skip to line xx in next pattern
52 F2 E6 Jump Loop B xx xx=number of loops 0 Set
53 F3 EE Pattern Delay B xx xx=notes to delay pattern

Speed Change Cmds
60 G0 F Set Regular Speed B xx xx=speed
61 G1 F Set BPM B xx xx=BPM (32-255)

Misc. Commands
70 H0 0 Arpeggio B xy x=semitone #1, y=semitone #2
71 H1 E5 Set Finetune B xx xx=finetune
72 H2 Set Balance B xx xx=Balance (0-15)

== Samples ==

Sample segment
0 4 ID 'PSAM' (Psm SAMple)
4 ? Data Sample data

Sample header segment
0 4 ID 'PSAH' (Psm SAmple Header)
4 ? Data Sample headers

Sample header
0 13 Name Sample filename, terminated with a null.
13 24 Desc Sample description or comments.
37 4 Offs Location of raw sample data in file
43 4 Mem This is the physical offset in RAM/DRAM of the sample. (Often blank.)
45 2 Num Sample number, 1-255
47 1 Type Sample type: (In some games left blank; if this is the case then the
sample format is END, as used in most PSM New Format files)
Bit 0: 0 - Digital, 1 - Synthesized
Bit 2: 0 - 8-bit, 1 - 16-bit
Bit 3: 0 - Signed, 1 - Unsigned
Bit 4: 0 - Deltas, 1 - Raw
Bit 5: 0 - Loop normally, 1 - Bidirectional
Bit 6: 1 - Gravis patch (unsupported)
Bit 7: 0 - No loop, 1 - Loop sample
48 4 Len Sample length, in bytes.
52 4 Rep st Sample repeat start; if sample loops, the loop starts here.
56 4 Rep fn Sample repeat end, if sample loops, it ends here. If this is less than the sample
repeat start, the sample loops backwards.
60 1 Tune Fine tune; range 0-15, Tune 0-7 = 0-7; tune -1 - -8 = 8-15
61 1 Vol Sample volume, 0-64
62 2 Freq This is the frequency for the sample at a C of Octave 2.
Typical values are 8,000 hz to 8,448 hz.

Like S3M, sample headers are stored separately from the raw sample data. Unlike S3M, the number of sample headers doesn't have to be 31, but rather is the number of samples in the header. Sample headers are usually stored at then end of the file, after the raw sample data.

A type of sample compression used often, like in the PSM New Format is 'Deltas', which converts a string of bytes into another by storing the DIFFERENCE between a byte and the previous byte. Thus:

RAW: 64 66 67 68 69 70 71 73 75 77 76
DELTAS: 11 64 2 1 1 1 1 1 2 2 2 -1

This is done to make files more compressible, but doesn't seem to be used much.

= Utilities =

It is unknown which of the three PSM formats the following utilities support, unless stated otherwise.

* Download [http://www.shikadi.net/files/psm2scrm.zip psm2scrm.zip] - DOS program to convert .PSM songs into ScreamTracker .S3M format, suitable for playing in your favourite tracker/module player. Works only with PSM New Format and is not nearly as accurate as OpenMPT.
* [http://www.modplug.com ModPlug Tracker] and OpenMPT 1.17 can play the files and save them as S3M. More complex songs don't load correctly though. Works only with new format.
* [http://openmpt.org OpenMPT] 1.18 and newer can load all PSM and PSM16 files.
* [http://kode54.foobar2000.org/ foo_dumb] is a plugin for various module formats for the Foobar2k media player. It supports both PSM16 and PSM and is similar to OpenMPT in playback quality.
* [http://ftp.lanet.lv/ftp/mirror/x2ftp/msdos/programming/mxinfo/epictest.zip EPICTEST] is a demonstration of the Epic Megagames MASI. It contains CONVERT.EXE which can be used to convert modules to the PSM format.
* [http://www.jazz2online.com/J2Ov2/downloads/info.php?levelID=5471#29435] JJ1MOD can convert S3M files to PSM, though often with errors (Though these are usually only detectable with older programs such as game executables.) It is currently the only utility able to do this, and works only with New Format.

= Notes =

The New PSM format was reverse engineered by Levellord and tidied up by Levellass. It is possible there may be minor errors in the sample format information, especially since this is poorly documented.
Some format definitions have been updated and corrected by Johannes Schultz of the OpenMPT development team.

The Silverball PSM format was reverse engineered by Wotsit and written up by Levellass. More info is needed.

The Old PSM format was obtained from [http://www.silent-dreams.de/handbook.html#ProTracker%20song&module%20format ProTracker song & module format]

In all formats the following table shows how note bytes are converted into actual notes: (PSM new format has the widest range, 0-255)

+---------+---------+---------+---------+---------+
| C-0 0 | C-1 12 | C-2 24 | C-3 36 | C-4 48 |
| C#0 1 | C#1 13 | C#2 25 | C#3 37 | C#4 49 |
| D-0 2 | D-1 14 | D-2 26 | D-3 38 | D-4 50 |
| D#0 3 | D#1 15 | D#2 27 | D#3 39 | D#4 51 |
| E-0 4 | E-1 16 | E-2 28 | E-3 40 | E-4 52 |
| F-0 5 | F-1 17 | F-2 29 | F-3 41 | F-4 53 |
| F#0 6 | F#1 18 | F#2 30 | F#3 42 | F#4 54 |
| G-0 7 | G-1 19 | G-2 31 | G-3 43 | G-4 55 |
| G#0 8 | G#1 20 | G#2 32 | G#3 44 | G#4 56 |
| A-0 9 | A-1 21 | A-2 33 | A-3 45 | A-4 57 |
| A#0 10 | A#1 22 | A#2 34 | A#3 46 | A#4 58 |
| B-0 11 | B-1 23 | B-2 35 | B-3 47 | B-4 59 |
+---------+---------+---------+---------+---------+

It should be noted that all PSM formats are severely limited compared to other module formats, most applications limited them to four channels, the note range is limited and the range of effects is severely curtailed.

[[Category:Music Files]]
[[Category:Jazz Jackrabbit]]
[[Category:File Formats]]