+==========================================================================================+ |Jazz Jackrabbit Music (ProTracker Stuido Module) format: | +==========================================================================================+ The ProTracker Studio Module (PSM) file format is used for the music in Jazz Jackrabbit Epic Pinball and One Must Fall. It is a module music format initially believed to be similar to Scream 3 Tracker (S3M) format, but reccently discovered to be formatted quite differently. The files are created using ProTracker, an Amiga program. OpenMPT can open the files, but not save them. Modplug tracker can play the files and save them as S3M. There is a second, unrelated file format known as PSM, used in [[Silverball] and a few other games. This has been documented elsewhere and is totally unrelated to the PSM format used in early Epic games. It can be identified because it stores the song name at byte 4 instead of the size, and the song itle may be 59 characters long. All conversions to S3M involve (Usually negligible.) data loss that is most noticeable with the high quality Epic Pinball music. The structure is quite complex and is as follows, a file header followed by 'patterns' a song structure (Order) segment and then samples. (Sound data) ------------------------------------------------------------------------------- FILE STRUCTURE: Header Patterns ... .. . Song segment Date segment: Order segment Pattern list ... .. . Sample list ... .. . Samples ... .. . ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- File header: 0 4 ID 'PSM '; indicates file is PSM format 4 4 Size Filesize - 11 8 4 ID2 'FILE'; indicates start of file info 12 ? Title Optional title segment ? 4 ID3 'SDFT'; indicates start of format info +4 4 Size Size of next header as dword, usually 8 +8 8 Song 'MAINSONG'; indicates song type ------------------------------------------------ Title segment: 0 4 ID 'TITL'; indicates a title follows 4 4 Size Size of title as dword after dword 8 ? Title Song title ------------------------------------------------ ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Pattern: 0 4 ID 'PBOD'; indicates a pattern follows (Pattern BODy) 4 4 Size Length of pattern data as dword, after dword 8 4 Size Same value as above, unknown function 12 4 Number 'Px' padded with spaces. Indicates pattern number (Start = 'P0 ') 16 2 Row n Number of rows in ALL channels in pattern (64) as word 18 ? Rows Contains 64 rows of interleaved channels (12341234...) Each row 7x + 2 bytes in length, if unpacked, total size is 64*30 = 1'920 bytes ------------------------------------------------ Pattern row: ? 2 Size Size of row +2 7x Chan -Consist of 1-4 channel entries, empty channels aren't included. -A channel entry is empty if nothing happens to it during the row -A totally empty row consists just of a size of 2 bytes ----------------------------- Pattern row channel entry: ? 1 Fill Convert this byte value into binary; (240 -> 11110000), the first four values indicate whether there are bytes for the following four variables: Instrument, Note, Volume, Effect AND Effect magnitude. Thus 5 bytes are represented by a combination of 4 possibilities. +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... +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, Portamanteu... +6 1 Eff Am Strength of effect / 2, e.g amount of slide ----------------------------- ------------------------------------------------ ------------------------------------------------------------------------------- The song segment defines the song type and is used by some programs to define how to play the file. However this is largely redundant since only two types of PSM now exist, and the second is rather rare. ------------------------------------------------------------------------------- Song segment: 0 4 ID 'SONG' indicates start of song structure 4 4 Size Size of song structure, including all other IDs 8 9 Type Type of song this is for; For PSM, 'MAINSONG ' only 17 1 Comp Compression, for PSM = 1 (Uncompressed) 18 1 Chan Number of channels, usually, but not always, 4 ------------------------------------------------------------------------------- The date segment the file and is used by some programs. ------------------------------------------------------------------------------- Date segment: 0 4 ID 'DATE' indicates date data 4 4 Size Size of date info 8 6 Date Date as text, YYMMDD ------------------------------------------------------------------------------- Orders are how patterns are arranged in the song. There is usually only one order. ------------------------------------------------------------------------------- Order segment: 0 4 ID 'OLPH' indicates start of pattern placement order 4 4 Size Size of pattern placement 8 29 ??? Data as follows: (This seems to be basic song information) 0A 00 0C 00 FF 00 00 01 00 0D 00 C1 02 0D 01 3F 04 0D 02 3F 04 0D 03 C1 0x 07 0x 08 7D -Byte 27 is song speed -Byte 29 is bpm? 37 5x Pat -Pattern entries (Order of patterns in song, each entry 5 bytes) ? 4 End $03 $04, seems to indicate end of pattern entries. ------------------------------------------------ Pattern entry: 0 1 Start Set at $01, to indicate a pattern 1 4 ID 'P(x)' padded with spaces, the pattern number, often starts with 'P0 ' ------------------------------------------------ ------------------------------------------------------------------------------- The pattern list is simply a list of all the patterns used in the file. ------------------------------------------------------------------------------- Pattern list: 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 ------------------------------------------------------------------------------- Similar to the above, the sample list is a list of all the samples used in the file. ------------------------------------------------------------------------------- Sample list: 8 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...) 8 4 ID 'I0 ', 'I1 '... the sample ID 12 2 Num The sample number, 0,1,2... for the sample ------------------------------------------------ ------------------------------------------------------------------------------- Samples are the raw sound data that makes up the instruments on the song. The data is similar to wave format, but signed, and is variously warped, looped and shifted to make up an array of instruments in the song. this is by far the largest part of the file, since the raw data takes up so much space. The XM2 format sample has a header that is 7 bytes longer (Padded with nulls) and is labelled 'Ix ' instead of 'INSx' ------------------------------------------------------------------------------- Samples: 0 4 ID 'DSMP' indicates start of sample 4 4 Size Size of following sample as 'DSMP' + dword from end of word 8 9 Format Sample format (END, RAG2, XM2...) 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 6 is $FF Bytes 7-8 is instrument number Bytes 9-12 is loop start location in data Byte 13 is loop (1 = loop) Bytes 17-20 is loop end location in data; all $FF means at end of sample Byte 23 is default volume Bytes 28-29 is frequency (Sample rate) 105 ? Data Music data in 8-bit mono scream tracker (st) format -------------------------------------------------------------------------------