ModdingWiki - User contributions [en-gb]

Apogee Sound System Timbre Format

2017-07-25T07:09:19Z

Binarymaster:

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song. Files of this format are has <tt>.tmb</tt> extension.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

IBK Format

2017-07-25T07:08:46Z

Binarymaster: Small fixes

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 128
| Names = Yes, 8 chars
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|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
|-
|[[UINT8]]||iPercVoc||N/A||Percussion voice mode: 0 is melodic, 6 - Bass Drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbal, 10 - HiHat
|-
|[[INT8]]||iTranspos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||iDPitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercVoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = Yes
| notes = Instrument editor using IBK as its primary format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

DSIK Module Format

2017-06-24T07:50:12Z

Binarymaster: /* Tools */ correct entry

{{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}}
}}

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
|-
| 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).

{{TODO|Commands are unknown but are presumed very similar to .mod}} Effect 0x0F is used to set the tempo in some [[Trugg]] songs. If the value is small it is a new ''speed'' value, if it is large then it is a new ''tempo'' value.

=== 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]]

SOP Format

2017-02-27T18:07:04Z

Binarymaster: Latest updates

{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Comment, Instrument names
| Games = None
}}

The '''SOP Format''' was created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (normally 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (normally 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File-name / short-name, null-terminated
|-
| <tt>char[31]</tt> || title || Song-title, null-terminated
|-
| <tt>UINT8</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || tickBeat || Number of ticks-per-beat
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats-per-measure (normally 4)
|-
| <tt>UINT8</tt> || basicTempo || Song-tempo, in beats-per-minute (normally 120)
|-
| <tt>char[13]</tt> || comment || Comment string, unused
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT8</tt> || nInsts || Number of instruments
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

The header has a fixed size of 76 bytes, then it is followed by data-structure.

=== Data structure ===

The data-structure's size is dynamic, therefore, it varies depending upon the number of tracks and instruments:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of the data-structure is described below:

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
The header is followed by the instrument-block. An instrument-structure is repeated <tt>nInsts</tt> times:

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument-name / short-name
|-
| <tt>char[19]</tt> || longName || Long instrument-name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

An instrument's data-size varies depending upon the instrument's type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

The actual instrument-data is merely just a dump of the OPL registers:

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data Type!!Name!!OPL Base Register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and Bass Drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave-select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data Type!!Name!!OPL Base Register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave-select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave-select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave-select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave-select
|}

=== Sequenced tracks ===

The instrument-block is followed by all sequenced tracks, which contain the music's events:

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track's data-size, in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta-ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure varies depending upon the event-code value:

{|class="wikitable"
! Event Code !! Description !! Event Structure
|-
| <center>1</center> || Special Event || <tt>UINT8</tt> value
|-
| <center>2</center> || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| <center>4</center> || Change Volume || <tt>UINT8</tt> volume
|-
| <center>5</center> || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| <center>6</center> || Instrument Change || <tt>UINT8</tt> number
|-
| <center>7</center> || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event has no effect on normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current note plus the frequency of the next note in octave (or previous note, if value is negative). Its combined value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, and if the next note frequency is 163, then, the actual output frequency can be calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in a SOP file is the control-track. It is used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control-events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control-track data-size, in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control-track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta-ticks (change position)
|-
| <tt>UINT8</tt> || event || Control-event code
|-
| <tt>SOP_CVAL</tt> || value || Control-event structure
|}

<tt>SOP_CVAL</tt> structure varies depending upon the control-event code value:

{|class="wikitable"
! Event Code !! Description !! Event Structure
|-
| <center>3</center> || Change Tempo || <tt>UINT8</tt> bpm
|-
| <center>8</center> || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it was not set before, then, it defaults to the <tt>basicTempo</tt> value, however, the official Note editor overrides that default value with 120.

The frequency is calculated with this formula:

frequency = bpm * tickBeat / 60

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{FileFormatTool
| Name = SOP Play
| Platform = Windows 9x
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Uses direct output to OPL chip
}}
{{FileFormatTool
| Name = Testing SOP
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Open-source player
}}
{{FileFormatTool
| Name = Grassman software IMS/ROL/SOP Player
| Platform = Windows/Winamp
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Uses emulated output
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-28T12:52:38Z

Binarymaster: Grammar fixes

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Comment, Instrument names
| Games = None
}}

The '''SOP Format''' was created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (normally 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (normally 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File-name / short-name, null-terminated
|-
| <tt>char[31]</tt> || title || Song-title, null-terminated
|-
| <tt>UINT8</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || tickBeat || Number of ticks-per-beat
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats-per-measure (normally 4)
|-
| <tt>UINT8</tt> || basicTempo || Song-tempo, in beats-per-minute (normally 120)
|-
| <tt>char[13]</tt> || comment || Comment string, unused
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT8</tt> || nInsts || Number of instruments
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

The header has a fixed size of 76 bytes, then it is followed by data-structure.

=== Data structure ===

The data-structure's size is dynamic, therefore, it varies depending upon the number of tracks and instruments:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of the data-structure is described below:

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
The header is followed by the instrument-block. An instrument-structure is repeated <tt>nInsts</tt> times:

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument-name / short-name
|-
| <tt>char[19]</tt> || longName || Long instrument-name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

An instrument's data-size varies depending upon the instrument's type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

The actual instrument-data is merely just a dump of the OPL registers:

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data Type!!Name!!OPL Base Register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and Bass Drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave-select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data Type!!Name!!OPL Base Register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave-select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave-select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave-select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave-select
|}

=== Sequenced tracks ===

The instrument-block is followed by all sequenced tracks, which contain the music's events:

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track's data-size, in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta-ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure varies depending upon the event-code value:

{|class="wikitable"
! Event Code !! Description !! Event Structure
|-
| <center>1</center> || Special Event || <tt>UINT8</tt> value
|-
| <center>2</center> || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| <center>4</center> || Change Volume || <tt>UINT8</tt> volume
|-
| <center>5</center> || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| <center>6</center> || Instrument Change || <tt>UINT8</tt> number
|-
| <center>7</center> || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event has no effect on normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the pending sound. Its combined value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, and if the pending frequency is 163, then, the actual output frequency can be calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in a SOP file is the control-track. It is used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control-events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control-track data-size, in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control-track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data Type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta-ticks (change position)
|-
| <tt>UINT8</tt> || event || Control-event code
|-
| <tt>SOP_CVAL</tt> || value || Control-event structure
|}

<tt>SOP_CVAL</tt> structure varies depending upon the control-event code value:

{|class="wikitable"
! Event Code !! Description !! Event Structure
|-
| <center>3</center> || Change Tempo || <tt>UINT8</tt> tempo
|-
| <center>8</center> || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it was not set before, then, it defaults to the <tt>basicTempo</tt> value, however, the official Note editor overrides that default value with 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{FileFormatTool
| Name = SOP Play
| Platform = Windows 9x
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Uses direct output to OPL chip
}}
{{FileFormatTool
| Name = Testing SOP
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Open-source player
}}
{{FileFormatTool
| Name = Grassman software IMS/ROL/SOP Player
| Platform = Windows/Winamp
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Uses emulated output
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-13T22:21:28Z

Binarymaster: /* Header */ update nInsts

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Comment, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>UINT8</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT8</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>char[13]</tt> || comment || Comment string, unused
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT8</tt> || nInsts || Number of instruments
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however official Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T18:42:09Z

Binarymaster: /* Header */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Comment, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>UINT8</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT8</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>char[13]</tt> || comment || Comment string, unused
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>[[UINT16LE]]</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however official Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T18:26:23Z

Binarymaster: /* Header */ comment string

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Comment, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT8</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || padding || Unused, must be zero
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT8</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>char[13]</tt> || comment || Comment string, unused
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however official Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T13:04:01Z

Binarymaster: /* Header */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>BYTE[12]</tt> || unknown || {{TODO|Unknown values}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however official Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T11:24:44Z

Binarymaster: /* Change Tempo */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however official Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = tempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T11:23:18Z

Binarymaster: /* Change Tempo */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

This event updates the tempo value. If it wasn't set before, it comes from <tt>basicTempo</tt> value, however Note editor overrides the default value to 120.

The frequency is calculated with this formula {{TODO|check it later}}:

frequency = basicTempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T11:18:01Z

Binarymaster: /* Change Tempo */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || basicTempo || Song tempo, in beats-per-minute (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo comes from <tt>basicTempo</tt> value, but the Note editor overrides it to 120. The frequency is calculated with this formula {{TODO|check it later}}:

frequency = basicTempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T10:56:36Z

Binarymaster: /* Change Tempo */ update from research

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || pageKey || Page key value / control view (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 120. The frequency is calculated with this formula {{TODO|check it later}}:

frequency = basicTempo * tickBeat

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T10:40:18Z

Binarymaster: /* Header */ reveal more values

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure (usually 4)
|-
| <tt>UINT16LE</tt> || pageKey || Page key value / control view (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 255. The frequency is calculated with this formula:

freq = 298295 / (tempo / 100)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T10:23:30Z

Binarymaster: /* File format */ update header

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 4)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 0)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

Header have fixed size of 76 bytes. Then it's followed by data structure.

=== Data structure ===

Data structure size is dynamic and depending on number of tracks and instruments.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

Each section of data structure is described below.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 255. The frequency is calculated with this formula:

freq = 298295 / (tempo / 100)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T09:24:56Z

Binarymaster: Update structure names

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 4)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 0)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes (see below)
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_STRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRK</tt> || ctrlTrack || Control track
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_STRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVNT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVNT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRK</tt> structure is similar to <tt>SOP_STRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CEVT[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CEVT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 255. The frequency is calculated with this formula:

freq = 298295 / (tempo / 100)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-11T09:19:28Z

Binarymaster: /* Header */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 4)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 120)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}} (usually 0)
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>BYTE</tt> || unknown || {{TODO|Unknown value}}
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes (see below)
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_TRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRL</tt> || ctrlTrack || Control track
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_TRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVENT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVENT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRL</tt> structure is similar to <tt>SOP_TRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CTEV[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CTEV</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 255. The frequency is calculated with this formula:

freq = 298295 / (tempo / 100)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-09T23:57:11Z

Binarymaster: /* Control track */

{{NeedMoreInfo}}
{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3)
| NumTracks = 20
| NumPatterns = 1
| NumOrders = 0
| Tags = File name, Title, Instrument names
| Games = None
}}

The '''SOP Format''' is created by Lee Ho Bum (sopepos) for the '''Note''' OPL3 music sequencer.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[char]][7]</tt> || signature || Header signature (must be "<tt>sopepos</tt>")
|-
| <tt>[[UINT8]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT8</tt> || minorVersion || Minor version number (usually 1)
|-
| <tt>[[BYTE]]</tt> || padding || Unused, must be zero
|-
| <tt>char[13]</tt> || fileName || File name / short name, null terminated
|-
| <tt>char[31]</tt> || title || Song title, null terminated
|-
| <tt>[[UINT16LE]]</tt> || percussive || OPL rhythm mode: 0 = melodic, 1 = percussive
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>BYTE</tt> || unknown || Unknown value (usually 4)
|-
| <tt>BYTE</tt> || unknown || Unknown value (usually 120)
|-
| <tt>BYTE</tt> || unknown || Unknown value (usually 0)
|-
| <tt>BYTE[3]</tt> || unknown || Unknown value
|-
| <tt>UINT8</tt> || beatMeasure || Number of beats per measure
|-
| <tt>BYTE[8]</tt> || unknown || Unknown values
|-
| <tt>UINT8</tt> || nTracks || Number of tracks
|-
| <tt>UINT16LE</tt> || nInsts || Number of instruments
|-
| <tt>BYTE[nTracks]</tt> || chanMode || Channel modes
|-
| <tt>SOP_INST[nInsts]</tt> || insts || Instruments
|-
| <tt>SOP_TRK[nTracks]</tt> || tracks || Sequenced tracks
|-
| <tt>SOP_CTRL</tt> || ctrlTrack || Control track
|}

The only known version of this format is 0.1.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff.

=== Channel modes ===

{|class="wikitable"
! Value !! Description
|-
| <tt>0x00</tt> || Unused channel
|-
| <tt>0x01</tt> || YMF-262M 4OP Mode
|-
| <tt>0x02</tt> || YM-3812 2OP Mode
|}

=== Instruments ===
Header is followed by instruments block. Instrument structures are repeated <tt>nInsts</tt> times.

<tt>SOP_INST</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT8</tt> || instType || Instrument type
|-
| <tt>char[8]</tt> || shortName || Bank instrument name / short name
|-
| <tt>char[19]</tt> || longName || Long instrument name
|-
| <tt>BYTE[]</tt> || instData || Instrument data
|}

Instrument data size depends on instrument type:

{|class="wikitable"
! Type !! Size !! Description
|-
| 0 || 22 || Melody (YMF-262M, 4OP Mode)
|-
| 1 || 11 || Melody (YM-3812, 2OP Mode)
|-
| 6 || 11 || Bass Drum
|-
| 7 || 11 || Snare Drum
|-
| 8 || 11 || Tom Tom
|-
| 9 || 11 || Cymbal
|-
| 10 || 11 || Hi-Hat
|-
| 12 || 0 || Unused instrument (comment)
|}

Actual instrument data is just OPL registers dump.

==== 2OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic
|-
|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||iFeedback||0xC0||Feedback/connection
|-
|UINT8||iCarChar||0x23||Carrier characteristic (only melody instruments and bass drum)
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level (only melody instruments)
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level (only melody instruments)
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level (only melody instruments)
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select (only melody instruments)
|}

==== 4OP Mode instrument data ====

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iOp1Char||0x20||Operator 1 characteristic
|-
|UINT8||iOp1Scale||0x40||Operator 1 key scaling/output level
|-
|UINT8||iOp1Attack||0x60||Operator 1 attack/decay level
|-
|UINT8||iOp1Sustain||0x80||Operator 1 sustain/release level
|-
|UINT8||iOp1WaveSel||0xE0||Operator 1 wave select
|-
|UINT8||iOp1Feedback||0xC0||Operator 1 feedback/connection
|-
|UINT8||iOp2Char||0x23||Operator 2 characteristic
|-
|UINT8||iOp2Scale||0x43||Operator 2 key scaling/output level
|-
|UINT8||iOp2Attack||0x63||Operator 2 attack/decay level
|-
|UINT8||iOp2Sustain||0x83||Operator 2 sustain/release level
|-
|UINT8||iOp2WaveSel||0xE3||Operator 2 wave select
|-
|UINT8||iOp3Char||0x28||Operator 3 characteristic
|-
|UINT8||iOp3Scale||0x48||Operator 3 key scaling/output level
|-
|UINT8||iOp3Attack||0x68||Operator 3 attack/decay level
|-
|UINT8||iOp3Sustain||0x88||Operator 3 sustain/release level
|-
|UINT8||iOp3WaveSel||0xE8||Operator 3 wave select
|-
|UINT8||iOp3Feedback||0xC8||Operator 3 feedback/connection
|-
|UINT8||iOp4Char||0x2B||Operator 4 characteristic
|-
|UINT8||iOp4Scale||0x4B||Operator 4 key scaling/output level
|-
|UINT8||iOp4Attack||0x6B||Operator 4 attack/decay level
|-
|UINT8||iOp4Sustain||0x8B||Operator 4 sustain/release level
|-
|UINT8||iOp4WaveSel||0xEB||Operator 4 wave select
|}

=== Sequenced tracks ===

Instrument block is followed by sequenced tracks, containing the music events.

<tt>SOP_TRK</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Track data size in bytes
|-
| <tt>SOP_EVENT[numEvents]</tt> || events || Track events
|}

<tt>SOP_EVENT</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Event code
|-
| <tt>SOP_EVAL</tt> || value || Event structure
|}

<tt>SOP_EVAL</tt> structure is depending on event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 1 || Special Event || <tt>UINT8</tt> value
|-
| 2 || Note On || <tt>UINT8</tt> pitch, <tt>UINT16LE</tt> length (in ticks)
|-
| 4 || Change Volume || <tt>UINT8</tt> volume
|-
| 5 || Change Pitch || <tt>UINT8</tt> pitch (<tt>0x64</tt> (100) is a center value)
|-
| 6 || Instrument Change || <tt>UINT8</tt> number
|-
| 7 || Set Panning || <tt>UINT8</tt> panning (0 - right, 1 - middle, 2 - left)
|}

==== Special Event ====

This event is meaningless in normal playback.

==== Pitch Change ====

The pitch is a signed char type with a value between -100 and +100. The actual pitch setting is the pitch of the current sound plus the frequency of the next sound - the value can be calculated as a percentage. That is, when the pitch is +50 and the current frequency is 153, if the next frequency is 163, then actual output frequency is calculated like this:

153 + (163-153) * 50/100 = 158

=== Control track ===

The last block in the file is control track, it used to control global playback parameters.

<tt>SOP_CTRL</tt> structure is similar to <tt>SOP_TRK</tt>:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || numEvents || Number of control events in track
|-
| <tt>[[UINT32LE]]</tt> || dataSize || Control track data size in bytes
|-
| <tt>SOP_CTEV[numEvents]</tt> || events || Control track events
|}

<tt>SOP_CTEV</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || ticks || Delta ticks (change position)
|-
| <tt>UINT8</tt> || event || Control event code
|-
| <tt>SOP_CVAL</tt> || value || Control event structure
|}

<tt>SOP_CVAL</tt> structure is depending on control event code:

{|class="wikitable"
! Event code !! Description !! Event structure
|-
| 3 || Change Tempo || <tt>UINT8</tt> tempo
|-
| 8 || Global Volume || <tt>UINT8</tt> volume
|}

==== Change Tempo ====

The default tempo value is 255. The frequency is calculated with this formula:

freq = 298295 / (tempo / 100)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = Note
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = No
| canImport = Yes; [[IMS Format|.ims]]
| editHidden = No
| editMetadata = Yes
| notes = Official player and editor
}}
{{EndFileFormatTools}}

== See also ==

* http://www.vogons.org/viewtopic.php?f=5&t=37849 - topic on VOGONS
* https://adplug.github.io/library/entry/Note10b2.html - AdPlug Library entry
* [[ROL Format]] - similar format

== Credits ==

This file format was described by Park Jeenhong in 1996 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

SOP Format

2017-01-09T23:26:42Z

Binarymaster: /* Sequenced tracks */

SOP Format

2017-01-09T22:49:23Z

Binarymaster: /* 2OP Mode instrument data */

SOP Format

2017-01-09T22:32:19Z

Binarymaster: /* 4OP Mode instrument data */

SOP Format

2017-01-09T22:09:47Z

Binarymaster: Created page with "{{NeedMoreInfo}} {{Music Infobox | Type = Custom | Instruments = OPL | NumChannels = 9 or 11 (OPL2), 18 or 20 (OPL3) | NumTracks = 20 | NumPatterns = 1 | NumOrders = 0..."

IMF Format

2016-10-24T09:48:07Z

Binarymaster: Fix typo

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| Tags = Unofficial: Title, Composer, Remarks, Program name
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Cosmo's Cosmic Adventures}}
{{Game|Duke Nukem II}}
{{Game|Hocus Pocus}}
{{Game|Major Stryker}}
{{Game|Monster Bash}}
{{Game|Operation Body Count}}
{{Game|Realms of Chaos}}
{{Game|Wolfenstein 3-D}}
}}

The id Software Music Format (IMF) is a raw music format that stores the actual bytes sent to the Adlib's [[OPL2]] chip. For this reason it is a very simple format to process.

== File format ==

There are two versions of the IMF format: Type-0 format and Type-1 format. In a Type-0 file, the whole file is Adlib data that is played until the end of the file is reached. Type-1 files are actually ripped chunks from an [[AudioT Format]] file. No game ever actually used Type-1 IMFs that were not stored inside an AudioT file. The two initial bytes contain the size of the Adlib data (not including the two bytes themselves), so only this much data is played. This means it's possible to store arbitrary data in a Type-1 IMF file after the song data (see [[#Tag Data]] below.)

As a matter of luck, the first two data bytes in a Type-0 files are almost always 0x00 0x00, so this can be used to detect the file format version. If the first two bytes match the length of the file it is likely Type-1, but be aware that trailing data will mean this is not always true. Otherwise the only other way is to parse all the register/value pairs in the file and ensure the register is [[OPL chip#Register Map|within range]] (e.g. registers 0xA0 to 0xA9 are valid, but 0xAA to 0xAF should never be used.) Note that 0x00 is actually an invalid register, but must be treated as valid since the files usually begin by writing 0x00 to register 0x00.

Another way to detect the type of an IMF file is to examine the first few instructions in the IMF file. The idea is that the first few IMF commands set up the AdLib registers and therefore should have no delay. Even if there is a delay, it would normally be relatively low compared to the combined 16-bit value of the (register, value) pair.

<source lang="c">
UINT16 ReadInt16LE(FILE* in)
{
UINT8 buf[2];
fread(buf, 1, 2, in);
return (buf[0] | (buf[1] << 8));
}

int IMF_IsChunk(FILE* in)
{
UINT16 chunksize, buff, i=42;
UINT32 sum1=0, sum2=0;

if(!in)
return 0;

if (!feof(in))
{
chunksize = ReadInt16LE(in);
if ((chunksize == 0) || (chunksize & 3))
return 0;

while(!feof(in) && i)
{
buff = ReadInt16LE(in);
sum1 += buff;
buff = ReadInt16LE(in);
sum2 += buff;
i--;
}
fseek(in, 0, SEEK_SET);
return (sum1 > sum2);
}
return 0;
}
</source>

In the code given above, if the file is a chunk (Type-1), then <tt>sum1</tt> contains the sum of all (register, value) pairs and <tt>sum2</tt> contains the sum of all delays. If it's a plain IMF file (Type-0), the sums are swapped.

The only case in which this detection would fail is IMF data that writes a bunch of zeroes to register zero (which would be pointless since that register is undefined) and/or has very large delays (which would be pointless because it would lead to delays of up to a minute before the next IMF command would be processed, resulting in multiple minutes of silence before the song actually starts playing notes).

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||iLength||Song data length in bytes (Type-1 format only)
|-
|[[BYTE]][iLength]||cAdlibData||Song data (see below) - <code>iLength</code> bytes long if Type-1, or until EOF if Type-0
|-
|[[BYTE]][]||cExtraData||Arbitrary data/tags (Type-1 format only, see [[#Tag Data]] below)
|}

The earliest version of the IMF data in the [[AudioT Format]] actually starts with a [[UINT32LE]] length value. The Commander Keen 4 Demo uses that early version. Just extracting the IMF chunk from the <tt>AUDIOT.CK4</tt> file will most likely confuse programs, since the file does not start with two 0's. Programs that only check the first two bytes will assume that the file is a ripped chunk, but will swap the delays and register/data pairs because of the length value being stored in the first four bytes instead of just the first two. That means the song will not play the intended notes. Programs that use the detection code given above will identify the file as plain IMF data and treat the length value as an IMF command. That means the song will play correctly at first, but any trailing data present in the file will also be interpreted as IMF data, most likely leading to long delays at the end of the song.

Note that for Type-1 files, the initial two bytes (the "song data length") are likely to be the filesize minus two, as the two initial bytes aren't counted. The obvious exception to this is if there is trailing data at the end of the OPL data, such as an info tag.

The song data is composed of four-byte "units":

{|class="wikitable"
!Data type!!Description
|-
|[[BYTE]]||Adlib register
|-
|[[BYTE]]||Adlib data
|-
|[[UINT16LE]]||Delay
|}

The data byte is sent to the specified register on the Adlib card, followed by a delay for the specified number of cycles. For a 560Hz IMF file, there are 560 cycles in one second (see [[#Timing]] below), so a delay of 560 would result in one second of silence (and likewise in a 700Hz IMF the delay value would need to be 700 to produce one second of silence.) A delay of 1 would wait for a single cycle, and a delay of zero means the next register/data pair should be sent immediately (so in a single 'cycle', data would be sent continuously until the next non-zero delay value is reached.)

=== Timing ===

IMF files exist at three known speeds. Unfortunately this is determined by the game, not the IMF file, so tempo cannot be determined from the music files alone. Extracted IMFs can be compared to discern their speeds. The known speeds are:

{|class="wikitable"
!Speed!!Game
|-
|280Hz||[[Duke Nukem II]]
|-
|560Hz||[[Bio Menace]], [[Commander Keen]], [[Cosmo's Cosmic Adventures]], [[Monster Bash]]
|-
|700Hz||[[Blake Stone]], [[Major Stryker]], [[Operation Body Count]], [[Wolfenstein 3-D]]
|}

The easiest method to tell the files apart is to treat all files with a .WLF extension as 700Hz and all .IMF files as 560Hz. Since Duke II is the odd one out, it is usually ignored since doubling the value of all the delay bytes conveniently turns it into a 560Hz .IMF.

=== Restrictions ===

As IMF files contain Adlib music for games that may also have Adlib sound effects, care must be taken to ensure that IMF music and any sound effects can share the OPL chip without conflict. This is done by reserving the OPL's first channel for sound effects, leaving eight remaining channels available for use in IMF files. This has been confirmed by automated inspection of the IMF files from the following games, all of which have no data on OPL channel #0 beyond 2-3 initialisation commands: [[Bio Menace]], [[Blake Stone]], [[Commander Keen 4-6]], [[Cosmo's Cosmic Adventures]], [[Duke Nukem II]], [[Major Stryker]], [[Monster Bash]], [[Operation Body Count]], [[Wolfenstein 3-D]].

In situations where channel #0 is not reserved and is used by the IMF file, when it is placed back into the game it interferes with the sound effects causing distortion, transposition, and otherwise resulting in broken sound effects. This can happen when an IMF file is created using a utility that does not take into account the fact that channel #0 must be left unused. See the end of this page for a list of utilities that can create IMF files and whether they treat channel #0 correctly.

It is worth noting that channel #0 is unused even in games such as Cosmo and Monster Bash, which do not use Adlib sound effects (Cosmo has PC speaker effects only and Monster Bash has PC speaker and digitised PCM audio.) It is also worth mentioning that some IMF songs from [[Monster Bash]] make use of the OPL's rhythm-mode, which trades three note-producing channels for five percussion channels. The IMF songs from the Keen 4 Demo also use rhythm-mode.

=== Tag Data ===

In a Type-1 IMF file it's possible to store data after the end of a song (as per the length given in the first two bytes of the file.) There are a few uses for this - some games store additional (unused) data there generated when the files were added to the game's group file, and others have repurposed this area to store information about the song itself (title, artist, etc.)

The tag data was originally written to the AudioT files by Id Software's tool [[Muse]] and was probably only processed by that tool. The [[Wolfenstein 3-D]] source code reads the entire chunk from the [[AudioT Format|AudioT]] file (including any tag data), but it only ever uses the song length and the song data.

==== Official data ====
For those files which were distributed with additional data in this area, it is not entirely clear what the purpose of this data is. It was apparently added when the source IMF files were compiled into a group audio file by [[Muse]]. (They appear not to be part of the source IMF files as there are occurrences where a file consists solely of tag data.) The format appears to be the same in all games that use it (such as Bio Menace or Wolfenstein 3-D) but it is not supported by any IMF players.

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||Unknown||
|-
|[[char]][16]||strTitle||Song title
|-
|[[char]][64]||strRemarks||Song comment/message, usually source file name.
|-
|[[char]][6]||cProg||Data from the compiler?
|}

==== Unofficial uses ====
It is also possible to store tags there, and this simple format is supported by most IMF players:

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[BYTE]]||cSignature||0x1A
|-
|[[char]][256]||strTitle||Song title
|-
|[[char]][256]||strComposer||Song composer
|-
|[[char]][256]||strRemarks||Song comment/message
|-
|[[char]][9]||cProg||Name of the first program that added these tags (eight bytes + terminating NULL, pad out with NULLs if necessary.)
|}

Note that the char[256] strings are variable-length NULL-terminated strings. Their maximum length is 256 bytes *including* the terminating NULL, meaning the string will only ever contain 255 characters or less, plus the terminating-NULL. Of course the string will normally be much shorter, and an empty string will consist of a single 0x00 byte.

This tag format is supported by AdPlug when playing IMFs. The tag format can also be used with .raw files, but no players officially support it yet.

Note that the tags should begin directly after the IMF data, so in other words reading in the first two bytes of the file (the "song length") and then seeking forward that many bytes, should put the file pointer at the start of the tag block (so the next byte that will be read in should be 0x1A, if the tags are present.)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://adplug.sourceforge.net AdPlug]
| Platform = All
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[RAW Format (Adlib)|.raw]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/cmf2imf CMF2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[CMF Format|.cmf]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[DRO Format|.dro]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [http://winwolf3d.dugtrio17.com/download/IMFCreator IMFCreator]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MID Format|.mid]]
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = MUS2IMF
| Platform = DOS?
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MUS Format|.mus]]
| editHidden = No
| editMetadata = No
}}
{{EndFileFormatTools}}

MDI Format

2016-09-04T05:24:01Z

Binarymaster: /* See also */ replace link directly to zip archive

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Dark Ages}}
{{Game|Galactix}}
{{Game|Prehistorik}}
}}

The '''MDI Format''' is derived from [[ROL Format]] and have compatible specification for playback. It uses a [[MID Format|standard MIDI file]] structure (MIDI Type 0) that contains MIDI meta events for setting OPL instrument settings. It is a way of storing FM/OPL instruments inside a standard MIDI file, with the file being a standard, fully compatible .mid file. Players that are not aware of the FM/OPL commands will simply ignore them and play the file without instruments.

Typically standard MIDI files use the <tt>.mid</tt> filename extension, while files that use the FM/OPL commands are given the <tt>.mdi</tt> extension.

== Differences to standard MIDI ==

=== Manufacturer-specific events ===

To be compatible with standard MIDI container specification, the format uses sequencer specific events to change instrument patches, control AdLib rhythm mode, and set pitch bend range.

These meta events begins with 0xFF byte, followed by 0x7F parameter, indicating "sequencer specific" event. Then it's followed by variable length value and the data blob.

The first data byte 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. In this case, read another UINT16BE to obtain the opcode, then the data following the opcode is arranged as:

{|class="wikitable"
! Opcode !! Purpose !! Description
|-
| 1 || Instrument change || 29 data bytes follow:<table class="wikitable">
<tr><th>Type</th><th>Name</th><th>Description</th></tr>
<tr><td>[[UINT8]]</td><td>voice</td><td>MIDI channel number to assign instrument to</td></tr>
<tr><td>BNK_ENTRY</td><td>patch</td><td>OPL register settings</td></tr>
</table>
|-
| 2 || Sound mode || One data byte. 0=melodic/rhythm-off, 1=percussive/rhythm-on
|-
| 3 || Pitch bend range || One data byte, value in range 1-12 inclusive. {{TODO|Explain how this works}}
|}

<tt>BNK_ENTRY</tt> is defined as follows: (note this is identical to the layout of an instrument inside a [[AdLib Instrument Bank Format]] .bnk file. See that article for the explanation of the <tt>OPLREGS</tt> structure.)

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[AdLib Instrument Bank Format|OPLREGS]] || oplModulator || Register values for the Modulator operator (op 0)
|-
| [[AdLib Instrument Bank Format|OPLREGS]] || oplCarrier || Register values for the Carrier operator (op 1)
|-
| [[UINT8]] || iModWaveSel || Modulator wave select (OPL base register 0xE0)
|-
| [[UINT8]] || iCarWaveSel || Carrier wave select (OPL base register 0xE0)
|}

=== Channel aftertouch event ===

Event 0xD# is used to control channel volume. It mostly used for dynamic volume control of currently played note (for example: fade in, fade out, or tremolo effects).

=== Velocity parameter ===

This parameter goes with Note On and Note Off events. Since the format is inherited from ROL, it doesn't have note velocity specification.

It also changes current channel volume, same as event previously described.

Some "Note Off" events may have note parameter equal to 0. This event just stops last played note on specified channel. If there is no played note on channel, it obviously used to set channel volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>midiplay.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = AdLib <tt>rol2midi.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[ROL Format|.rol]]
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = Yes
}}
{{EndFileFormatTools}}

== See also ==

* [[MID Format]] - the container format
* [[AdLib Instrument Bank Format]] - format with the same instrument definition structure
* http://cd.textfiles.com/soundsensations/MISCPROG/ZIPFILES/AD-PROG.ZIP - AdLib Programmer's Guide, including source code for playing and converting files in this format

God of Thunder Music Format

2016-08-12T20:39:50Z

Binarymaster: /* Timing */ Update information about timing

{{NeedMoreInfo}}
{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = None
| Games =
{{Game|God of Thunder}}
}}
[[God of Thunder]] stores its music in this format. It is a raw Adlib format, containing the exact register and data pairs to send to the OPL chip.

== File format ==

The file begins with a header of unknown purpose.

{|class="wikitable"
! Data type !! Description
|-
| [[UINT16LE]] header || Always 0x0001
|}

This is then immediately followed by a variable number of three byte chunks.

{|class="wikitable"
! Data type !! Description
|-
| [[BYTE]] delay || Number of ticks to wait *after* the data has been sent
|-
| [[BYTE]] reg || OPL register to write to
|-
| [[BYTE]] val || Value to write
|}

The very last chunk has all values set to zero, plus a final 0x00 byte.

=== Timing ===

Songs are played at a different tempo (i.e. each delay tick lasts a different length of time): <tt>menu.got</tt> plays at 140 Hz, all other songs plays at 120 Hz.
Known song lengths (based on Teppic's PCM recordings of in-game Adlib playback) are:

{|class="wikitable"
! Song !! Length !! Notes
|-
| menu || 1:15,759 || in got.exe, not in gotres.dat
|-
| song11 || 1:41,457 ||
|-
| song12 || 2:07,676 ||
|-
| song13 || 1:07,647 ||
|-
| song14 || 0:59,884 ||
|-
| song21 || 1:19,258 ||
|-
| song22 || 1:27,120 ||
|-
| song23 || 0:34,845 ||
|-
| song24 || 1:06,350 ||
|-
| song25 || 1:39,959 ||
|-
| song31 || 0:55,890 ||
|-
| song32 || 0:58,659 ||
|-
| opensong || 1:19,821 || Story song - slow version of song33
|-
| song33 || 1:13,730 || in-game version of the story song
|-
| song34 || 1:11,795 ||
|-
| song35 || 1:19,315 ||
|-
| song36 || 0:47,887 ||
|-
| winsong || 0:32,918 ||
|-
| bosssong || 0:26,169 ||
|}

When some songs are converted to this format (e.g. Keen 6 aliens.imf), the tempo speeds up considerably towards the end of the file, so it would seem there is some way of adjusting the song tempo during playback. {{TODO|Check whether it's a conversion bug.}}

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [http://grompe.org.ru/ GromPE's GoT unpacker]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [http://grompe.org.ru/ GromPE's OPL2WAV]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[WAV Format|.wav]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [[Wombat]]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{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!)

God of Thunder Music Format

2016-08-12T19:59:08Z

Binarymaster: /* Timing */ correct file names

{{NeedMoreInfo}}
{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = None
| Games =
{{Game|God of Thunder}}
}}
[[God of Thunder]] stores its music in this format. It is a raw Adlib format, containing the exact register and data pairs to send to the OPL chip.

== File format ==

The file begins with a header of unknown purpose.

{|class="wikitable"
! Data type !! Description
|-
| [[UINT16LE]] header || Always 0x0001
|}

This is then immediately followed by a variable number of three byte chunks.

{|class="wikitable"
! Data type !! Description
|-
| [[BYTE]] delay || Number of ticks to wait *after* the data has been sent
|-
| [[BYTE]] reg || OPL register to write to
|-
| [[BYTE]] val || Value to write
|}

The very last chunk has all values set to zero, plus a final 0x00 byte.

=== Timing ===

Each song is played at a different tempo (i.e. each delay tick lasts a different length of time) however {{TODO|it is not currently known how to obtain the correct tempo for a given song.}}

Known song lengths (based on Teppic's PCM recordings of in-game Adlib playback) are:

{|class="wikitable"
! Song !! Length !! Notes
|-
| menu || 1:15,759 || in got.exe, not in gotres.dat
|-
| song11 || 1:41,457 ||
|-
| song12 || 2:07,676 ||
|-
| song13 || 1:07,647 ||
|-
| song14 || 0:59,884 ||
|-
| song21 || 1:19,258 ||
|-
| song22 || 1:27,120 ||
|-
| song23 || 0:34,845 ||
|-
| song24 || 1:06,350 ||
|-
| song25 || 1:39,959 ||
|-
| song31 || 0:55,890 ||
|-
| song32 || 0:58,659 ||
|-
| opensong || 1:19,821 || Story song - slow version of song33
|-
| song33 || 1:13,730 || in-game version of the story song
|-
| song34 || 1:11,795 ||
|-
| song35 || 1:19,315 ||
|-
| song36 || 0:47,887 ||
|-
| winsong || 0:32,918 ||
|-
| bosssong || 0:26,169 ||
|}

When some songs are converted to this format (e.g. Keen 6 aliens.imf), the tempo speeds up considerably towards the end of the file, so it would seem there is some way of adjusting the song tempo during playback.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [http://grompe.org.ru/ GromPE's GoT unpacker]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [http://grompe.org.ru/ GromPE's OPL2WAV]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[WAV Format|.wav]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{FileFormatTool
| Name = [[Wombat]]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Incorrect tempo
}}
{{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!)

ROL Format

2016-07-31T17:48:46Z

Binarymaster: Document a new format

{{Music Infobox
| Type = Custom
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 45
| NumPatterns = 1
| NumOrders = 0
| Tags = None
| Games =
{{Game|Pee and Gity}}
{{Game|Hi Octane}}
}}

The '''ROL Format''' is created by Ad Lib, Inc. for AdLib Visual Composer program. Some games use it for the background music.

Earlier ROL files goes with [[AdLib Instrument Format|instrument]] files, but later they were superseded by single [[AdLib Instrument Bank Format|instrument bank]] file.

== File format ==

=== Header ===

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[UINT16LE]]</tt> || majorVersion || Major version number (usually 0)
|-
| <tt>UINT16LE</tt> || minorVersion || Minor version number (usually 4)
|-
| <tt>[[char]][40]</tt> || signature || Signature, null terminated (usually "<tt>\roll\default</tt>")
|-
| <tt>UINT16LE</tt> || tickBeat || Number of ticks per beat
|-
| <tt>UINT16LE</tt> || beatMeasure || Number of beats per measure
|-
| <tt>UINT16LE</tt> || scaleY || Editing scale (Y axis)
|-
| <tt>UINT16LE</tt> || scaleX || Editing scale (X axis)
|-
| <tt>[[BYTE]]</tt> || reserved || Unused, set to zero
|-
| <tt>UINT8</tt> || isMelodic || OPL rhythm mode: 0 = percussive, 1 = melodic
|-
| <tt>UINT16LE[45]</tt> || counters || Counter values for each track ([[#Counter values|see below]])
|-
| <tt>BYTE[38]</tt> || filler || Padding, set to zero
|}

The most known version of this format is 0.4.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> are used to convert ticks into beats and measures for drawing a musical staff in AdLib Visual Composer.

=== Tracks ===

Header is followed by 45 tracks of different type. The first is always a tempo track. Then it's followed by Voice, Timbre, Volume, and Pitch tracks, repeated 11 times for each possible AdLib voice.

This resulting in actual track count:

1 + 4 * 11 = 45

ROL files always contain 45 tracks even if 9-voice melodic mode is used.

==== Tempo track ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>char[15]</tt> || trackName || Track name, null terminated (usually "<tt>Tempo</tt>")
|-
| <tt>[[Single]]</tt> || basicTempo || Song tempo, in beats-per-minute
|-
| <tt>UINT16LE</tt> || nEvents || Number of events
|-
| <tt>E_TEMPO[nEvents]</tt> || tempoEvents || Array of tempo events
|}

<tt>E_TEMPO</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || atTick || Time of event, in ticks (absolute)
|-
| <tt>Single</tt> || multiplier || Tempo multiplier (in range 0.01 - 10.0)
|}

The <tt>basicTempo</tt> field controls the song playback speed and is measured in beats per minute. The playback frequency can be calculated as follows:

frequency = (basicTempo / 60) * tickBeat

For a song that plays at 120BPM and with 10 ticks per beat, this works out as:

frequency = (120 / 60) * 10
= 20 Hz

Therefore playback should happen at 20 ticks per second to be at the correct tempo.

Tempo multiplier allows to change song speed during playback, so the actual frequency is calculated like this:

frequency = (basicTempo / 60) * tickBeat * multiplier

==== Voice track ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>char[15]</tt> || trackName || Track name, null terminated (usually "<tt>Voix ##</tt>", # - voice number from 0)
|-
| <tt>UINT16LE</tt> || nTicks || Total ticks for current track
|-
| <tt>E_NOTE[]</tt> || noteEvents || Array of note events
|}

<tt>E_NOTE</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || note || Note number (0: note off, 12..107: note on)
|-
| <tt>UINT16LE</tt> || duration || Note duration, in ticks
|}

This structure is repeated while the sum of <tt>duration</tt> values is less than <tt>nTicks</tt> value.

The <tt>note</tt> value is compatible with MIDI standard (48 is middle-C).

==== Timbre track ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>char[15]</tt> || trackName || Track name, null terminated (usually "<tt>Timbre ##</tt>", # - voice number from 0)
|-
| <tt>UINT16LE</tt> || nEvents || Number of events
|-
| <tt>E_TIMBRE[nEvents]</tt> || timbreEvents || Array of timbre events
|}

<tt>E_TIMBRE</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || atTick || Time of event, in ticks (absolute)
|-
| <tt>char[9]</tt> || instName || Instrument name, null terminated
|-
| <tt>BYTE</tt> || filler || Padding, set to zero
|-
| <tt>UINT16LE</tt> || unknown || Unknown value, sometimes equal to instrument index
|}

These events set the instrument to be played on specified channel.

Instrument name is a reference to [[AdLib Instrument Format|<tt>INSTNAME.INS</tt>]] file, or an instrument name inside [[AdLib Instrument Bank Format|<tt>STANDARD.BNK</tt>]] file.

==== Volume track ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>char[15]</tt> || trackName || Track name, null terminated (usually "<tt>Volume ##</tt>", # - voice number from 0)
|-
| <tt>UINT16LE</tt> || nEvents || Number of events
|-
| <tt>E_VOLUME[nEvents]</tt> || volumeEvents || Array of volume events
|}

<tt>E_VOLUME</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || atTick || Time of event, in ticks (absolute)
|-
| <tt>Single</tt> || volume || Volume multiplier (in range 0.0 - 1.0)
|}

These events set the volume for specified channel.

==== Pitch track ====

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>char[15]</tt> || trackName || Track name, null terminated (usually "<tt>Pitch ##</tt>", # - voice number from 0)
|-
| <tt>UINT16LE</tt> || nEvents || Number of events
|-
| <tt>E_PITCH[nEvents]</tt> || pitchEvents || Array of pitch events
|}

<tt>E_PITCH</tt> structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>UINT16LE</tt> || atTick || Time of event, in ticks (absolute)
|-
| <tt>Single</tt> || pitch || Pitch variation (in range 0.0 - 2.0)
|}

These events works the same as Pitch Bend events. Nominal <tt>pitch</tt> value is 1.0.

=== Counter values ===

There are 45 counter values for each track.

{|class="wikitable"
! Data type !! Name !! Description
|-
| <tt>[[UINT16LE]][11]</tt> || cTicks || Total ticks for each voice track
|-
| <tt>[[UINT16LE]][11]</tt> || cTimbreEvents || Number of events for each timbre track
|-
| <tt>[[UINT16LE]][11]</tt> || cVolumeEvents || Number of events for each volume track
|-
| <tt>[[UINT16LE]][11]</tt> || cPitchEvents || Number of events for each pitch track
|-
| <tt>[[UINT16LE]]</tt> || cTempoEvents || Number of events in the tempo track
|}

== Rhythm mode ==

If <tt>isMelodic</tt> is 1, then rhythm mode is off. Valid channels are 0 to 8 inclusive.

When <tt>isMelodic</tt> is 0, then rhythm mode is on. Valid channels are 0 to 10, with 0 to 5 being melodic and 6 to 10 being percussive (see table below).

Both the top cymbal and the snare drum only use the OPL carrier registers, but the values for these registers are actually stored in the file's modulator fields. The carrier fields for these instruments appear to be unused. In other words, percussive instruments always have their settings loaded from the instrument's modulator fields, even when the values are loaded into the OPL chip's carrier registers.

{|class="wikitable"
! Channel !! Percussive instrument !! Operator used in file !! OPL cell
|-
| 0-5 || Melodic || Modulator Carrier || Modulator Carrier
|-
| 6 || Bass drum || Modulator Carrier || 13 - Channel 7 Modulator 16 - Channel 7 Carrier
|-
| 7 || Snare drum || Modulator || 17 - Channel 8 Carrier
|-
| 8 || Tom tom || Modulator || 15 - Channel 9 Modulator
|-
| 9 || Top cymbal || Modulator || 18 - Channel 9 Carrier
|-
| 10 || Hi-hat || Modulator || 14 - Channel 8 Modulator
|}

BNK files have an indicator whether a patch is percussive or melodic, however it is not used by official ROL player. It's controlled entirely by which channel it is used on. It is possible to use the same patch for both percussive and melodic channels.

In percussive mode, the pitch of the single-operator percussive instruments is handled specially (that is, the snare drum, tom tom, top cymbal and hi-hat. The bass drum is not considered here.) When a note is played on channel 8 (tom-tom), the pitch on the other instruments is changed also. The changes are:

{|class="wikitable"
! Channel !! Percussive instrument !! Note pitch
|-
| 7 || Snare drum || 7 semitones higher than the last tom-tom note on channel 8
|-
| 8 || Tom tom || Use pitch as indicated in the note-on event
|-
| 9 || Top cymbal || Use pitch from last tom-tom note on channel 8
|-
| 10 || Hi-hat || 7 semitones higher than the last tom-tom note on channel 8
|}

The initial frequency for the tom-tom is supposed to be two octaves below middle-C according to comments in the official <tt>adlib.c</tt>, however {{TODO|this doesn't seem to be the case.}}

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>playrol.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Included with AdLib Visual Composer
}}
{{FileFormatTool
| Name = AdLib <tt>convert.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[AdLib MIDI Format|.mus]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = AdLib <tt>rol2midi.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MDI Format|.mdi]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{EndFileFormatTools}}

== See also ==

* [[AdLib Instrument Format]] - first time companion format for storing instruments for songs in this format
* [[AdLib Instrument Bank Format]] - second time companion format for storing instruments for songs in this format
* http://hwiegman.home.xs4all.nl/fileformats/rol/Rol-form.txt - format described by Chris Holmes
* [[AdLib MIDI Format]], [[IMS Format]], [[MDI Format]] - derived formats

== Credits ==

This file format was described by Chris Holmes in 1992 and then adapted and supplemented by [[User:binarymaster|binarymaster]]. 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!)

Double

2016-07-31T14:36:48Z

Binarymaster: Redirected page to File format data types

#REDIRECT [[File format data types]]

Single

2016-07-31T14:36:43Z

Binarymaster: Redirected page to File format data types

#REDIRECT [[File format data types]]

File format data types

2016-07-31T14:35:10Z

Binarymaster: /* Type list */ add floating point values

This is a list of all the data types used in the file format descriptions on the wiki. They are loosely based on common C/C++ data types, and should be used throughout the wiki for consistency.

== Type list ==

==== Numeric values ====

{|class="wikitable"
!Data type!!Description
|-
|UINT8||Unsigned 8-bit integer
|-
|UINT16LE||Unsigned 16-bit integer in little-endian format
|-
|UINT16BE||Unsigned 16-bit integer in big-endian format
|-
|UINT32LE||Unsigned 32-bit integer in little-endian format
|-
|UINT32BE||Unsigned 32-bit integer in big-endian format
|}

Signed equivalents are the same without the leading U, i.e. <tt>INT8</tt>, <tt>INT16LE</tt>, etc. Unless otherwise stated, the format is in [[wikipedia:Two's complement|two's complement]] (where a UINT8 value of 255 is -1 as an INT8, for example.)

==== Floating point values ====

{|class="wikitable"
!Data type!!Description
|-
|Single||32-bit float (IEEE-754)
|-
|[[Turbo Pascal Real|Real]]||48-bit float (Pascal specific)
|-
|Double||64-bit float (IEEE-754)
|}

All floating point values are signed. They usually contain a sign bit, exponent, and mantissa.

==== Character strings ====
{|class="wikitable"
!Data type!!Description
|-
|char[x]||String ''x'' characters long
|-
|char||Single 8-bit character
|-
|ASCIIZ||A C-style string (variable-length, terminated with a single NULL/0x00 value)
|}

==== Misc data types ====
{|class="wikitable"
!Data type!!Description
|-
|BYTE||Same as UINT8 but conceptually for generic data rather than numeric values (e.g. UINT8 would be used for a number, while a BYTE would be used for a bitfield)
|-
|BYTE[x]||Block of data ''x'' bytes long
|}

== Big endian vs little endian ==

For numeric values larger than a single byte, the endianness specifies how the values are split over multiple bytes. For example a hex value of 0x1234AABB when written to a file will take up two bytes, as follows:

{|class="wikitable"
!Endian!!Bytes in file
|-
|Big||<code>12 34 AA BB</code>
|-
|Little||<code>BB AA 34 12</code>
|}

For those languages that allow direct memory access such as C/C++, converting an integer value to a byte array will reveal the value stored in-memory in the same order as the table above.

Normally when reading or writing a variable to a file a programmer will simply pass the memory address of the variable, resulting in the file mirroring the byte order in memory. This is no problem when reading the variable back in on the same system, as the byte order will match. However when reading data from a different system (for example using an Intel PC to read files from a PowerPC Mac) the byte order will be opposite to what the system expects and the programmer must convert the values manually.

=== Conversion examples ===

If a value is being read on the same system (little to little or big to big) then no action is required. If the systems are different, then the values must be swapped. The following sections list examples for different programming languages.

==== C/C++ ====

<source lang="c">
// 16-bit
int in = 0x1234;
int out = ((in & 0xFF) << 8) | (in >> 8);
// out should now be 0x3412

// 32-bit
int in = 0x1234AABB;
int out =
((in & 0xFF) << 24) |
((in & 0xFF00) << 8) |
((in & 0xFF0000) >> 8) |
(in >> 24);
// out should now be 0xBBAA3412
</source>

==== C# .NET ====

<source lang="csharp">
Int16 ByteSwap16(Int16 inValue)
{
return (Int16)(
((inValue & 0xFF) << 8) |
((inValue >> 8) & 0xFF)
);
}

Int32 ByteSwap32(Int32 inValue)
{
return (Int32)(
((inValue & 0xFF) << 24) |
((inValue & 0xFF00) << 8) |
((inValue & 0xFF0000) >> 8) |
((inValue >> 24) & 0xFF)
);
}
</source>

==== Visual Basic .NET ====

<source lang="vbnet">
Function ByteSwap16(ByVal InValue as Int16) as Int16
Return ((InValue And &HFF) << 8) Or ((InValue >> 8) And &HFF)
End Function

Function ByteSwap32(ByVal InValue as Int32) as Int32
Return ((InValue And &HFF) << 24) Or _
((InValue And &HFF00) << 8) Or _
((InValue And &HFF0000) >> 8) Or _
((InValue >> 24) And &HFF)
End Function
</source>

[[Category:File Formats]]

MID Format

2016-07-31T14:01:28Z

Binarymaster: Link to MDI Format

{{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) >> 1) | (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)
|}

===== 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]]

MDI Format

2016-07-31T13:55:10Z

Binarymaster: Update format specification from latest research

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Dark Ages}}
{{Game|Galactix}}
{{Game|Prehistorik}}
}}

The '''MDI Format''' is derived from [[ROL Format]] and have compatible specification for playback. It uses a [[MID Format|standard MIDI file]] structure (MIDI Type 0) that contains MIDI meta events for setting OPL instrument settings. It is a way of storing FM/OPL instruments inside a standard MIDI file, with the file being a standard, fully compatible .mid file. Players that are not aware of the FM/OPL commands will simply ignore them and play the file without instruments.

Typically standard MIDI files use the <tt>.mid</tt> filename extension, while files that use the FM/OPL commands are given the <tt>.mdi</tt> extension.

== Differences to standard MIDI ==

=== Manufacturer-specific events ===

To be compatible with standard MIDI container specification, the format uses sequencer specific events to change instrument patches, control AdLib rhythm mode, and set pitch bend range.

These meta events begins with 0xFF byte, followed by 0x7F parameter, indicating "sequencer specific" event. Then it's followed by variable length value and the data blob.

The first data byte 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. In this case, read another UINT16BE to obtain the opcode, then the data following the opcode is arranged as:

{|class="wikitable"
! Opcode !! Purpose !! Description
|-
| 1 || Instrument change || 29 data bytes follow:<table class="wikitable">
<tr><th>Type</th><th>Name</th><th>Description</th></tr>
<tr><td>[[UINT8]]</td><td>voice</td><td>MIDI channel number to assign instrument to</td></tr>
<tr><td>BNK_ENTRY</td><td>patch</td><td>OPL register settings</td></tr>
</table>
|-
| 2 || Sound mode || One data byte. 0=melodic/rhythm-off, 1=percussive/rhythm-on
|-
| 3 || Pitch bend range || One data byte, value in range 1-12 inclusive. {{TODO|Explain how this works}}
|}

<tt>BNK_ENTRY</tt> is defined as follows: (note this is identical to the layout of an instrument inside a [[AdLib Instrument Bank Format]] .bnk file. See that article for the explanation of the <tt>OPLREGS</tt> structure.)

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[AdLib Instrument Bank Format|OPLREGS]] || oplModulator || Register values for the Modulator operator (op 0)
|-
| [[AdLib Instrument Bank Format|OPLREGS]] || oplCarrier || Register values for the Carrier operator (op 1)
|-
| [[UINT8]] || iModWaveSel || Modulator wave select (OPL base register 0xE0)
|-
| [[UINT8]] || iCarWaveSel || Carrier wave select (OPL base register 0xE0)
|}

=== Channel aftertouch event ===

Event 0xD# is used to control channel volume. It mostly used for dynamic volume control of currently played note (for example: fade in, fade out, or tremolo effects).

=== Velocity parameter ===

This parameter goes with Note On and Note Off events. Since the format is inherited from ROL, it doesn't have note velocity specification.

It also changes current channel volume, same as event previously described.

Some "Note Off" events may have note parameter equal to 0. This event just stops last played note on specified channel. If there is no played note on channel, it obviously used to set channel volume.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>midiplay.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = AdLib <tt>rol2midi.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[ROL Format|.rol]]
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = Yes
}}
{{EndFileFormatTools}}

== See also ==

* [[MID Format]] - the container format
* [[AdLib Instrument Bank Format]] - format with the same instrument definition structure
* http://cd.textfiles.com/soundsensations/MISCPROG/AD-PROG/ - AdLib Programmer's Guide, including source code for playing and converting files in this format

AdLib MIDI Format

2016-07-31T13:09:15Z

Binarymaster: /* Timing */ Overflow bytes

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = Title
| Games =
{{Game|Kung Fu Louie Vs. The Martial Art Posse}}
{{Game|Weird Dreams}}
{{Game|DragonStrike}}
{{Game|Vinyl Goddess From Mars}}
}}

The '''AdLib MIDI Format''' is an Ad Lib music format, based on the standard MIDI format. It is derived from [[ROL Format]] and have compatible specification for playback. The format has a custom header, but the actual music data mostly in standard MIDI notation. Despite this, it appears that it was never intended to be played on a MIDI device, as the patch numbers refer to indices into a companion OPL instrument bank in [[AdLib Timbre Bank Format]].

In this respect it is similar to the [[CMF Format]], which also stores OPL music in MIDI notation, but unlike CMF this format keeps the instruments in a separate file.

== File format ==

The file is arranged like this:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || majorVersion || Major version number (usually 1)
|-
| UINT8 || minorVersion || Minor version number (usually 0)
|-
| INT32LE || tuneId || Song identification number
|-
| char[30] || tuneName || Song title, null terminated
|-
| UINT8 || tickBeat || Number of ticks per beat
|-
| UINT8 || beatMeasure || Number of beats per measure
|-
| INT32LE || totalTick || Length of song, in ticks
|-
| INT32LE || dataSize || Length of MIDI data block, in bytes
|-
| INT32LE || nrCommand || Total number of MIDI events in song, including final 0xFC "stop"
|-
| BYTE[8] || filler || Padding, set to zero
|-
| UINT8 || soundMode || OPL rhythm mode: 0=melodic (off), 1=percussive (on)
|-
| UINT8 || pitchBRange || Pitchbend range (1-12)
|-
| UINT16 || basicTempo || Song tempo, in beats-per-minute.
|-
| BYTE[8] || filler2 || Padding, set to zero
|-
| BYTE[dataSize] || data || Song data in standard MIDI format (same content as a MIDI MTrk block, almost)
|}

The only known version of this format is 1.0.

=== Timing ===

The MIDI delay bytes in the song data are in units of "ticks", as per normal. Timing bytes vary from 0 to 0xFE and precede every command. A timing byte of 0xF8 means timing overflow with a value of 240. An overflow byte is always followed by another overflow byte or timing byte.

The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> can be used to convert ticks into beats and measures if desired, for example when drawing a musical staff.

The <tt>basicTempo</tt> field controls the song playback speed and is measured in beats per minute. The playback frequency can be calculated as follows:

frequency = (basicTempo / 60) * tickBeat

For a song that plays at 120BPM and with 10 ticks per beat, this works out as:

frequency = (120 / 60) * 10
= 20 Hz

Therefore playback should happen at 20 ticks per second to be at the correct tempo.

Also the song speed can be controlled during playback, see [[#Tempo multiplier]] event.

=== Rhythm mode ===

If <tt>soundMode</tt> is 0, then rhythm mode is off. Valid MIDI channels are 0 to 8 inclusive.

When <tt>soundMode</tt> is 1, then rhythm mode is on. Valid MIDI channels are 0 to 10, with 0 to 5 being melodic and 6 to 10 being percussive (see table below.) The official code actually treats any nonzero value as enabling rhythm mode, however only the values 0 and 1 should be used.

Both the top cymbal and the snare drum only use the OPL carrier registers, but the values for these registers are actually stored in the file's modulator fields. The carrier fields for these instruments appear to be unused. In other words, percussive instruments always have their settings loaded from the instrument's modulator fields, even when the values are loaded into the OPL chip's carrier registers.

{|class="wikitable"
! MIDI channel !! Percussive instrument !! Operator used in file !! OPL cell
|-
| 0-5 || Melodic || Modulator Carrier || Modulator Carrier
|-
| 6 || Bass drum || Modulator Carrier || 13 - Channel 7 Modulator 16 - Channel 7 Carrier
|-
| 7 || Snare drum || Modulator || 17 - Channel 8 Carrier
|-
| 8 || Tom tom || Modulator || 15 - Channel 9 Modulator
|-
| 9 || Top cymbal || Modulator || 18 - Channel 9 Carrier
|-
| 10 || Hi-hat || Modulator || 14 - Channel 8 Modulator
|}

There is no indicator whether a patch is percussive or melodic, so this is controlled entirely by which MIDI channel it is used on. It is possible to use the same patch for both percussive and melodic channels.

In percussive mode, the pitch of the single-operator percussive instruments is handled specially (that is, the snare drum, tom tom, top cymbal and hi-hat. The bass drum is not considered here.) When a note is played on MIDI channel 8 (tom-tom), the pitch on the other instruments is changed also. The changes are:

{|class="wikitable"
! MIDI channel !! Percussive instrument !! Note pitch
|-
| 7 || Snare drum || 7 semitones higher than the last tom-tom note on MIDI channel 8
|-
| 8 || Tom tom || Use pitch as indicated in the MIDI note-on event
|-
| 9 || Top cymbal || Use pitch from last tom-tom note on MIDI channel 8
|-
| 10 || Hi-hat || 7 semitones higher than the last tom-tom note on MIDI channel 8
|}

The initial frequency for the tom-tom is supposed to be two octaves below middle-C according to comments in the official <tt>adlib.c</tt>, however {{TODO|this doesn't seem to be the case.}}

=== Differences to MIDI ===

==== Polyphonic key pressure ====

According to MIDI specification, event 0xA# should have two byte parameters (the key/note and the pressure for that note), however this format provides only one byte parameter.

It is used to control channel volume. It frequently appears in the beginning of MIDI stream. Also it may be used for dynamic volume control of currently played note (for example: fade in, fade out, or tremolo effects).

==== Velocity parameter ====

This parameter goes with Note On and Note Off events. Since the format is inherited from ROL, it doesn't have note velocity specification.

It also changes current channel volume, same as event previously described.

If "Note On" event has velocity parameter equal to 0, it is treated as "Note Off" event, and channel volume is not changed.

==== Tempo multiplier ====

This event is structured like System Exclusive event, beginning with bytes 0xF0 0x7F and ending with 0xF7 byte.

By default, it does have fixed length of 6 bytes (including status bytes), and is used to change song speed during playback. It consists of an integer and a fractional part, in 1/128.

{|class="wikitable"
! Byte
! Description
|-
| 0xF0
| SysEx Status Byte
|-
| 0x7F
| Universal Realtime Command
|-
| 0x00
| Reserved
|-
| XX
| Integer part
|-
| YY
| Fractional part 1/128
|-
| 0xF7
| End of SysEx
|}

So the actual frequency calculated like this:

multiplier = XX + YY / 128
frequency = (basicTempo / 60) * tickBeat * multiplier

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>play.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = AdLib <tt>convert.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[ROL Format|.rol]]
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/vinyl2cmf Vinyl2CMF]
| Platform = Windows CLI
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[CMF Format|.cmf]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{EndFileFormatTools}}

== See also ==

* [[AdLib Timbre Bank Format]] - companion format for storing instruments for songs in this format
* http://files.mpoli.fi/software/programm/general/adlip.zip - AdLib Programmer's Guide, including source code for playing and converting files in this format

== Credits ==

This file format was originally reverse engineered by [[User:Malvineous|Malvineous]] as the [[Vinyl Goddess From Mars]] music format, until [[User:binarymaster|binarymaster]] discovered it was the same as an early AdLib music format, and supplied the documentation on which this article is now based. 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!)

AdLib MIDI Format

2016-07-31T13:04:31Z

Binarymaster: Update format specification from latest research

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = Title
| Games =
{{Game|Kung Fu Louie Vs. The Martial Art Posse}}
{{Game|Weird Dreams}}
{{Game|DragonStrike}}
{{Game|Vinyl Goddess From Mars}}
}}

The '''AdLib MIDI Format''' is an Ad Lib music format, based on the standard MIDI format. It is derived from [[ROL Format]] and have compatible specification for playback. The format has a custom header, but the actual music data mostly in standard MIDI notation. Despite this, it appears that it was never intended to be played on a MIDI device, as the patch numbers refer to indices into a companion OPL instrument bank in [[AdLib Timbre Bank Format]].

In this respect it is similar to the [[CMF Format]], which also stores OPL music in MIDI notation, but unlike CMF this format keeps the instruments in a separate file.

== File format ==

The file is arranged like this:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || majorVersion || Major version number (usually 1)
|-
| UINT8 || minorVersion || Minor version number (usually 0)
|-
| INT32LE || tuneId || Song identification number
|-
| char[30] || tuneName || Song title, null terminated
|-
| UINT8 || tickBeat || Number of ticks per beat
|-
| UINT8 || beatMeasure || Number of beats per measure
|-
| INT32LE || totalTick || Length of song, in ticks
|-
| INT32LE || dataSize || Length of MIDI data block, in bytes
|-
| INT32LE || nrCommand || Total number of MIDI events in song, including final 0xFC "stop"
|-
| BYTE[8] || filler || Padding, set to zero
|-
| UINT8 || soundMode || OPL rhythm mode: 0=melodic (off), 1=percussive (on)
|-
| UINT8 || pitchBRange || Pitchbend range (1-12)
|-
| UINT16 || basicTempo || Song tempo, in beats-per-minute.
|-
| BYTE[8] || filler2 || Padding, set to zero
|-
| BYTE[dataSize] || data || Song data in standard MIDI format (same content as a MIDI MTrk block, almost)
|}

The only known version of this format is 1.0.

=== Timing ===

The MIDI delay bytes in the song data are in units of "ticks", as per normal. The fields <tt>tickBeat</tt> and <tt>beatMeasure</tt> can be used to convert ticks into beats and measures if desired, for example when drawing a musical staff.

The <tt>basicTempo</tt> field controls the song playback speed and is measured in beats per minute. The playback frequency can be calculated as follows:

frequency = (basicTempo / 60) * tickBeat

For a song that plays at 120BPM and with 10 ticks per beat, this works out as:

frequency = (120 / 60) * 10
= 20 Hz

Therefore playback should happen at 20 ticks per second to be at the correct tempo.

=== Rhythm mode ===

If <tt>soundMode</tt> is 0, then rhythm mode is off. Valid MIDI channels are 0 to 8 inclusive.

When <tt>soundMode</tt> is 1, then rhythm mode is on. Valid MIDI channels are 0 to 10, with 0 to 5 being melodic and 6 to 10 being percussive (see table below.) The official code actually treats any nonzero value as enabling rhythm mode, however only the values 0 and 1 should be used.

Both the top cymbal and the snare drum only use the OPL carrier registers, but the values for these registers are actually stored in the file's modulator fields. The carrier fields for these instruments appear to be unused. In other words, percussive instruments always have their settings loaded from the instrument's modulator fields, even when the values are loaded into the OPL chip's carrier registers.

{|class="wikitable"
! MIDI channel !! Percussive instrument !! Operator used in file !! OPL cell
|-
| 0-5 || Melodic || Modulator Carrier || Modulator Carrier
|-
| 6 || Bass drum || Modulator Carrier || 13 - Channel 7 Modulator 16 - Channel 7 Carrier
|-
| 7 || Snare drum || Modulator || 17 - Channel 8 Carrier
|-
| 8 || Tom tom || Modulator || 15 - Channel 9 Modulator
|-
| 9 || Top cymbal || Modulator || 18 - Channel 9 Carrier
|-
| 10 || Hi-hat || Modulator || 14 - Channel 8 Modulator
|}

There is no indicator whether a patch is percussive or melodic, so this is controlled entirely by which MIDI channel it is used on. It is possible to use the same patch for both percussive and melodic channels.

In percussive mode, the pitch of the single-operator percussive instruments is handled specially (that is, the snare drum, tom tom, top cymbal and hi-hat. The bass drum is not considered here.) When a note is played on MIDI channel 8 (tom-tom), the pitch on the other instruments is changed also. The changes are:

{|class="wikitable"
! MIDI channel !! Percussive instrument !! Note pitch
|-
| 7 || Snare drum || 7 semitones higher than the last tom-tom note on MIDI channel 8
|-
| 8 || Tom tom || Use pitch as indicated in the MIDI note-on event
|-
| 9 || Top cymbal || Use pitch from last tom-tom note on MIDI channel 8
|-
| 10 || Hi-hat || 7 semitones higher than the last tom-tom note on MIDI channel 8
|}

The initial frequency for the tom-tom is supposed to be two octaves below middle-C according to comments in the official <tt>adlib.c</tt>, however {{TODO|this doesn't seem to be the case.}}

=== Differences to MIDI ===

==== Polyphonic key pressure ====

According to MIDI specification, event 0xA# should have two byte parameters (the key/note and the pressure for that note), however this format provides only one byte parameter.

It is used to control channel volume. It frequently appears in the beginning of MIDI stream. Also it may be used for dynamic volume control of currently played note (for example: fade in, fade out, or tremolo effects).

==== Velocity parameter ====

This parameter goes with Note On and Note Off events. Since the format is inherited from ROL, it doesn't have note velocity specification.

It also changes current channel volume, same as event previously described.

If "Note On" event has velocity parameter equal to 0, it is treated as "Note Off" event, and channel volume is not changed.

==== Tempo multiplier ====

This event is structured like System Exclusive event, beginning with bytes 0xF0 0x7F and ending with 0xF7 byte.

By default, it does have fixed length of 6 bytes (including status bytes), and is used to change song speed during playback. It consists of an integer and a fractional part, in 1/128.

{|class="wikitable"
! Byte
! Description
|-
| 0xF0
| SysEx Status Byte
|-
| 0x7F
| Universal Realtime Command
|-
| 0x00
| Reserved
|-
| XX
| Integer part
|-
| YY
| Fractional part 1/128
|-
| 0xF7
| End of SysEx
|}

So the actual frequency calculated like this:

multiplier = XX + YY / 128
frequency = (basicTempo / 60) * tickBeat * multiplier

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>play.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = AdLib <tt>convert.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[ROL Format|.rol]]
| editHidden = No
| editMetadata = No
| notes = Part of AdLib Programmer's Guide
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/vinyl2cmf Vinyl2CMF]
| Platform = Windows CLI
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[CMF Format|.cmf]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{EndFileFormatTools}}

== See also ==

* [[AdLib Timbre Bank Format]] - companion format for storing instruments for songs in this format
* http://files.mpoli.fi/software/programm/general/adlip.zip - AdLib Programmer's Guide, including source code for playing and converting files in this format

== Credits ==

This file format was originally reverse engineered by [[User:Malvineous|Malvineous]] as the [[Vinyl Goddess From Mars]] music format, until [[User:binarymaster|binarymaster]] discovered it was the same as an early AdLib music format, and supplied the documentation on which this article is now based. 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!)

AdLib Instrument Bank Format

2016-07-28T10:14:59Z

Binarymaster: /* Tools */ add AdLib Bank Manager

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL
| Count = 65535
| Names = Yes, 8 chars
| Games =
{{Game|SkyRoads}}
{{Game|Super Tetris}}
{{Game|Wordtris}}
{{Game|Witchaven}}
{{Game|Witchaven II}}
{{Game|Dark Legions}}
}}
The '''Ad Lib BNK Format''' is an instrument bank file created by the Ad Lib Corporation. It was designed for version 1.5 of ''AdLib Visual Composer'' in 1989, to work in conjunction with [[ROL Format]] music files. It had been discovered that the ~80-byte [[AdLib Instrument Format|individual instrument files]] were actually using closer to 1,024 bytes of disk space each, due to the way the DOS FAT filesystem allocates at least one cluster per file. By combining all the instruments into a single <tt>.bnk</tt> file, disk space could be drastically reduced.

BNK files contain all of the custom instrument data for a set of ROL songs which contained the notes to play. Games that feature music composed with AdLib Visual Composer usually have BNK files as well, although in the case of [[:Category:id Software|id Software]] titles, the two files were converted into [[IMF Format]] during game development. Also this format used by [[Human Machine Interfaces MIDI Format|Human Machine Interfaces]] sound engine for music instruments in HMP and HMI files.

The format can be opened and edited by the Instrument Maker program that came with AdLib Visual Composer.

== File format ==

The file begins with a header:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT8]] || verMajor || Major version number
|-
| [[UINT8]] || verMinor || Minor version number
|-
| [[char]] || signature || "ADLIB-"
|-
| [[UINT16LE]] || numUsed || Number of instrument records in use
|-
| [[UINT16LE]] || numInstruments || Number of instrument records in the file
|-
| [[UINT32LE]] || offsetName || Offset where instrument names begin
|-
| [[UINT32LE]] || offsetData || Offset where instrument data begins
|-
| [[BYTE]][8] || pad || Padded with 0x00
|}

This is followed by a list of instrument names, repeated <tt>numInstruments</tt> times:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT16LE]] || index || Index into data section Calculation: <tt>offsetInstr = offsetData + (index * sizeof(PackedTimbre))</tt>
|-
| [[UINT8]] || flags || 0 if this record is not used, else 1
|-
| [[char]][9] || name || Instrument name - must be NULL-terminated
|}

It's important that it must be sorted by instrument name in alphabetical order to be correctly processed by Ad Lib tools.

At this point, the current position should be the same as <tt>offsetData</tt>. The actual instrument data follows, again repeated once for each instrument. The instrument data is in the following format, which is almost identical to the [[AdLib Instrument Format]] except with only one byte to store each field instead of two.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT8]] || iPercussive || 0: Melodic instrument 1: Percussive instrument
|-
| [[UINT8]] || iVoiceNum || Voice number (percussive only)
|-
| OPLREGS || oplModulator || Register values for the Modulator operator (op 0)
|-
| OPLREGS || oplCarrier || Register values for the Carrier operator (op 1)
|-
| [[UINT8]] || iModWaveSel || Modulator wave select (OPL base register 0xE0)
|-
| [[UINT8]] || iCarWaveSel || Carrier wave select (OPL base register 0xE0)
|}

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| [[UINT8]] || ksl || Key scaling level || 0x40 (bits 6-7) ||
|-
| [[UINT8]] || multiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| [[UINT8]] || feedback || Feedback [op 0 only, op 1 ignored] || 0xC0 (bits 1-3) ||
|-
| [[UINT8]] || attack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| [[UINT8]] || sustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| [[UINT8]] || eg || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| [[UINT8]] || decay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| [[UINT8]] || releaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| [[UINT8]] || totalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| [[UINT8]] || am || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| [[UINT8]] || vib || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| [[UINT8]] || ksr || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| [[UINT8]] || con || Connector [op 0 only, op 1 ignored] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

This structure is almost identical to an individual instrument in [[AdLib Instrument Format]], but with [[UINT8]] fields instead of [[UINT16LE]].

== Human Machine Interfaces version ("Version 0.0")==

{{TODO|Find out more about what is altered and how this version could be worked with.}}

The version of this format associated with HMP/HMI files is altered and incompatible with most tools that work with BNK files. Known differences include:
* The major and minor version numbers in the header are both zero.
* The flags byte in the instrument names list may have values other than 0 or 1, and a null flags byte might not be indicative of an unused sample.
The header and names list otherwise appear to follow the format spec. The instrument data itself has not yet been inspected for differences.

Known examples of games that include files of this version include two possibly standardized file names: DRUMS.BNK and MELODIC.BNK. Dark Legions also includes a BNKDRUM.BNK. All of the known "version 0.0" files are 5,404 bytes in length, with 128 instrument records reported in the header, but have differing contents.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>bankmng.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[AdLib Instrument Format|.ins]]
| canImport = Yes; [[AdLib Instrument Format|.ins]]
| editHidden = No
| editMetadata = No
| notes = Part of ''AdLib Visual Composer'' and ''AdLib Programmer's Manual''
}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{EndFileFormatTools}}

AdLib Instrument Bank Format

2016-07-28T10:11:37Z

Binarymaster: /* File format */ instrument order

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL
| Count = 65535
| Names = Yes, 8 chars
| Games =
{{Game|SkyRoads}}
{{Game|Super Tetris}}
{{Game|Wordtris}}
{{Game|Witchaven}}
{{Game|Witchaven II}}
{{Game|Dark Legions}}
}}
The '''Ad Lib BNK Format''' is an instrument bank file created by the Ad Lib Corporation. It was designed for version 1.5 of ''AdLib Visual Composer'' in 1989, to work in conjunction with [[ROL Format]] music files. It had been discovered that the ~80-byte [[AdLib Instrument Format|individual instrument files]] were actually using closer to 1,024 bytes of disk space each, due to the way the DOS FAT filesystem allocates at least one cluster per file. By combining all the instruments into a single <tt>.bnk</tt> file, disk space could be drastically reduced.

BNK files contain all of the custom instrument data for a set of ROL songs which contained the notes to play. Games that feature music composed with AdLib Visual Composer usually have BNK files as well, although in the case of [[:Category:id Software|id Software]] titles, the two files were converted into [[IMF Format]] during game development. Also this format used by [[Human Machine Interfaces MIDI Format|Human Machine Interfaces]] sound engine for music instruments in HMP and HMI files.

The format can be opened and edited by the Instrument Maker program that came with AdLib Visual Composer.

== File format ==

The file begins with a header:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT8]] || verMajor || Major version number
|-
| [[UINT8]] || verMinor || Minor version number
|-
| [[char]] || signature || "ADLIB-"
|-
| [[UINT16LE]] || numUsed || Number of instrument records in use
|-
| [[UINT16LE]] || numInstruments || Number of instrument records in the file
|-
| [[UINT32LE]] || offsetName || Offset where instrument names begin
|-
| [[UINT32LE]] || offsetData || Offset where instrument data begins
|-
| [[BYTE]][8] || pad || Padded with 0x00
|}

This is followed by a list of instrument names, repeated <tt>numInstruments</tt> times:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT16LE]] || index || Index into data section Calculation: <tt>offsetInstr = offsetData + (index * sizeof(PackedTimbre))</tt>
|-
| [[UINT8]] || flags || 0 if this record is not used, else 1
|-
| [[char]][9] || name || Instrument name - must be NULL-terminated
|}

It's important that it must be sorted by instrument name in alphabetical order to be correctly processed by Ad Lib tools.

At this point, the current position should be the same as <tt>offsetData</tt>. The actual instrument data follows, again repeated once for each instrument. The instrument data is in the following format, which is almost identical to the [[AdLib Instrument Format]] except with only one byte to store each field instead of two.

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT8]] || iPercussive || 0: Melodic instrument 1: Percussive instrument
|-
| [[UINT8]] || iVoiceNum || Voice number (percussive only)
|-
| OPLREGS || oplModulator || Register values for the Modulator operator (op 0)
|-
| OPLREGS || oplCarrier || Register values for the Carrier operator (op 1)
|-
| [[UINT8]] || iModWaveSel || Modulator wave select (OPL base register 0xE0)
|-
| [[UINT8]] || iCarWaveSel || Carrier wave select (OPL base register 0xE0)
|}

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| [[UINT8]] || ksl || Key scaling level || 0x40 (bits 6-7) ||
|-
| [[UINT8]] || multiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| [[UINT8]] || feedback || Feedback [op 0 only, op 1 ignored] || 0xC0 (bits 1-3) ||
|-
| [[UINT8]] || attack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| [[UINT8]] || sustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| [[UINT8]] || eg || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| [[UINT8]] || decay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| [[UINT8]] || releaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| [[UINT8]] || totalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| [[UINT8]] || am || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| [[UINT8]] || vib || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| [[UINT8]] || ksr || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| [[UINT8]] || con || Connector [op 0 only, op 1 ignored] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

This structure is almost identical to an individual instrument in [[AdLib Instrument Format]], but with [[UINT8]] fields instead of [[UINT16LE]].

== Human Machine Interfaces version ("Version 0.0")==

{{TODO|Find out more about what is altered and how this version could be worked with.}}

The version of this format associated with HMP/HMI files is altered and incompatible with most tools that work with BNK files. Known differences include:
* The major and minor version numbers in the header are both zero.
* The flags byte in the instrument names list may have values other than 0 or 1, and a null flags byte might not be indicative of an unused sample.
The header and names list otherwise appear to follow the format spec. The instrument data itself has not yet been inspected for differences.

Known examples of games that include files of this version include two possibly standardized file names: DRUMS.BNK and MELODIC.BNK. Dark Legions also includes a BNKDRUM.BNK. All of the known "version 0.0" files are 5,404 bytes in length, with 128 instrument records reported in the header, but have differing contents.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{EndFileFormatTools}}

XMI Format

2016-07-09T19:41:28Z

Binarymaster: /* TIMB */ timbre array correction

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 1
| Games =
{{Game|The Lost Vikings}}
{{Game|Master of Magic}}
{{Game|SimCity 2000}}
}}
The '''eXtended MIDI file format''' is used by the Miles Sound System (MSS) for storing game music.

== File format ==

The file format is made up of two standard [[Interchange File Format (IFF)]] files one after the other. As there is more than one root-level chunk in the same file, technically the file does not meet the IFF standard which only allows one root-level chunk per file. The chunks are arranged as follows:

* FORM (type XDIR)
** INFO

Immediately following this is another IFF file, which contains a '''FORM''' subchunk for each sequence (song) stored in the XMI file:

* CAT (type XMID)
** FORM (type XMID) - first song
*** TIMB
*** EVNT
** FORM (type XMID) - second song (optional)
*** TIMB
*** EVNT
** etc. for as many songs as needed

It is unknown why the files are arranged as multiple separate IFF files concatenated, rather than one IFF with the same chunk arrangement, but perhaps it is due to a misunderstanding on the part of the format designers of the way the IFF format works.

=== IFF root chunk 1 (FORM:XDIR) ===

The '''FORM''' chunk is of type '''XDIR'''. It contains one subchunk of type '''INFO'''. The contents of the '''INFO''' chunk are as follows:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[INT16LE]] || seqCount || Number of sequences (songs) in the file
|}

=== IFF root chunk 2 (CAT :XMID) ===

This chunk is a simple list, with one '''FORM:XMID''' subchunk for each song in the file, which contains all the information necessary to play that single song. Each '''FORM''' subchunk is further broken up into the following chunks.

==== TIMB ====

The '''TIMB''' chunk stores details about the MIDI patches used in the song. It is used so that normal MIDI patch-change events can set instrument banks at the same time. It has the following structure:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[UINT16LE]] || count || Entry count of the following array
|}

Then it is followed by structure, repeated <tt>count</tt> times:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[UINT8]] || patch || MIDI patch for this instrument number
|-
| [[UINT8]] || bank || MIDI bank for this instrument number
|}

Each entry in the array is repeated once for each instrument in the current track.

The official XMI creation utility (<tt>midiform</tt>) uses MIDI controller <tt>AIL_TIMB_BNK</tt> (114) to set the bank on a given channel, and a standard MIDI program change event to store the patch. These two values (bank and patch) are used to populate an entry in the '''TIMB''' chunk on the next note-on event on the channel.

==== RBRN ====

The optional '''RBRN''' chunk is used to store seek destinations where playback should jump to when encountering a branch event. It is an array of the following structure:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[UINT16LE]] || id || Branch ID, used to select this branch destination
|-
| [[UINT32LE]] || dest || Seek destination for this branch, expressed as a number of bytes since the start of the event data, i.e. 0 means the start of the song. It is important that this points to the start of an event or delay value, otherwise the results will be unpredictable.
|}

It is unknown whether the chunk order is important, however the official XMI creation utility (<tt>midiform</tt>) places this chunk after '''TIMB''' and before '''EVNT'''. If there are no branch points then the chunk is omitted entirely.

<tt>midiform</tt> uses MIDI controller number <tt>AIL_BRANCH_PT</tt> (120) to place branch destination points in a song, with the controller value setting the <tt>id</tt> for that branch point. These controller events are not removed from the MIDI data, so the first event at each branch point is likely to be MIDI controller 120 on some channel. This is just an observation however, and these MIDI controller events are by no means required.

{{TODO|It is unknown how branch points are triggered (whether it is by code or by other MIDI events.)}}

==== EVNT ====

The '''EVNT''' chunk stores the MIDI events to play. There is only one track per song.

The event data is almost in standard MIDI format (as per the data in the [[MID Format]] MTrk chunk), with two important differences.

The first difference is "Note On" event contains 3 parameters - the note number, velocity level (same as standard MIDI), and also duration in ticks. Duration is stored as variable-length value in concatenated bits format. Since note events store information about its duration, there are no "Note Off" events. {{TODO|Provide example}}

The second difference is both store delays as variable-length values, but while standard MIDI stores delays as a series of 7-bit values that are concatenated together to produce the final number, XMI instead stores the values as a series of 7-bit values that are summed to produce the final value.

To further complicate matters, if there is no delay at all, then the delay byte is completely omitted. This means when reading in a byte, the high-bit will need to be inspected to work out whether the byte is the first part of a delay value (high-bit unset) or a MIDI event (high-bit set.) If the high bit is not set, the values should be read and summed until a byte (possibly the first one) is not 127.

For example: (newlines added for clarity only)

C1 71 // C1 has high-bit set so this is a MIDI event
C2 71 // C2 again has high bit set to this is another MIDI event with a delay of zero in between
10 // 10 does not have the high bit set so this is a delay of 10
C3 72 // Another MIDI event
7F 22 // 7F does not have the high bit set so this is a delay, but 7F means there is another delay byte following
// Actual delay is 7F + 22 = A1

There is no limit to the number of 0x7F bytes that may be supplied in a row for long delays, however a reasonable limit should be placed on this to avoid infinite loops in the case of corrupted data.

Note that because of this way of using the high-bit to signal the meaning of the byte (delay vs event), the standard MIDI "running status" is not available as the high-bit is now used for this alternate purpose.

== MIDI controller assignments ==

The following MIDI controllers are given specific meaning when used in XMI files:

{|class="wikitable"
! Controller !! Name !! Description
|-
| 32 || AIL sysex start address MSB (queue 0) || {{TODO|?}}
|-
| 33 || AIL sysex start address KSB (queue 0) || {{TODO|?}}
|-
| 34 || AIL sysex start address LSB (queue 0) || {{TODO|?}}
|-
| 35 || AIL sysex data byte (queue 0) || {{TODO|?}}
|-
| 36 || AIL final sysex data byte (queue 0) || {{TODO|?}}
|-
| 37 || AIL sysex start address MSB (queue 1) || {{TODO|?}}
|-
| 38 || AIL sysex start address KSB (queue 1) || {{TODO|?}}
|-
| 39 || AIL sysex start address LSB (queue 1) || {{TODO|?}}
|-
| 40 || AIL sysex data byte (queue 1) || {{TODO|?}}
|-
| 41 || AIL final sysex data byte (queue 1) || {{TODO|?}}
|-
| 42 || AIL sysex start address MSB (queue 2) || {{TODO|?}}
|-
| 43 || AIL sysex start address KSB (queue 2) || {{TODO|?}}
|-
| 44 || AIL sysex start address LSB (queue 2) || {{TODO|?}}
|-
| 45 || AIL sysex data byte (queue 2) || {{TODO|?}}
|-
| 46 || AIL final sysex data byte (queue 2) || {{TODO|?}}
|-
|colspan=3|
|-
| 58 || AIL rhythm setup timbre || {{TODO|?}}
|-
| 59 || AIL MT-32 patch reverb switch || {{TODO|?}}
|-
| 60 || AIL MT-32 patch bender range || {{TODO|?}}
|-
| 61 || AIL MT-32 reverb mode || {{TODO|?}}
|-
| 62 || AIL MT-32 reverb time || {{TODO|?}}
|-
| 63 || AIL MT-32 reverb level || {{TODO|?}}
|-
|colspan=3|
|-
| 110 || AIL channel lock/release || {{TODO|?}}
|-
| 111 || AIL channel lock protection || {{TODO|?}}
|-
| 112 || AIL voice protection || {{TODO|?}}
|-
| 113 || AIL timbre protection || {{TODO|?}}
|-
| 114 || AIL patch bank select || Select patch bank (see [[#TIMB]] above)
|-
| 115 || AIL indirect controller prefix || {{TODO|?}}
|-
| 116 || AIL loop: FOR loop = 1 to n || {{TODO|Loop start point?}}
|-
| 117 || AIL loop: NEXT/BREAK || {{TODO|Return to last loop start point?}}
|-
| 118 || AIL clear beat/measure count || {{TODO|?}}
|-
| 119 || AIL callback trigger || {{TODO|?}}
|-
| 120 || AIL sequence index || Branch point destination (see [[#RBRN]] above)
|}

== External links ==

* http://www.ke5fx.com/ - homepage of John Miles, original author of the Miles Sound System and designer of the XMI file format

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] from reading the Miles Sound System source code available from John Miles' homepage. 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!)

PAK Format (Westwood)

2016-06-29T20:11:13Z

Binarymaster: Correct name

{{Archive Infobox
| MaxFiles = 65,536
| FAT = Beginning
| Names = Yes, 8.3
| Metadata = None
| Subdirectories = N
| Compressed = N
| Encrypted = N
| Hidden = Y
| Games =
{{Game|Dune II}}
{{Game|Eye of the Beholder}}
{{Game|Lands of Lore: The Throne of Chaos}}
{{Game|The Legend of Kyrandia, Book One}}
{{Game|The Legend of Kyrandia, Book Two: The Hand of Fate}}
{{Game|The Legend of Kyrandia, Book Three: Malcolm's Revenge}}
}}

Westwood's '''PAK Format''' is a simple group file used in their games from 1991-1994. It is efficient in the sense that it only stores file names and starting positions in the header, so file lengths must be inferred. It does not support compression. There are three different versions of the header layouts which are nearly identical and backward-compatible with the previous version. Each update makes it slightly easier to read the header.

* Version 1: Eye of the Beholder 1
* Version 2: Dune II, Legend of Kyrandia 1
* Version 3: Legend of Kyrandia 2, Lands of Lore 1, Legend of Kyrandia 3

== File format ==

=== Signature ===

PAK files have no signature. They are usually given the extension .PAK, but not always.

=== File Entry ===

The header contains a list of files consisting of a 32-bit file offset and a null-terminating file name. Depending on the version, the header ends either when the file pointer equals the offset of the first file (version 1), or when you encounter a file offset of 0 (versions 2 and 3).

{|class="wikitable"
!Data type!!Description
|-
|[[char]] cFilename||File name (8.3 style), null terminated, variable width.
|-
|[[UINT32LE]] iOffset||File's starting offset in the PAK archive.
|}

Each file's size must be calculated by subtracting it from the next file's offset. Version 1 PAK files have a final file offset equal to the size of the file. Version 2 PAK files replace this offset with a end of header flag (0x0000), so the end of the last file must be inferred from the size of the file itself. Version 3 PAK files have an additional file offset with an empty file name (just a null) to determine the size of the last file and then feature a end of header flag (0x0000). Because of this, version 2 PAK files cannot contain hidden files after the last file.

== Source Code ==

This FreeBASIC code will extract all of the files from a version 1, 2, or 3 PAK file into the folder you specify.

<source lang="freebasic">
' This program will extract the files stored in a Westwood PAK file used in various games in the first half of the 1990s.
' There are three versions of the PAK file. Version 1 was used only in Eye of the Beholder 1. To determine the
' end of the header, just wait until the file pointer equals the position of the first file. The last file offset is the
' length of the file. Version 2 was first used in Dune II. It's header ends when the file offset is zero (0x0000).
' Version 3 was first used in The Legend of Kyrandia 2. It has an additional empty file name with a file offset so you
' can easily determine the size of the last file rather than relying on the length of the file, like in version 2.

Dim As String PAKFile = "C:\\Games\\Kyrandia\\dat.pak"
Dim As String ExportFolder = "C:\\Games\\Kyrandia\\dat"

Open PAKFile For Binary As #1

Dim As UInteger FileStart(1000)
Dim As String FileName(1000)
Dim As UInteger Position
Dim As String Char
Dim As UInteger FileCount = 0
Dim As UInteger FileNo
Dim As ULong FileSize
Dim As UInteger ByteNo

' Loop through the header.
Do
' 4-byte file start position.
Get #1, , FileStart(FileCount)

Position = Seek(1)

' Trap for version 2 and 3 PAK files.
If FileStart(FileCount) = 0 Then
Exit Do
Else
' Trap for version 1 PAK files.
If (Position - 1) = FileStart(0) Then
FileCount = FileCount + 1
Exit Do
Else
' Read the file name until we hit a null.
FileName(FileCount) = ""
Do
Char = " "
Get #1, , Char
If Asc(Char) <> 0 Then
FileName(FileCount) = FileName(FileCount) + Char
End If
Loop While Asc(Char) <> 0

FileCount = FileCount + 1
End If
End If
Loop

FileCount = FileCount - 1

MKDir(ExportFolder)

For FileNo = 0 To FileCount
' Read the previous file from the PAK.

' Get the file size.
If FileNo = FileCount Then
' Trap for version 1 and 2 PAK files.
FileSize = LoF(1) - FileStart(FileNo)
Else
FileSize = FileStart(FileNo + 1) - FileStart(FileNo)
End If

Print Using "###) File: \\ \\ Offset: ########,, Size: ########,"; FileNo; FileName(FileNo); FileStart(FileNo); FileSize

' Trap for version 3 PAK files.
If FileSize > 0 Then
' Create a buffer to store the next file.
ReDim As Byte FileData(0 To FileSize)

' Load the file from the PAK into the buffer.
Seek 1, FileStart(FileNo) + 1
For ByteNo = 0 To (FileSize - 1)
Get #1, , FileData(ByteNo)
Next ByteNo

' Save the buffer to the export folder.
Open ExportFolder + "\\" + FileName(FileNo) For Binary As #2
For ByteNo = 0 To (FileSize - 1)
Put #2, , FileData(ByteNo)
Next ByteNo
Close #2
End If
Next FileNo

Close #1

Sleep
</source>

== Tools ==

== Credits ==

This archive format was reverse engineered by [[User:TheAlmightyGuru|TheAlmightyGuru]]. 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!)

ADL Format

2016-06-29T20:08:37Z

Binarymaster: Add Kyrandia 2

{{Stub}}

ADL files are used in the Westwood Studios PC-DOS games to play sound through an adlib compatible sound card.

Each ADL file contains these blocks:
# Song indexes for the following pointer array
# Pointer array for sound/music tracks
# Pointer array for adlib instruments
# Tracks data
# Instruments data

Each pointer in array is relative to the size of primary indexes block.

{| class="wikitable" |
! Game
! Primary Indexes
! Track Pointers
! Instrument Pointers
! First Track Offset
! First Track Absolute Offset
|-
! [[Eye of the Beholder|EOB]]
| 120 (8-bit)
| 150 (16-bit)
| 150 (16-bit)
| 0x258
| 0x2D0
|-
! [[Eye of the Beholder 2|EOB 2]]
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! [[Kyrandia 1]]
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! [[Dune II]]
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! [[Lands of Lore]]
| 250 (16-bit)
| 500 (16-bit)
| 500 (16-bit)
| 0x7D0
| 0x9C4
|-
! [[Kyrandia 2]]
| 250 (16-bit)
| 500 (16-bit)
| 500 (16-bit)
| 0x7D0
| 0x9C4
|}

== Links ==

* [http://www.vgmpf.com/Wiki/index.php?title=ADL ADL page on VGMPF]

ADL Format

2016-06-26T20:13:10Z

Binarymaster:

{{Stub}}

ADL files are used in the Westwood Studios PC-DOS games to play sound through an adlib compatible sound card.

Each ADL file contains these blocks:
# Song indexes for the following pointer array
# Pointer array for sound/music tracks
# Pointer array for adlib instruments
# Tracks data
# Instruments data

Each pointer in array is relative to the size of primary indexes block.

{| class="wikitable" |
! Game
! Primary Indexes
! Track Pointers
! Instrument Pointers
! First Track Offset
! First Track Absolute Offset
|-
! EOB
| 120 (8-bit)
| 150 (16-bit)
| 150 (16-bit)
| 0x258
| 0x2D0
|-
! EOB 2
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! Kyrandia 1
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! Dune II
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x3E8
| 0x460
|-
! Lands of Lore
| 250 (16-bit)
| 500 (16-bit)
| 500 (16-bit)
| 0x7D0
| 0x9C4
|}

==Links==
* [http://www.vgmpf.com/Wiki/index.php?title=ADL vgmpf.com/Wiki/index.php?title=ADL] - Some information on VGMPF.

ADL Format

2016-06-26T17:04:58Z

Binarymaster: Reveal some info

{{Stub}}

ADL files are used in the Westwood Studios PC-DOS games to play sound through an adlib compatible sound card.

Each ADL file contains these blocks:
# Song indexes for the following pointer array
# Pointer array for sound/music tracks
# Pointer array for adlib instruments
# Tracks data
# Instruments data

Each pointer in array is relative to the size of primary indexes block.

{| class="wikitable" |
! Game
! Primary Indexes
! Track Pointers
! Instrument Pointers
! First Track Offset
|-
! EOB
| 120 (8-bit)
| 150 (16-bit)
| 150 (16-bit)
| 0x2D0
|-
! EOB 2
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x460
|-
! Kyrandia 1
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x460
|-
! Dune II
| 120 (8-bit)
| 250 (16-bit)
| 250 (16-bit)
| 0x460
|-
! Lands of Lore
| 250 (16-bit)
| 500 (16-bit)
| 500 (16-bit)
| 0x9C4
|}

==Links==
* [http://www.vgmpf.com/Wiki/index.php?title=ADL vgmpf.com/Wiki/index.php?title=ADL] - Some information on VGMPF.

XMI Format

2016-06-10T22:47:15Z

Binarymaster: /* EVNT */ specific note events

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 1
| Games =
{{Game|The Lost Vikings}}
{{Game|Master of Magic}}
{{Game|SimCity 2000}}
}}
The '''eXtended MIDI file format''' is used by the Miles Sound System (MSS) for storing game music.

== File format ==

The file format is made up of two standard [[Interchange File Format (IFF)]] files one after the other. As there is more than one root-level chunk in the same file, technically the file does not meet the IFF standard which only allows one root-level chunk per file. The chunks are arranged as follows:

* FORM (type XDIR)
** INFO

Immediately following this is another IFF file, which contains a '''FORM''' subchunk for each sequence (song) stored in the XMI file:

* CAT (type XMID)
** FORM (type XMID) - first song
*** TIMB
*** EVNT
** FORM (type XMID) - second song (optional)
*** TIMB
*** EVNT
** etc. for as many songs as needed

It is unknown why the files are arranged as multiple separate IFF files concatenated, rather than one IFF with the same chunk arrangement, but perhaps it is due to a misunderstanding on the part of the format designers of the way the IFF format works.

=== IFF root chunk 1 (FORM:XDIR) ===

The '''FORM''' chunk is of type '''XDIR'''. It contains one subchunk of type '''INFO'''. The contents of the '''INFO''' chunk are as follows:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[INT16LE]] || seqCount || Number of sequences (songs) in the file
|}

=== IFF root chunk 2 (CAT :XMID) ===

This chunk is a simple list, with one '''FORM:XMID''' subchunk for each song in the file, which contains all the information necessary to play that single song. Each '''FORM''' subchunk is further broken up into the following chunks.

==== TIMB ====

The '''TIMB''' chunk stores details about the MIDI patches used in the song. It is used so that normal MIDI patch-change events can set instrument banks at the same time. It is an array of the following structure:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[UINT8]] || patch || MIDI patch for this instrument number
|-
| [[UINT8]] || bank || MIDI bank for this instrument number
|}

This structure is repeated once for each instrument in the file.

The official XMI creation utility (<tt>midiform</tt>) uses MIDI controller <tt>AIL_TIMB_BNK</tt> (114) to set the bank on a given channel, and a standard MIDI program change event to store the patch. These two values (bank and patch) are used to populate an entry in the '''TIMB''' chunk on the next note-on event on the channel.

==== RBRN ====

The optional '''RBRN''' chunk is used to store seek destinations where playback should jump to when encountering a branch event. It is an array of the following structure:

{|class="wikitable"
!Data type!!Name!!Description
|-
| [[UINT16LE]] || id || Branch ID, used to select this branch destination
|-
| [[UINT32LE]] || dest || Seek destination for this branch, expressed as a number of bytes since the start of the event data, i.e. 0 means the start of the song. It is important that this points to the start of an event or delay value, otherwise the results will be unpredictable.
|}

It is unknown whether the chunk order is important, however the official XMI creation utility (<tt>midiform</tt>) places this chunk after '''TIMB''' and before '''EVNT'''. If there are no branch points then the chunk is omitted entirely.

<tt>midiform</tt> uses MIDI controller number <tt>AIL_BRANCH_PT</tt> (120) to place branch destination points in a song, with the controller value setting the <tt>id</tt> for that branch point. These controller events are not removed from the MIDI data, so the first event at each branch point is likely to be MIDI controller 120 on some channel. This is just an observation however, and these MIDI controller events are by no means required.

{{TODO|It is unknown how branch points are triggered (whether it is by code or by other MIDI events.)}}

==== EVNT ====

The '''EVNT''' chunk stores the MIDI events to play. There is only one track per song.

The event data is almost in standard MIDI format (as per the data in the [[MID Format]] MTrk chunk), with two important differences.

The first difference is "Note On" event contains 3 parameters - the note number, velocity level (same as standard MIDI), and also duration in ticks. Duration is stored as variable-length value in concatenated bits format. Since note events store information about its duration, there are no "Note Off" events. {{TODO|Provide example}}

The second difference is both store delays as variable-length values, but while standard MIDI stores delays as a series of 7-bit values that are concatenated together to produce the final number, XMI instead stores the values as a series of 7-bit values that are summed to produce the final value.

To further complicate matters, if there is no delay at all, then the delay byte is completely omitted. This means when reading in a byte, the high-bit will need to be inspected to work out whether the byte is the first part of a delay value (high-bit unset) or a MIDI event (high-bit set.) If the high bit is not set, the values should be read and summed until a byte (possibly the first one) is not 127.

For example: (newlines added for clarity only)

C1 71 // C1 has high-bit set so this is a MIDI event
C2 71 // C2 again has high bit set to this is another MIDI event with a delay of zero in between
10 // 10 does not have the high bit set so this is a delay of 10
C3 72 // Another MIDI event
7F 22 // 7F does not have the high bit set so this is a delay, but 7F means there is another delay byte following
// Actual delay is 7F + 22 = A1

There is no limit to the number of 0x7F bytes that may be supplied in a row for long delays, however a reasonable limit should be placed on this to avoid infinite loops in the case of corrupted data.

Note that because of this way of using the high-bit to signal the meaning of the byte (delay vs event), the standard MIDI "running status" is not available as the high-bit is now used for this alternate purpose.

== MIDI controller assignments ==

The following MIDI controllers are given specific meaning when used in XMI files:

{|class="wikitable"
! Controller !! Name !! Description
|-
| 32 || AIL sysex start address MSB (queue 0) || {{TODO|?}}
|-
| 33 || AIL sysex start address KSB (queue 0) || {{TODO|?}}
|-
| 34 || AIL sysex start address LSB (queue 0) || {{TODO|?}}
|-
| 35 || AIL sysex data byte (queue 0) || {{TODO|?}}
|-
| 36 || AIL final sysex data byte (queue 0) || {{TODO|?}}
|-
| 37 || AIL sysex start address MSB (queue 1) || {{TODO|?}}
|-
| 38 || AIL sysex start address KSB (queue 1) || {{TODO|?}}
|-
| 39 || AIL sysex start address LSB (queue 1) || {{TODO|?}}
|-
| 40 || AIL sysex data byte (queue 1) || {{TODO|?}}
|-
| 41 || AIL final sysex data byte (queue 1) || {{TODO|?}}
|-
| 42 || AIL sysex start address MSB (queue 2) || {{TODO|?}}
|-
| 43 || AIL sysex start address KSB (queue 2) || {{TODO|?}}
|-
| 44 || AIL sysex start address LSB (queue 2) || {{TODO|?}}
|-
| 45 || AIL sysex data byte (queue 2) || {{TODO|?}}
|-
| 46 || AIL final sysex data byte (queue 2) || {{TODO|?}}
|-
|colspan=3|
|-
| 58 || AIL rhythm setup timbre || {{TODO|?}}
|-
| 59 || AIL MT-32 patch reverb switch || {{TODO|?}}
|-
| 60 || AIL MT-32 patch bender range || {{TODO|?}}
|-
| 61 || AIL MT-32 reverb mode || {{TODO|?}}
|-
| 62 || AIL MT-32 reverb time || {{TODO|?}}
|-
| 63 || AIL MT-32 reverb level || {{TODO|?}}
|-
|colspan=3|
|-
| 110 || AIL channel lock/release || {{TODO|?}}
|-
| 111 || AIL channel lock protection || {{TODO|?}}
|-
| 112 || AIL voice protection || {{TODO|?}}
|-
| 113 || AIL timbre protection || {{TODO|?}}
|-
| 114 || AIL patch bank select || Select patch bank (see [[#TIMB]] above)
|-
| 115 || AIL indirect controller prefix || {{TODO|?}}
|-
| 116 || AIL loop: FOR loop = 1 to n || {{TODO|Loop start point?}}
|-
| 117 || AIL loop: NEXT/BREAK || {{TODO|Return to last loop start point?}}
|-
| 118 || AIL clear beat/measure count || {{TODO|?}}
|-
| 119 || AIL callback trigger || {{TODO|?}}
|-
| 120 || AIL sequence index || Branch point destination (see [[#RBRN]] above)
|}

== External links ==

* http://www.ke5fx.com/ - homepage of John Miles, original author of the Miles Sound System and designer of the XMI file format

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] from reading the Miles Sound System source code available from John Miles' homepage. 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!)

MDI Format

2016-01-18T21:40:51Z

Binarymaster: Link to Prehistorik

{{Music Infobox
| Type = MIDI
| Instruments = MIDI
| NumChannels = 16
| NumTracks = 65535
| NumPatterns = 1
| NumOrders = 0
| Tags = Text events
| Games =
{{Game|Dark Ages}}
{{Game|Galactix}}
{{Game|Prehistorik}}
}}

The '''MDI Format''' is a [[MID Format|standard MIDI file]] that contains MIDI meta events for setting OPL instrument settings. It is a way of storing FM/OPL instruments inside a standard MIDI file, with the file being a standard, fully compatible .mid file. Players that are not aware of the FM/OPL commands will simply ignore them and play the file as normal.

The special commands are described in the [[MID Format#0x7F: Manufacturer-specific|manufacturer-specific section of the MID Format article]].

Typically standard MIDI files use the <tt>.mid</tt> filename extension, while files that use the FM/OPL commands are given the <tt>.mdi</tt> extension.

Prehistorik

2016-01-18T21:38:54Z

Binarymaster: Correct link to MDI

{{Game Infobox
| Levels = No
| Tiles = No
| Sprites = No
| Fullscreen = Edit
| Sound = No
| Music = Edit
| Text = No
| Story = No
| Interface = No
}}

[[Prehistorik]] is a platform game.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = Edit
| map = No
| gfx = No
| mus = Edit
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

{{BeginGameFileList}}
{{GameFile
| Name = *.cur *.vga
| Format = [[CUR Format]]
| KnownFormat = Yes
| Desc = Archives storing game data - many of the other files in this list are inside these ones
}}
{{GameFile
| Name = *.dur
| Format = ?
| KnownFormat = No
| Desc = ?
}}
{{GameFile
| Name = *.mat
| Format = ?
| KnownFormat = No
| Desc = Graphics
}}
{{GameFile
| Name = *.mdi
| Format = [[MDI Format]]
| KnownFormat = Yes
| Desc = Background music (<tt>*buz.mdi</tt> are for the "buzzer" - PC speaker)
}}
{{GameFile
| Name = *.pc1
| Format = [[LBM Format]]
| KnownFormat = Yes
| Desc = 320×200 full-screen images
}}
{{GameFile
| Name = *.voc
| Format = [[VOC Format]]
| KnownFormat = Yes
| Desc = Sound effects
}}
{{EndGameFileList}}

Additionally, the following data is contained within <tt>historik.exe</tt>. The filenames are made up for ease of description.

{{BeginGameFileList|header=false|offsets=true}}
{{GameFile
| Offset = 0x21A2E
| Name = level1-1.pre
| Format = [[Prehistorik Level Format]]
| KnownFormat = Partial
| Desc = Level 1, screen 1
}}
{{GameFile
| Offset = 0x21A64
| Name = level1-2.pre
| Format = [[Prehistorik Level Format]]
| KnownFormat = Partial
| Desc = Level 1, screen 2
}}
{{EndGameFileList}}

{{TODO|Add offsets of rest of levels, or find out where they are stored}}
[[Category:Sidescroller]]

Duke 1 Level Format

2015-11-06T16:50:04Z

Binarymaster:

{{Map Infobox
| Type = 2D tile-based
| Layers = 1
| Tile size = 16×16
| Viewport = 208×160
| Games =
{{Game|Duke Nukem}}
}}

The levels in [[Duke Nukem]] 1 are stored in the files <tt>WORLDALx.DNy</tt>, where y is the episode number, and x is the level number, going from 1-9 then A-C. Oddly, level 2 is the intermediate level and level C is the demo level.

Level structure is very simple, each level is 128x90 tiles in size and consists of 11520 UINT16LE words (23040 bytes) of data. Each word controls what appears on one tile in the level. (The level has only one plane, containing background, foreground and enemies. Thus each word is sometimes called a ShapeThing. Because of this limit, the game has some interesting shortcuts to allow things to appear more naturally, such as an enemy tile using the tile before it as its background.) The following values control what appears:

{|class="wikitable"
! Range (hex) !! Class !! Description
|-
| 0000-05FF || Flashers || Animated backgrounds or stationary backdrops, Duke can pass through these.
|-
| 0600-17FF || Backgrounds || Static background objects that Duke can pass through.
|-
| 1800-2FFF || Solids || Static foreground objects that Duke cannot pass through.
|-
| 3000-3059 || Active || This is the fun stuff, all the things that move, such as techbots, bonuses, items, Duke's starting location, hazards (spikes, force fields), doors, keyholes/access slots, conveyor belts and some special effect items (such as mirror floor and transparent windows).
|-
| 306A-FFFF || (Hacks) || Static foreground objects that Duke cannot pass through. The first tiles use tile images from BORDER.DN? and most of the later tiles are displayed as random junk. All of these tiles are clingable.
|}

== Tile mapping ==

The Level's tiles use tile graphics from 8 files: <tt>BACK0.DN?</tt> through <tt>BACK3.DN?</tt> and <tt>SOLID0.DN?</tt> through <tt>SOLID3.DN?</tt>. Tiles from <tt>BORDER.DN?</tt> can also be used, though they are not "officially" supported.

Each file contains 48 tiles (at least the game loads 48 tiles from each file), so there are 384 "actual" tiles. Due to the way the tile graphics are stored in memory, you need to divide the tile value by 32 (EGA plane size of a 16x16 pixel tile) to get a tile index from the data stored in the level file.

{|class="wikitable"
! Range (hex) !! File
|-
| 0000-05FF || BACK0.DN?
|-
| 0600-0BFF || BACK1.DN?
|-
| 0C00-11FF || BACK2.DN?
|-
| 1200-17FF || BACK3.DN?
|-
| 1800-1DFF || SOLID0.DN?
|-
| 1E00-23FF || SOLID1.DN?
|-
| 2400-29FF || SOLID2.DN?
|-
| 2A00-2FFF || SOLID3.DN?
|-
| 3000-367F || Varies, see below
|-
| 4000-? || current backdrop 1 (hack)
|-
| 8100-? || current backdrop 2 (hack)
|}

=== Active ===

The follow tiles appear to be manually mapped. These tile codes from the map do not need to be divided by 32, unlike the other tilecodes.

{|class="wikitable"
! Tile code (hex) !! File !! Tile index !! Type !! Description
|-
| 3000 || OBJECT0.DN1 || 0 || Bonus || Grey box, empty
|-
| 3001 || OBJECT0.DN1 || 5 || Interactive || Elevator
|-
| 3002 || {{TODO|?}} || ? || Interactive || Left-moving conveyor belt start, must be left of end tile
|-
| 3003 || {{TODO|?}} || ? || Interactive || Left-moving conveyor belt end, must be on right of start tile
|-
| 3004 || {{TODO|?}} || ? || Interactive || Right-moving conveyor belt start, must be left of end tile
|-
| 3005 || {{TODO|?}} || ? || Interactive || Right-moving conveyor belt end, must be on right of start tile
|-
| 3006 || OBJECT0.DN1 || 10 || Bonus || Grey box (0 @ OBJECT0.DN1), contains shoes
|-
| 3007 || OBJECT0.DN1 || 11-17 || Interactive || Rocket, tile below is replaced with default tile after rocket takeoff
|-
| 3008 || OBJECT0.DN1 || 24-28 || Hazard || Flamethrower, firing to the right (three tiles wide including placement tile)
|-
| 3009 || OBJECT0.DN1 || 18 || Bonus || Grey box (0 @ OBJECT0.DN1), contains helmet {{TODO|Is this really a helmet?}}
|-
| 300A || OBJECT0.DN1 || 29-33 || Hazard || Flamethrower, firing to the left (three tiles wide including placement tile)
|-
| 300B || ANIM0.DN1 || 0-5 || Enemy || Floating 1x1 robot with purple antenna
|-
| 300C || ANIM0.DN1 || 10-33 || Enemy || Jumping 2x2 robot
|-
| 300D || ANIM0.DN1 || 34-41 || Enemy || Wheeled 2x1 robot with blue wheels
|-
| 300E || ANIM1.DN1 || 0-31 || Enemy || 2x2 rotating wheel with flames
|-
| 300F || OBJECT0.DN1 || 43 || Bonus || Grey box (0 @ OBJECT0.DN1), contains raygun (ammo)
|-
| 3010 || ANIM1.DN1 || 32 || Enemy || 1x1 robot
|-
| 3011 || - || - || - || Exit door (only 1 instance allowed!)
|-
| 3012 || ANIM2.DN1 || 17 || Bonus || Grey box (0 @ OBJECT0.DN1), contains dynamite
|-
| 3013 || ANIM2.DN1 || 24-31 || Enemy || Flying orb monster, each shot removes one orb
|-
| 3014 || - || - || Decorative || Shimmering water effect, also affects tile below this one
|-
| 3015 || ANIM2.DN1 || 32-35 || Bonus || Red box (1 @ OBJECT2.DN1), contains soda can
|-
| 3016 || ANIM2.DN1 || 40-43 || Enemy || Green bitey creature walking up and down walls, facing right
|-
| 3017 || ANIM2.DN1 || 44-47 || Enemy || Green bitey creature walking up and down walls, facing left
|-
| 3018 || OBJECT0.DN1 || 44 || Bonus || Red box (1 @ OBJECT2.DN1), contains turkey drumstick
|-
| 3019 || ANIM3.DN1 || 0 || - || Bridge that explodes when stepped on twice (only 1 instance allowed!)
|-
| 301A || OBJECT1.DN1 || 0-3 || Hazard || Blue force field, horizontal
|-
| 301B || ANIM3.DN1 || 12-19 || Hazard || Rotating fan blades, can't stand on when shot
|-
| 301C || ANIM3.DN1 || 12-19 || Hazard || Rotating fan blades, can stand on when shot
|-
| 301D || OBJECT1.DN1 || 8 || Bonus || Blue box (0 @ OBJECT2.DN1), contains football
|-
| 301E || OBJECT1.DN1 || 9 || Bonus || Blue box (0 @ OBJECT2.DN1), contains joystick
|-
| 301F || OBJECT1.DN1 || 10 || Bonus || Blue box (0 @ OBJECT2.DN1), contains "DN" floppy
|-
| 3020 || OBJECT1.DN1 || 13 || Bonus || Grey box (0 @ OBJECT2.DN1), contains robohand
|-
| 3021 || OBJECT1.DN1 || 15-18 || Hazard || White/blue force field, vertical
|-
| 3022 || ANIM3.DN1 || 20-47 || Enemy || Helicopter
|-
| 3023 || OBJECT1.DN1 || 19-23 || Bonus || Blue box (0 @ OBJECT2.DN1), contains balloon
|-
| 3024 || ANIM4.DN1 || 8-10 || Bonus || Security camera
|-
| 3025 || ANIM4.DN1 || 11 || Decorative || Brown spikes
|-
| 3026 || ANIM4.DN1 || 12 || Decorative || Rock, left half
|-
| 3027 || ANIM4.DN1 || 13 || Decorative || Rock, right half
|-
| 3028 || ANIM4.DN1 || 14 || Decorative || Grey rounded window
|-
| 3029 || OBJECT1.DN1 || 24 || Bonus || Grey box (0 @ OBJECT0.DN1), contains nuclear molecule
|-
| 302A || OBJECT1.DN1 || 33 || Hazard || Loose/falling ACME sign, left half
|-
| 302B || OBJECT1.DN1 || 34 || Hazard || Loose/falling ACME sign, right half
|-
| 302C || OBJECT1.DN1 || 45-46 || Hazard || Spike, pokes up when walking over
|-
| 302D || OBJECT1.DN1 || 47-49 || Bonus || Blue box (0 @ OBJECT2.DN1), contains magenta flag
|-
| 302E || OBJECT2.DN1 || 2-4 || Bonus || Blue box (0 @ OBJECT2.DN1), contains radio
|-
| 302F || ANIM4.DN1 || 20-28 || Interactive || Teleporter, transports to tilecode 3030
|-
| 3030 || ANIM4.DN1 || 20-28 || Interactive || Teleporter, transports to tilecode 302F
|-
| 3031 || ANIM4.DN1 || 31 || Hazard || Spiky round red bomb, bouncing
|-
| 3032 || - || - || Interactive || Player start point
|-
| 3033 || OBJECT1.DN1 || 14 || Bonus || Grey box (0 @ OBJECT0.DN1), contains access card
|-
| 3034 || OBJECT2.DN1 || 5-12 || Interactive || Access card activation point
|-
| 3035 || OBJECT2.DN1 || 14-15 || Interactive || Robohand activation point
|-
| 3036 || {{TODO|?}} || ? || ? || Red girder, creates a bridge when Robohand activation point is used
|-
| 3037 || OBJECT2.DN1 || 21 || Bonus || Grey box (0 @ OBJECT0.DN1), contains "D"
|-
| 3038 || OBJECT2.DN1 || 21 || Bonus || Grey box (0 @ OBJECT0.DN1), contains "U"
|-
| 3039 || OBJECT2.DN1 || 21 || Bonus || Grey box (0 @ OBJECT0.DN1), contains "K"
|-
| 303A || OBJECT2.DN1 || 21 || Bonus || Grey box (0 @ OBJECT0.DN1), contains "E"
|-
| 303B || ANIM2.DN1 || 18-23 || Bonus || Purple rabbit thing, 5000 bonus points
|-
| 303C || ANIM5.DN1 || 1 || Enemy || Fire monster
|-
| 303D || ANIM5.DN1 || 12 || Decorative || Diamond-shaped wire mesh
|-
| 303E || ANIM5.DN1 || 13 || Decorative || Window showing through to backdrop, left half
|-
| 303F || ANIM5.DN1 || 14 || Decorative || Window showing through to backdrop, right half
|-
| 3040 || OBJECT2.DN1 || 23 || Interactive || Message, press up to read (blank message for most levels?)
|-
| 3041 || - || - || - || Screen display with Dr. Proton
|-
| 3042 || ANIM5.DN1 || 30-42 || Enemy || Dr Proton, E3 boss, killable ("I won it all!", game ends)
|-
| 3043 || ANIM5.DN1 || 30-42 || Enemy || Dr Proton, E1 boss, not killable (escapes to moon, game ends)
|-
| 3044 || OBJECT2.DN1 || 24 || Interactive || Door key, red
|-
| 3045 || OBJECT2.DN1 || 25 || Interactive || Door key, green
|-
| 3046 || OBJECT2.DN1 || 26 || Interactive || Door key, blue
|-
| 3047 || OBJECT2.DN1 || 27 || Interactive || Door key, magenta
|-
| 3048 || OBJECT2.DN1 || 37 || Interactive || Door lock, operated by red key
|-
| 3049 || OBJECT2.DN1 || 38 || Interactive || Door lock, operated by green key
|-
| 304A || OBJECT2.DN1 || 39 || Interactive || Door lock, operated by blue key
|-
| 304B || OBJECT2.DN1 || 40 || Interactive || Door lock, operated by magenta key
|-
| 304C || OBJECT2.DN1 || 28 || Interactive || Door, opened by red lock
|-
| 304D || OBJECT2.DN1 || 28 || Interactive || Door, opened by green lock
|-
| 304E || OBJECT2.DN1 || 28 || Interactive || Door, opened by blue lock
|-
| 304F || OBJECT2.DN1 || 28 || Interactive || Door, opened by magenta lock
|-
| 3050 || OBJECT1.DN1 || 8 || Bonus || Football
|-
| 3051 || OBJECT0.DN1 || 44 || Bonus || Turkey drumstick
|-
| 3052 || ANIM2.DN1 || 32-35 || Bonus || Soda can
|-
| 3053 || OBJECT1.DN1 || 10 || Bonus || "DN" floppy disk
|-
| 3054 || OBJECT1.DN1 || 9 || Bonus || Joystick
|-
| 3055 || OBJECT1.DN1 || 47-49 || Bonus || Purple flag
|-
| 3056 || OBJECT2.DN1 || 2-4 || Bonus || Radio
|-
| 3057 || ANIM4.DN1 || 31 || Hazard || Spiky round red bomb, stationary, explodes on touch
|-
| 3058 || OBJECT2.DN1 || 48 || Hazard || Spikes, poking up
|-
| 3059 || OBJECT2.DN1 || 49 || Hazard || Spikes, poking down
|}

== Links ==

There are numerous level editors available, from the basic original ASCII one, to rather advanced ones capable of rendering animations.

* Maps can be found at [http://vgmaps.com/Atlas/PC/index.htm#DukeNukem vgmaps.com]
* The original level editor is at [http://archive.shikadi.net/sites/www.geocities.com/dooknookimklassik/ Dook Nookim Klassik]
* A reasonable level editor can be found at [http://crystalshard.net/?p=8&s=51 crystalshard.net]
* Possibly the best editor is DN1MOD, which renders levels as the game does, by loading the game's graphics files [http://archive.shikadi.net/sites/members.iinet.net.au/~markim/admiral_bob/files/]

Dave 2 Intro format

2015-04-23T06:10:04Z

Binarymaster:

The <tt>INTRO.DD2</tt> file stores a masked image used at the start of [[Dangerous Dave 2]]. It differs in format and compression from all other files used in the game.

The file is a 256x64 [[Raw EGA data]] image compressed using [[RLEW compression]] The color dark blue is transparent here, acting as a mask while only needing 4 EGA planes.

==Notes==

Dave 2 uses a trigonometric function to work out the image's size and co-ordinates when displaying it.
Format reverse engineered by [[User:Napalm]] and [[User:Levellass]]

[[Category:Dangerous Dave 2]]
[[Category:File Formats]]
[[Category:Graphics Files]]

ADL Format

2015-01-31T13:59:38Z

Binarymaster: Mark as a stub; add links

{{Stub}}

ADL files are used in the PC-DOS version of EOB1&2 to play sound through an adlib compatible sound card.

For EOB2:
Offset:
#x0000: 120 bytes which are indices for the following pointer array
#x0078: 250*16bit pointers for sound/music tracks
#x026C: start of configuration data for adlib instruments
#x????: tracks

EOB1 ADL files are adlib.dat and sound.dat. The difference to EOB2 is the size of the pointer array for tracks which is here 300 bytes instead of 500.

==Links==
* [http://www.vgmpf.com/Wiki/index.php?title=ADL vgmpf.com/Wiki/index.php?title=ADL] - Some information on VGMPF.

User talk:Malvineous

2015-01-25T12:02:01Z

Binarymaster:

== Wolfenstein 3D -> Wolfenstein 3-D ==
I've corrected the infamous 3D tyop in the names of several Wolf3D-related pages; can you please delete the following ones?

[[:Category:Wolfenstein 3D]] -> Superseded by [[:Category:Wolfenstein 3-D]] 
[[:Image:Wolfenstein_3D.png]] -> Superseded by [[:Image:Wolfenstein_3-D.png]]

Thanks :) --De Zeurkous (zeurkous@zeurcomp.nichten.info), Thu Nov 22 08:18:42 UTC 2007

:Haha, you've certainly been busy. Don't forget that this wiki isn't meant to be an encyclopaedia of the games, its main purpose is documenting the file formats and editing tools that can be used with the games, as opposed to how the games behave without any mods, or what they might be called if you forget to change the title screen :-) -- [[User:Malvineous|Malvineous]] 11:14, 22 November 2007 (GMT)

::Nah, I haven't forgotten. As we're reinventing the wheel for a semi-virgin wiki, the naming and something static like the cheats seemed like a good place to start :) --De Zeurkous (zeurkous@nichten.info), Thu Nov 22 12:20:04 UTC 2007

== Jill of the Jungle palette ==

Hi, I'm currently working on a level viewer for [[Jill of the Jungle]] (maybe an editor later on). Some of the information I found here has been very useful, but there's one thing I'm a bit stuck on. On the [[SHA Format]] page it says:
:''Each array item contains 4 unsigned bytes, representing CGA, EGA and VGA, respectivley, and then a null value. [...] Each byte maps to the index of a colour in the palette. If there are no colours required, the tile set uses the default colours.''
However, it doesn't say anywhere where the palette can be found. Is it stored in the EXE file? I hope you can help me on this :)

Regards, [[User:Spinal|Spinal]] 13:00, 2 March 2008 (GMT)

:Unfortunately I didn't write the JotJ SHA page, and I haven't yet had the time to figure this out. For Xargon I've taken the quick and dirty route and used a screenshot from within DOSBox as the source of the palette, until I can figure out where the palette is located. If you find this out, don't forget to update the page! :-) -- [[User:Malvineous|Malvineous]] 22:02, 2 March 2008 (GMT)

::Hey Spinal, sorry, I wrote the [[SHA Format]] page, so that was probably my bad. I wasn't able to find the palette either. I assume it's in the .EXE, however I spent a fair bit of time manually mapping it using a Wombat tool (http://www.szevvy.com/node/3). I was also writing a level viewer (initally in XHTML which turned out to be too slow, so then I moved to Flash 9). I tried to email you my findings, but the email bounced. I'm not sure if they were 100% accurat, which is why I never added them to the documentation.

::Hey Malvineous, it seems the Jill - [[DMA Format]] page has been removed. Do you have a log of what happened to it? I'm sure it existed at some point.

::- [[User:dheim|Daniel]] 20:00, 5 March 2008

:::I don't ever remember seeing a DMA page - certainly there's nothing in the wiki logs about it being deleted or renamed. Maybe you started working on it but never got around to saving it? Or is it one of the Xargon pages that shares the same format as Jill? (by the way, you can type <nowiki>~~~~</nowiki> to automatically put in the signature in these messages.) -- [[User:Malvineous|Malvineous]] 11:28, 5 March 2008 (GMT)

::::Sorry, it must have been the stuff in the [[SHA Format]] page that I was thinking of. I may have added the link to the [[DMA Format]] page, and never expanded on it. - [[User:Dheim|Daniel]] 02:46, 6 March 2008 (GMT)

:::::Hi guys. Sorry for the mistake, I mixed up the authors of the SHA and level formats. I've written a level viewer in PHP the last week, by using static images instead of getting them from the actual files. This causes some problems for episode 2, which uses a different palette, but besides that it works great :) When everything is done I'll upload the maps to my server and the tile/object lists to this wiki.
:::::@Daniel: strange that it bounced, I confirmed my address so it should be working fine... You can mail it to spinal -at- zanderz -dot- net. Also, I saw on your Wombat page that you "have a vague idea of how to do" [[Hocus Pocus]]. Could you share your findings on this wiki? I'd love to make maps, or even a level viewer/editor for that game :) -- [[User:Spinal|Spinal]] 00:32, 8 March 2008 (GMT)
:Okay, with help of [[User:Dheim|Daniel]] who send me the palette I found it! I'll put my findings on [[Jill of the Jungle palette]]. -- [[User:Spinal|Spinal]] 15:36, 13 March 2008 (GMT)

== Halloween Harry/Alien Carnage ==

Hi Malvineous. Thanks for your edits on the GMF article! I notice you mentioned there exist versions of the game which don't require exploding a BNK to get at the game data. What does the directory structure look like for the version you have? I'm working on a map viewer (which will become a map editor at some point) and would like it to be able to work on whatever versions are out there. Thanks for any info. -[[User:Duckthing|Duckthing]] 04:41, 11 December 2010 (GMT)

: Hi Duckthing - no worries, Halloween Harry has long been an interest of mine, but my map editor sadly needs a lot more work before I can begin reverse engineering more file formats so I'm glad you've made a start! AFAIK technically Halloween Harry has no compression, but for whatever reason (probably listed in the Apogee FAQ) they decided to swap episodes 1 and 3, compress the BNK file and then re-release it under the name Alien Carnage. You can download all available versions (including registered versions since the game was released as freeware in 2007) from [http://www.classicdosgames.com/game/Alien_Carnage.html RGB Classic Games]. BTW not sure if you noticed but I also posted a couple of things on the GMF article's talk/discussion page. -- [[User:Malvineous|Malvineous]] 06:08, 11 December 2010 (GMT)

:: Thank you! Working with the uncompressed version will keep things less complicated. I did notice the GMF discussion you added, but haven't had a chance to really go through it yet. -- [[User:Duckthing|Duckthing]] 06:41, 11 December 2010 (GMT)

::: No worries. If you're running Linux or MacOSX you should be able to compile [[Camoto|libgamearchive]] which will let you copy files in and out of the BNK files. This is a library so it's also possible to use it in your own program for accessing and editing the map files while they're still inside the BNK, for instance. (BTW the 'minor' tickbox should only be used when the edit does not affect the information on the page - e.g. fixing a typo or a broken URL. If you are changing the actual content on a page it is never a minor edit!) -- [[User:Malvineous|Malvineous]] 07:51, 11 December 2010 (GMT)

== Dangerous Dave ==

Working on this, does anyone have any info on the formats? The EGA graphics are 84KB and external, but CGA and VGA graphics unrelated to them are in the 174KB executable, apparently uncompressed, I don't know how this is possible. I've found the levels and partially reverse engineered the format (The first 1000 bytes, a 100x10 array of tiles.) but each level is followed by ~280 bytes of variable and unknown data I assume is sprites. I have a list of internal files in the executable, looks like most of it is non-game code. Any help would be appreciated. -[[User:Levellass|Endian? What are you on about?]] 06:03, 12 December 2010 (GMT)

: Hmm, interesting. All I can suggest for the levels is - as you're probably already familiar with - changing the values in a hex editor then loading the game to see what happens. I would suspect that all the graphics would be in a similar format, so if there are any headers or structures used in the EGA graphics files perhaps they're duplicated for CGA/VGA? Also John Romero seems pretty accessible, perhaps you could ask him directly? Failing that, randomly writing data into the .exe until the images change could be used as a last resort! -- [[User:Malvineous|Malvineous]] 12:09, 12 December 2010 (GMT)

: Ha, that was easier than I expected - uncompressed VGA data is easy to find with a good hex editor ;-) [http://www.shikadi.net/pics/ddave-vga-hexdump.png This looks like it] -- [[User:Malvineous|Malvineous]] 12:17, 12 December 2010 (GMT)

: Ok that was only the menu graphics. At offset 0xC629 there's some sort of offset table which looks very similar to the contents of EGADAVE.DAV but there are extra bytes dotted all over the place - perhaps it's RLE encoded? Actually just before that there's the number 0x6CAA. If you go a bit less than 0x6CAA bytes after this you end up with another table, which to me suggests that 0x6CAA is the decompressed size of that first table. -- [[User:Malvineous|Malvineous]] 13:01, 12 December 2010 (GMT)

:If I remember it correctly, the VGA sprites and tiles are RLE compressed and it's not too hard to decompress them. The positions of the enemies in the levels on the other hand are still a mystery to me. [[User:Calvero|Calvero]] 20:43, 12 December 2010 (GMT)

: Looking at the levels, which directly follow the VGA palette, they seem to contain 256 bytes of header data, then the 100x10 tiles, then eight bytes of lead-out data. Then the next level's 256 bytes of header, 100x10 tiles, then eight bytes of lead-out. Although I say "level", the first "level" seems to contain both level 1 and 2, and this seems to be the way it works in the game - in some levels you can see through to others. I'm not sure what the 256 bytes of header data are for, but some levels have FF FF 00 00 repeated which seems to indicate two uint16 fields which are blanked out for those levels. -- [[User:Malvineous|Malvineous]] 13:15, 13 December 2010 (GMT)

::First up, levels; where does level 1 start? It's possible I'm reading the start of a level as the previous level's end, I looked for the start of tile data, which I assumed, like Keen 1, would be the level start.

::Next, palette; I'm assuming, as you said, it is located just before the level data?

::There is VGA and CGA graphics in the executable, plus headers, but the bulk of graphics for CGA and VGA I haven't been able to locate. If the data is RLE compressed I should think it would use either Keen 1-3 fullscreen or Jazz Jackrabbit tile RLE, both of which I know well. I'll look into both of these options, cheers! -[[User:Levellass|Endian? What are you on about?]] 12:03, 20 December 2010 (GMT)

:::I've found the VGA and CGA data for the menu graphics. It looks like the CGA data is stored in a series of 1-bit-per-pixel (monochrome) images. Or it could be EGA data with the planes split out (e.g. red plane for all images, then green plane for all images, etc.) I think I found three planes which means it's probably EGA, as CGA would have a max of two planes. I've also found the font graphics, this looks like 4bpp/16 colour EGA data. Haven't seen level graphics yet. I've successfully modded the levels with a hex editor (putting the jetpack everywhere) so now I've finally looked at all the levels! The creatures are definitely not stored in the 100x10 tile data. Putting random bytes in there revealed that the values are indices into the image files, because if you put the value in for fire it will animate, and the following three or so values show up as still frames from the fire animation.

:::The VGA palette starts at 0x26B0A (I updated the main DDave page with this) + 768 bytes leads straight onto the start of level 1 at 0x26E0A. So at 0x26E0A there are 256 bytes of data, then 100x10 tiles, then 24 bytes of footer data. Some of this data (perhaps footer data) might be the level start coordinates, because Dave doesn't always start the level at the same place (e.g. the warp level when you climb the tree on level 5 and jump off the edge of the screen.) -- [[User:Malvineous|Malvineous]] 12:24, 20 December 2010 (GMT)

:::I think I've found all the files so far, I've updated [[Dangerous Dave]] with the offsets of the files, including what appears to be CGA and VGA tiles. I'm not sure what sort of format they're in though, it looks like they might be compressed (and so the offsets in that list might be off by ~4, as I may have cut off the decompressed-size field.) I've also updated the map format page, I think it's pretty much fully reverse engineered now. -- [[User:Malvineous|Malvineous]] 05:13, 21 December 2010 (GMT)

== Noahs Ark 3D and IMFs ==

Been poking around Noah's Ark 3D, an adaption of the Wolfenstein game and found a few interesting things which I'm hoping to confirm.

First, the game uses MID files, not IMF files for music, second, the MIDI files have an extra word at the start of the file giving the file length. Third, the code uses the first word of the midi file as the length of data to read from the file and put into memory to play. After poking around a bit in Wolfenstein and Keen I believe this is the same with IMF files, that is, ALL IMF files are type 0 as it were and the type 1s are read just like type 0s by the games (The first word is read as the amount of IMF data to copy into memory to play, this is then read as type 0.) I'm not quite sure what this does for the two types since type 1 is would essentially be a type 0 with a header and footer that are part of the AUDIO.xxx format, much like PC\adlib sounds can have the huffman lengths at the start. Are there any games that use 'individual' type 1 IMFs (Even if included as part of a group file. All I've seen are games like cosmo, where non-AUDIO IMFs are type 0.)

Should there be a Noah's Ark 3D page and should we add the midi note to the AUDIO format page? It seems that the format can hold any type of music file the game can read, not just IMFs. -- Levellass

: Yes it is known that the type-1 header might really be part of the AUDIO.xxx format but alas there were many type-1 files floating around the place (incorrectly extracted, you could argue) before this was realised, so the format variant is here to stay. It does have some advantages though (like tagging files with the song title) but I'm not sure whether anyone has figured out definitively whether the header (and footer, in the case of the Wolf3D files) belongs to the IMF or the AUDIO file. I guess you'd have to browse the game source code and see how the game uses the data to know for sure.

: As far as the MIDI goes, I believe the AUDIO.xxx file is just a container file like any other, capable of supporting any data at all. It's up to the game to decide how to use it. If anything this makes me think it would fit better if the AUDIO.xxx article was merely documenting the structure, with links to actual audio formats like PC SFX, Adlib SFX, IMF and MIDI and notes about which games make use of which formats.

: Oh and yes, by all means create a page for the new game. -- [[User:Malvineous|Malvineous]] 08:41, 3 February 2011 (GMT)

== Sound Files category ==

I don’t know why there’s a Sound Files category and also an Audio Files category... it seems redundant. I left those categories the way they are though.

Also, the [[File format data types]] page needs some signed ints, but I didn’t know what naming convention you wanted to use. I described something as an [[INT16LE]] on [[BMC Format]]. [[User:Yellowantphil|Yellowantphil]] 20:12, 11 September 2011 (GMT)

: Not sure about the Sound vs Audio - I use the term 'audio' to mean both sound and music, but you're right, if there are separate sound and music categories we don't really need an audio one as well. Feel free to update. [[INT16LE]] is perfectly fine too! I added a note to the data types page. -- [[User:Malvineous|Malvineous]] 22:30, 11 September 2011 (GMT)

== GamePage template ==

Should the GamePage template add the page to its own category? It seems a little odd that [[Wacky Wheels]] is not in the Wacky Wheels category. [[User:Yellowantphil|Yellowantphil]] 04:51, 16 September 2011 (GMT)
: I decided against this because there is a link to the game's page in the category intro at the top of the page. It seemed unnecessary having another link in amongst all the other pages. This was also because the game page was really only meant to be a summary, there wasn't supposed to be a huge amount of detail on it, only links to other pages with the detail (which then would appear in the category list.) I would imagine that, eventually, [[Wacky Wheels]] would be tweaked to move a lot of the content onto subpages. -- [[User:Malvineous|Malvineous]] 12:58, 16 September 2011 (GMT)

== Scope of the wiki ==

I don’t know how extensive you want the information to be on ModdingWiki... I added a few lists of audio and graphics files a while ago, and there will probably be other information that I’ll find out that’s potentially helpful for level editing but not directly related to it. I can move some information to my website if it starts to become out of scope for your wiki. I also sometimes end up documenting everything imaginable... there’s some minutiae on my website and possibly on your wiki that I ought to go through and delete. [[User:Yellowantphil|Yellowantphil]] 05:28, 10 October 2011 (GMT)

:Hmm, that's a difficult one - I'm always in favour of documenting more rather than less. Generally speaking if it's related to a game and it would help either a programmer writing a utility or a someone trying to change a game manually then it should be documented. About the only thing that comes to mind that's over documenting is when some small calculation is expressed in a couple of different programming languages, but I've left that in so people can just copy it rather than trying to figure it out from the text. But the [[Wacky Wheels]] page is probably the gold standard for what all wiki pages should look like :-) Do you have anything in particular you're unsure of whether it would fit here? -- [[User:Malvineous|Malvineous]] 10:07, 10 October 2011 (GMT)

::I was mainly thinking of the list of VOC files on [[Wacky Wheels Music and Sound Effects]] and the list of <tt>*.sp</tt> files on [[Wacky Wheels Graphics Formats]]. I have an expanded list of the <tt>*.sp</tt> files on my computer but it isn’t finished yet. I guess there isn’t all that much more Wacky Wheels information to be added to this wiki though. There is still some modding information on my website that ought to be moved over here, so that would take up another page or two. I’ve been lazy about doing Wacky Wheels stuff lately, but I might find some time for it this weekend.

::By the way, I guess that guy from Cascadia Games emailed you. It’s pretty interesting that WW might become an iPhone app. He told me that he was going to be using his own game engine, which sounds a lot easier than trying to get a hold of the WW source code and porting it. —[[User:Yellowantphil|Yellowantphil]] 16:46, 15 October 2011 (GMT)

::: I was going to say the list of VOCs might be overkill, but then the list of .sp files might be useful. To be honest, it's the sort of thing that you could probably omit if you were feeling lazy, but likewise I don't mind at all if you choose to include it, so since it's already there I'm happy to keep it.

::: Yes I did get an e-mail from Cascadia, I was going to pass along your details but it sounds like you're already aware of it! Using their own engine might make it a bit smoother than the original, as the jerkiness of turning is my only criticism of the game. -- [[User:Malvineous|Malvineous]] 00:14, 16 October 2011 (GMT)

== Wacky Wheels ==

Basically all of the WW modding information from my website is here now. I moved one page when I realized it should probably be capitalized to match the rest of the pages on this site... you can delete the redirect at [[Wacky Wheels high score files]] if you want to.

Now, I need to remove most of the modding information from my website and refer people here. Then we’ll have reached the glorious future where all WW modding information is in one place. I’m going to keep those two text files of notes on my website though—the information in them is disorganized and I think not 100% accurate, but they might have some information that isn’t here yet.

By the way, how’s Camoto going? I’m planning to use it to make a new WW level, but I won’t have time for it for a few more months. —[[User:Yellowantphil|Yellowantphil]]

: Sounds good! Thanks for all the effort you've put in by moving it across. I think Wacky Wheels is now the most completely documented game on the wiki! Also can't hurt leaving your own info up - sometimes it's nice to go back to the original source if something is unclear. Camoto's going well, but unfortunately I haven't had much time to work on it over the last few weeks. You probably won't be able to make much of a level until I add in the ability to select a tile from the tileset, but that's in progress and hopefully will be ready by the time you are! Keep me posted when you do start your level(s?) -- [[User:Malvineous|Malvineous]] 12:22, 2 February 2012 (GMT)

::Well, as I was reading some of the information on my website, I noticed that it isn’t written very well. I wrote those pages back when I had very little experience programming. Anyway, I’m planning to redesign my website soon, and this will save me from having to rewrite a few of those pages.

::The tile editor in Camoto as it is now is still certainly useful—I can add new tile types to a level using a binary editor and then move them around in Camoto. I think that it shouldn’t be too hard to make a new WW level using the Gimp and Camoto plus some binary editing. I recall having some problems with the route editor for the computer players, but I didn’t look into it at the time—I’ll let you know when I’m working with Camoto again, and I’ll try to come up with some useful bug reports or fixes if I run into problems. —[[User:Yellowantphil|Yellowantphil]] 14:06, 2 February 2012 (GMT)

== Catacomb ==

Hey [[User:Malvineous|Malvineous]], do you know anyone who has properly read the [[Inverse_Frequency_Sound_format|Inverse Sound Frequency]] file format and got the sound playing? I'm struggling with some fine details in my game. Sounds play near what they should sound like, but the sound quality is all crackly and some sounds play totally incorrect. I followed a basic [http://web.archive.org/web/20000818033701/http://www.dd.chalmers.se/~f98anga/projects/keen/sounds2raw.c code sample] by Anders Gavare. Does your tool support this? Interested in helping me figure this out? My current code is available at [https://code.google.com/p/cataclone/source/browse/trunk/src/catacomb/catacomb_sound.c catacomb_sound.c] - [[User:Eros|Eros]] 11:57, 5 May 2012 (GMT)
: Should this be moved to my talk page? - [[User:Eros|Eros]] 11:59, 5 May 2012 (GMT)
:: Probably best to keep it on my talk page if you want me to respond in a timely manner :-) I based my old utility off Anders' one too, but it's been a long time since I looked at the code. My latest utility doesn't support sound effects yet. I know Levellass has written a few utilities to play and edit those sound files, so I think your best bet would probably be to post over at the [http://www.keenmodding.org Keen:Modding] forum. Do note that PC Speaker effects do sound crackly at the best of times, though! Also make sure you've got the right audio format (8-bit vs 16-bit, signed vs unsigned) - I remember some inconsistencies there causing some very distorted results for me. I love the name 'Cataclone' - does your code compile under Linux? -- [[User:Malvineous|Malvineous]] 13:21, 5 May 2012 (GMT)
::: I currently compile the code using Code::Blocks with GCC 4.6 -std=gnu99. It *should* compile under Linux. But I haven't tested that out yet. [[Catacomb]] sounds also have flags attached to each one, It's not exactly the same specification as what it says @ the [[Inverse_Frequency_Sound_format|Inverse Sound Frequency]] format page. Perhaps the flags would make a difference to the sounds? I have the sound setup @ [https://code.google.com/p/cataclone/source/browse/trunk/src/sound_manager.c sound_manager.c] in the sound_manager_init() method. I use AUDIO_S16 (signed 16-bit) @ 22050 Hz with 2 channels. I have not added support for the priority of the sounds yet, I plan on doing that after I get them playing properly.
::: I found some information on the [[ROTT]] sound format here: [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/_rt_soun.h _rt_soun.h]. This format should be similar to Catacomb as ROTT was developed by [[Apogee]] using the [[Doom]] engine. Here are the flags for the sounds that they define:
#define SD_OVERWRITE 0x01
#define SD_WRITE 0x02
#define SD_LOOP 0x04
#define SD_PITCHSHIFTOFF 0x08
#define SD_PLAYONCE 0x10
::: There are also many other sound files for ROTT: [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/rt_sound.c], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/rt_sound.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/snd_reg.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/snd_shar.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/sndcards.h]
:::: I tried it last night and I was able to get it to compile (after a few changes, like using '/' instead of '\' in a couple of #includes) but all I got was a black window and a beep sound, then nothing. How far advanced is the project? Should I expect more than that? I would expect small variations in the file formats between games, but I would be surprised if the core sound data has changed over time. -- [[User:Malvineous|Malvineous]] 02:38, 6 May 2012 (GMT)
::::: On Windows, you can run around the levels, collide with walls, collect items, etc... I still need to implement monsters, AI and power shots. However, that beep means that the sounds playing. (see line 71 in main.c: catacomb_sounds_play("foundsound");). I just committed the catacomb_data.h file. Update it accordingly, you should now see much more than a black screen.
:::::: Oh wow, that works really well now! I see what you mean by the sounds. You might have to output the PCM data to a .wav/.raw file and look at it in a sound editor to see what's going on. It sounds like there might be wrapping or something going on. Also some sounds (like being blocked by a door) play multiple times over the top of themselves. I guess this is what you meant by priority not being implemented (although maybe you wouldn't need to handle priority if you can play multiple sounds at the same time, unlike the real PC Speaker.) One suggestion - if you do decide to support Linux, abstract the calls that open files so that they search for filenames instead - that way you don't have to rename all the Catacomb files to be uppercase, since Linux has a case-sensitive filesystem and most filenames are usually all lowercase. -- [[User:Malvineous|Malvineous]] 03:42, 6 May 2012 (GMT)
::::::: I have exported the raw data to a file, then imported the raw data into Audacity using various settings. All of them sound like they do in the game, crackly and sometimes distorted. I really think its some sort of post FX used by the flags. As for files, I'll code some sort of SafeFileOpen, SafeFileClose functions like the id codebase that open files regardless of case when i get around to implementing the Linux version. - [[User:Eros|Eros]] 03:54, 6 May 2012 (GMT)
:::::::: If you can e-mail me one of the files (preferably a 'quiet' one that's not supposed to be crackly) I can take a look if you like - malvineous@shikadi.net -- [[User:Malvineous|Malvineous]] 03:57, 6 May 2012 (GMT)

== Merge ==

Is there a way to tag two pages such that it is clear that they should be merged?
For example, [[Crystal Caves Tileset Format]] describes the same format as [[Duke 1 Tileset Graphics]].[[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 21:00, 15 July 2013 (GMT)

: You can mention it on the talk page for one of the articles. Any suggestions as to what we should call the merged page? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 03:09, 20 July 2013 (GMT)

::Dark Ages is the first game that got released that uses this format, so ''Dark Ages Tileset Format'' could be the name, like all those formats that are named after Commander Keen 1-3.
::Or we name it after Duke Nukem 1, because that game is probably more popular than Dark Ages, Crystal Caves and Secret Agent, like [[Commander Keen 1-3 Level format]], although Slordax used it before Commander Keen 1-3 did.[[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 19:13, 20 July 2013 (GMT)

::: Yes I was thinking along the same lines, naming it after the first game that used the format. But then the release date doesn't necessarily indicate which game "invented" the format, if one game took longer to develop and was released late. I was wondering whether there is a common thread amongst all these games, such as the same programmer or company we could use instead. In many ways I would prefer a name like "Replogle tileset format" or "Apogee EGA tileset format". What do you think? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 23:36, 20 July 2013 (GMT)

:::: I've read the [http://www.3drealms.com/news/2006/04/the_apogee_legacy_15.html | Apogee Legacy interview with Peder Jungck] again today. He wrote the ProGraphx Toolbox.
:::: DN1.EXE contains the string ''Version 1.0 EGA/VGAProGraphx EGA/VGA Toolbox'',
:::: CC1.EXE contains the string ''Version 1.5 320x200 PAN EGA/VGAProGraphx EGA/VGA Toolbox'',
:::: SAM1.EXE contains the string ''ProGraphx EGA/VGA Toolbox Version 2.0 320x200 EGA/VGA Copyright 1991 by Peder Jungck'' and
:::: DA3.EXE contains the string ''Version 1.0 EGA/VGAProGraphx EGA/VGA Toolbox'' (DA1.EXE and DA2.exe contain gibberish).
:::: So I would suggest ''ProGraphx Toolbox tileset format''. Peder also wrote a book about the toolbox called ''Graphics Programming & Animation: Ultra-Fast Assembly Routines for EGA/VGA Graphics Animation''. Maybe that book has a better name for the file format. [[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 11:03, 21 July 2013 (GMT)

::::: So we know of three different versions of the ProGraphx Toolbox. Dark Ages and Duke Nukem 1 use version 1.0. Each tileset is 8064 bytes long and is in a separate file. Crystal Caves uses version 1.5 and each tileset is 8003 bytes long, but they are all in the same file. Secret Agent uses version 2.0 Each tileset is again 8064 bytes long, they are all in the same file and the file is encrypted. [[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 17:00, 28 July 2013 (GMT)

:::::: Thanks for figuring all that out. I've merged the pages and changed the name to [[ProGraphx Toolbox tileset format]] as suggested. Please feel free to correct anything I have missed. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:40, 4 August 2013 (GMT)

== Guidelines for proper Wiki Editing ==
Dear Malvineous! Could you post the guidelines (or guide) for proper editing of the Wiki? [[User:The coder|The coder]] ([[User talk:The coder|talk]])
: Hmm, there isn't really one, it's more about finding a similar page and matching the style found there! Copy and paste works well :-) There is [[ModdingWiki:Contributing]] but it's not very detailed. (BTW please put <nowiki>~~~~</nowiki> at the end of your messages, when you preview the page you will see this gets replaced with your name and the date automatically.) -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 21:59, 12 December 2014 (UTC)

== VGFM Music Format ==

Hello, Malvineous!

I accidentally found that [[VGFM Music Format]] is absolutely similar to the [http://www.vgmpf.com/Wiki/index.php?title=MUS_(AdLib) MUS (AdLib)] format which I finished researching yesterday.

And [[VGFM Instrument Format]] is similar to [http://www.vgmpf.com/Wiki/index.php?title=SND_(AdLib) SND (AdLib)].

These formats were developed by Ad Lib Inc, I found the sources and documentation in the Ad Lib developer's manual downloaded from old BBS board site :) And these formats are used not only in [[Vinyl Goddess From Mars]] game.

--[[User:Binarymaster|Binarymaster]] ([[User talk:Binarymaster|talk]]) 02:05, 22 January 2015 (UTC)

: Oh wow, what an interesting discovery!! Do you have any links to the official documentation? I'd really like to see what else they have to say about the format. And yes, we should definitely rename the articles here. What do you think they should be called? "Ad Lib Music Format" is probably a bit generic given they have a few, like .ROL... -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 09:45, 22 January 2015 (UTC)
:: Here it is: [http://files.mpoli.fi/software/programm/general/adlip.zip adlip.zip] - binaries and source code, probably from Ad Lib Programmer's Manual. MUS headers are described in CONVERT.C and CONVERT.H files. Fun fact that they also developed another similar format based on MIDI - [http://www.vgmpf.com/Wiki/index.php?title=MDI MDI]. It has similar musical features but stores all data in one file in MIDI format.
:: Well, I have no idea how to name it better, I think "Ad Lib Music Format" should be suitable for it :) --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 10:30, 22 January 2015 (UTC)

::: Many thanks!! I've updated the article pages with the info I could gain from the source code. There are still a few unresolved issues (like what exactly the default percussion pitch is) but it has certainly answered a number of questions. I called it "AdLib MIDI Format" because that's the name they use in one place in the source code, although it's not a very descriptive title! Thanks again for letting me know about this excellent find :-) -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 12:48, 24 January 2015 (UTC)

:::: That's good! I think maybe this format should be named as "AdLib MIDI Format v1.0", because there is also an improved version of it, probably v2.0 - [http://www.vgmpf.com/Wiki/index.php?title=MDI MDI] (I made a typo in previous posted link), it uses a single file in MIDI format.
:::: And about [[AdLib Timbre Bank Format]] article - BNK format originally was created in the 1987 with the first release of the [http://www.vgmpf.com/Wiki/index.php?title=AdLib_Visual_Composer AdLib Visual Composer], so actually Ad Lib Inc released its formats in this order:
:::: '''1)''' ROL & BNK (1987, with AdLib Visual Composer)
:::: '''2)''' MUS & SND/TIM (1988, with player and converter)
:::: '''3)''' MDI (1989, also with player and converter)
:::: Information about third format was placed [http://cd.textfiles.com/soundsensations/MISCPROG/AD-PROG/ here], though the link is not working now.
:::: --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 13:08, 24 January 2015 (UTC)

::::: Oh wow that's interesting too. I think the MUS/SND/TIM format should stay as "AdLib MIDI Format" with no version number, because that file format does have version fields so it's possible to have v1.0, v2.3, etc. within that format. The MDI article you linked to actually looks like conventional MIDI with some extra events for setting OPL instruments, so I think this belongs as one of the many backwards-compatible extensions of the [[MID Format]].

::::: With the instrument bank formats that's really unusual if BNK came first! It seems very odd for AdLib to produce the SND/TIM format if they already had the more efficient BNK format available. I was going from the dates in the text files from the programmer's guide you kindly posted, and bkformat.txt says in Jan 1989 they are in the process of converting their software to use BNK. Can you confirm there was BNK software earlier than this? I'm just thinking that Visual Composer may have come out in 1987, but maybe it didn't get BNK support added until later? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 01:30, 25 January 2015 (UTC)

:::::: Well, I'm sure that first version of Visual Composer was released with AdLib music card, but I don't know exactly about BNK support. It's really strange that Ad Lib downgraded the format (BNK is better in structure), but the known formats has converters which converts BNK to X format, but not from X to BNK - this makes sense that BNK was the first format. Also Visual Composer doesn't support other bank formats, only BNK.
:::::: BNK creation date 1987 was contributed by [http://www.vgmpf.com/Wiki/index.php?title=User:TheAlmightyGuru Dean Tersigni], I'll ask him about it.

:::::: Update: I also read information from bkformat.txt, and it seems you're right :)
:::::: So actually it was:
:::::: '''1)''' ROL & INS (1987, with AdLib Visual Composer v1.0)
:::::: '''2)''' MUS & SND/TIM (1988, with player and converter)
:::::: '''3)''' BNK (1989, with AdLib Visual Composer v1.5)
:::::: '''4)''' MDI (1989, also with player and converter)
:::::: Wow, that feel when restored original order of events! :D --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 01:51, 25 January 2015 (UTC)

::::::: That seems to make the most logical sense - there's a clear improvement with each new format. I'm glad you agree! Note that when you say there's no conversion from "X to BNK" there is BANKMNG.EXE that comes with the programmer's manual which converts .ins files to .bnk. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 04:09, 25 January 2015 (UTC)

:::::::: True. I forgot about it :) Thanks! --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 12:02, 25 January 2015 (UTC)

User talk:Malvineous

2015-01-25T01:53:49Z

Binarymaster:

User talk:Malvineous

2015-01-25T01:51:02Z

Binarymaster: /* VGFM Music Format */

== Wolfenstein 3D -> Wolfenstein 3-D ==
I've corrected the infamous 3D tyop in the names of several Wolf3D-related pages; can you please delete the following ones?

[[:Category:Wolfenstein 3D]] -> Superseded by [[:Category:Wolfenstein 3-D]] 
[[:Image:Wolfenstein_3D.png]] -> Superseded by [[:Image:Wolfenstein_3-D.png]]

Thanks :) --De Zeurkous (zeurkous@zeurcomp.nichten.info), Thu Nov 22 08:18:42 UTC 2007

:Haha, you've certainly been busy. Don't forget that this wiki isn't meant to be an encyclopaedia of the games, its main purpose is documenting the file formats and editing tools that can be used with the games, as opposed to how the games behave without any mods, or what they might be called if you forget to change the title screen :-) -- [[User:Malvineous|Malvineous]] 11:14, 22 November 2007 (GMT)

::Nah, I haven't forgotten. As we're reinventing the wheel for a semi-virgin wiki, the naming and something static like the cheats seemed like a good place to start :) --De Zeurkous (zeurkous@nichten.info), Thu Nov 22 12:20:04 UTC 2007

== Jill of the Jungle palette ==

Hi, I'm currently working on a level viewer for [[Jill of the Jungle]] (maybe an editor later on). Some of the information I found here has been very useful, but there's one thing I'm a bit stuck on. On the [[SHA Format]] page it says:
:''Each array item contains 4 unsigned bytes, representing CGA, EGA and VGA, respectivley, and then a null value. [...] Each byte maps to the index of a colour in the palette. If there are no colours required, the tile set uses the default colours.''
However, it doesn't say anywhere where the palette can be found. Is it stored in the EXE file? I hope you can help me on this :)

Regards, [[User:Spinal|Spinal]] 13:00, 2 March 2008 (GMT)

:Unfortunately I didn't write the JotJ SHA page, and I haven't yet had the time to figure this out. For Xargon I've taken the quick and dirty route and used a screenshot from within DOSBox as the source of the palette, until I can figure out where the palette is located. If you find this out, don't forget to update the page! :-) -- [[User:Malvineous|Malvineous]] 22:02, 2 March 2008 (GMT)

::Hey Spinal, sorry, I wrote the [[SHA Format]] page, so that was probably my bad. I wasn't able to find the palette either. I assume it's in the .EXE, however I spent a fair bit of time manually mapping it using a Wombat tool (http://www.szevvy.com/node/3). I was also writing a level viewer (initally in XHTML which turned out to be too slow, so then I moved to Flash 9). I tried to email you my findings, but the email bounced. I'm not sure if they were 100% accurat, which is why I never added them to the documentation.

::Hey Malvineous, it seems the Jill - [[DMA Format]] page has been removed. Do you have a log of what happened to it? I'm sure it existed at some point.

::- [[User:dheim|Daniel]] 20:00, 5 March 2008

:::I don't ever remember seeing a DMA page - certainly there's nothing in the wiki logs about it being deleted or renamed. Maybe you started working on it but never got around to saving it? Or is it one of the Xargon pages that shares the same format as Jill? (by the way, you can type <nowiki>~~~~</nowiki> to automatically put in the signature in these messages.) -- [[User:Malvineous|Malvineous]] 11:28, 5 March 2008 (GMT)

::::Sorry, it must have been the stuff in the [[SHA Format]] page that I was thinking of. I may have added the link to the [[DMA Format]] page, and never expanded on it. - [[User:Dheim|Daniel]] 02:46, 6 March 2008 (GMT)

:::::Hi guys. Sorry for the mistake, I mixed up the authors of the SHA and level formats. I've written a level viewer in PHP the last week, by using static images instead of getting them from the actual files. This causes some problems for episode 2, which uses a different palette, but besides that it works great :) When everything is done I'll upload the maps to my server and the tile/object lists to this wiki.
:::::@Daniel: strange that it bounced, I confirmed my address so it should be working fine... You can mail it to spinal -at- zanderz -dot- net. Also, I saw on your Wombat page that you "have a vague idea of how to do" [[Hocus Pocus]]. Could you share your findings on this wiki? I'd love to make maps, or even a level viewer/editor for that game :) -- [[User:Spinal|Spinal]] 00:32, 8 March 2008 (GMT)
:Okay, with help of [[User:Dheim|Daniel]] who send me the palette I found it! I'll put my findings on [[Jill of the Jungle palette]]. -- [[User:Spinal|Spinal]] 15:36, 13 March 2008 (GMT)

== Halloween Harry/Alien Carnage ==

Hi Malvineous. Thanks for your edits on the GMF article! I notice you mentioned there exist versions of the game which don't require exploding a BNK to get at the game data. What does the directory structure look like for the version you have? I'm working on a map viewer (which will become a map editor at some point) and would like it to be able to work on whatever versions are out there. Thanks for any info. -[[User:Duckthing|Duckthing]] 04:41, 11 December 2010 (GMT)

: Hi Duckthing - no worries, Halloween Harry has long been an interest of mine, but my map editor sadly needs a lot more work before I can begin reverse engineering more file formats so I'm glad you've made a start! AFAIK technically Halloween Harry has no compression, but for whatever reason (probably listed in the Apogee FAQ) they decided to swap episodes 1 and 3, compress the BNK file and then re-release it under the name Alien Carnage. You can download all available versions (including registered versions since the game was released as freeware in 2007) from [http://www.classicdosgames.com/game/Alien_Carnage.html RGB Classic Games]. BTW not sure if you noticed but I also posted a couple of things on the GMF article's talk/discussion page. -- [[User:Malvineous|Malvineous]] 06:08, 11 December 2010 (GMT)

:: Thank you! Working with the uncompressed version will keep things less complicated. I did notice the GMF discussion you added, but haven't had a chance to really go through it yet. -- [[User:Duckthing|Duckthing]] 06:41, 11 December 2010 (GMT)

::: No worries. If you're running Linux or MacOSX you should be able to compile [[Camoto|libgamearchive]] which will let you copy files in and out of the BNK files. This is a library so it's also possible to use it in your own program for accessing and editing the map files while they're still inside the BNK, for instance. (BTW the 'minor' tickbox should only be used when the edit does not affect the information on the page - e.g. fixing a typo or a broken URL. If you are changing the actual content on a page it is never a minor edit!) -- [[User:Malvineous|Malvineous]] 07:51, 11 December 2010 (GMT)

== Dangerous Dave ==

Working on this, does anyone have any info on the formats? The EGA graphics are 84KB and external, but CGA and VGA graphics unrelated to them are in the 174KB executable, apparently uncompressed, I don't know how this is possible. I've found the levels and partially reverse engineered the format (The first 1000 bytes, a 100x10 array of tiles.) but each level is followed by ~280 bytes of variable and unknown data I assume is sprites. I have a list of internal files in the executable, looks like most of it is non-game code. Any help would be appreciated. -[[User:Levellass|Endian? What are you on about?]] 06:03, 12 December 2010 (GMT)

: Hmm, interesting. All I can suggest for the levels is - as you're probably already familiar with - changing the values in a hex editor then loading the game to see what happens. I would suspect that all the graphics would be in a similar format, so if there are any headers or structures used in the EGA graphics files perhaps they're duplicated for CGA/VGA? Also John Romero seems pretty accessible, perhaps you could ask him directly? Failing that, randomly writing data into the .exe until the images change could be used as a last resort! -- [[User:Malvineous|Malvineous]] 12:09, 12 December 2010 (GMT)

: Ha, that was easier than I expected - uncompressed VGA data is easy to find with a good hex editor ;-) [http://www.shikadi.net/pics/ddave-vga-hexdump.png This looks like it] -- [[User:Malvineous|Malvineous]] 12:17, 12 December 2010 (GMT)

: Ok that was only the menu graphics. At offset 0xC629 there's some sort of offset table which looks very similar to the contents of EGADAVE.DAV but there are extra bytes dotted all over the place - perhaps it's RLE encoded? Actually just before that there's the number 0x6CAA. If you go a bit less than 0x6CAA bytes after this you end up with another table, which to me suggests that 0x6CAA is the decompressed size of that first table. -- [[User:Malvineous|Malvineous]] 13:01, 12 December 2010 (GMT)

:If I remember it correctly, the VGA sprites and tiles are RLE compressed and it's not too hard to decompress them. The positions of the enemies in the levels on the other hand are still a mystery to me. [[User:Calvero|Calvero]] 20:43, 12 December 2010 (GMT)

: Looking at the levels, which directly follow the VGA palette, they seem to contain 256 bytes of header data, then the 100x10 tiles, then eight bytes of lead-out data. Then the next level's 256 bytes of header, 100x10 tiles, then eight bytes of lead-out. Although I say "level", the first "level" seems to contain both level 1 and 2, and this seems to be the way it works in the game - in some levels you can see through to others. I'm not sure what the 256 bytes of header data are for, but some levels have FF FF 00 00 repeated which seems to indicate two uint16 fields which are blanked out for those levels. -- [[User:Malvineous|Malvineous]] 13:15, 13 December 2010 (GMT)

::First up, levels; where does level 1 start? It's possible I'm reading the start of a level as the previous level's end, I looked for the start of tile data, which I assumed, like Keen 1, would be the level start.

::Next, palette; I'm assuming, as you said, it is located just before the level data?

::There is VGA and CGA graphics in the executable, plus headers, but the bulk of graphics for CGA and VGA I haven't been able to locate. If the data is RLE compressed I should think it would use either Keen 1-3 fullscreen or Jazz Jackrabbit tile RLE, both of which I know well. I'll look into both of these options, cheers! -[[User:Levellass|Endian? What are you on about?]] 12:03, 20 December 2010 (GMT)

:::I've found the VGA and CGA data for the menu graphics. It looks like the CGA data is stored in a series of 1-bit-per-pixel (monochrome) images. Or it could be EGA data with the planes split out (e.g. red plane for all images, then green plane for all images, etc.) I think I found three planes which means it's probably EGA, as CGA would have a max of two planes. I've also found the font graphics, this looks like 4bpp/16 colour EGA data. Haven't seen level graphics yet. I've successfully modded the levels with a hex editor (putting the jetpack everywhere) so now I've finally looked at all the levels! The creatures are definitely not stored in the 100x10 tile data. Putting random bytes in there revealed that the values are indices into the image files, because if you put the value in for fire it will animate, and the following three or so values show up as still frames from the fire animation.

:::The VGA palette starts at 0x26B0A (I updated the main DDave page with this) + 768 bytes leads straight onto the start of level 1 at 0x26E0A. So at 0x26E0A there are 256 bytes of data, then 100x10 tiles, then 24 bytes of footer data. Some of this data (perhaps footer data) might be the level start coordinates, because Dave doesn't always start the level at the same place (e.g. the warp level when you climb the tree on level 5 and jump off the edge of the screen.) -- [[User:Malvineous|Malvineous]] 12:24, 20 December 2010 (GMT)

:::I think I've found all the files so far, I've updated [[Dangerous Dave]] with the offsets of the files, including what appears to be CGA and VGA tiles. I'm not sure what sort of format they're in though, it looks like they might be compressed (and so the offsets in that list might be off by ~4, as I may have cut off the decompressed-size field.) I've also updated the map format page, I think it's pretty much fully reverse engineered now. -- [[User:Malvineous|Malvineous]] 05:13, 21 December 2010 (GMT)

== Noahs Ark 3D and IMFs ==

Been poking around Noah's Ark 3D, an adaption of the Wolfenstein game and found a few interesting things which I'm hoping to confirm.

First, the game uses MID files, not IMF files for music, second, the MIDI files have an extra word at the start of the file giving the file length. Third, the code uses the first word of the midi file as the length of data to read from the file and put into memory to play. After poking around a bit in Wolfenstein and Keen I believe this is the same with IMF files, that is, ALL IMF files are type 0 as it were and the type 1s are read just like type 0s by the games (The first word is read as the amount of IMF data to copy into memory to play, this is then read as type 0.) I'm not quite sure what this does for the two types since type 1 is would essentially be a type 0 with a header and footer that are part of the AUDIO.xxx format, much like PC\adlib sounds can have the huffman lengths at the start. Are there any games that use 'individual' type 1 IMFs (Even if included as part of a group file. All I've seen are games like cosmo, where non-AUDIO IMFs are type 0.)

Should there be a Noah's Ark 3D page and should we add the midi note to the AUDIO format page? It seems that the format can hold any type of music file the game can read, not just IMFs. -- Levellass

: Yes it is known that the type-1 header might really be part of the AUDIO.xxx format but alas there were many type-1 files floating around the place (incorrectly extracted, you could argue) before this was realised, so the format variant is here to stay. It does have some advantages though (like tagging files with the song title) but I'm not sure whether anyone has figured out definitively whether the header (and footer, in the case of the Wolf3D files) belongs to the IMF or the AUDIO file. I guess you'd have to browse the game source code and see how the game uses the data to know for sure.

: As far as the MIDI goes, I believe the AUDIO.xxx file is just a container file like any other, capable of supporting any data at all. It's up to the game to decide how to use it. If anything this makes me think it would fit better if the AUDIO.xxx article was merely documenting the structure, with links to actual audio formats like PC SFX, Adlib SFX, IMF and MIDI and notes about which games make use of which formats.

: Oh and yes, by all means create a page for the new game. -- [[User:Malvineous|Malvineous]] 08:41, 3 February 2011 (GMT)

== Sound Files category ==

I don’t know why there’s a Sound Files category and also an Audio Files category... it seems redundant. I left those categories the way they are though.

Also, the [[File format data types]] page needs some signed ints, but I didn’t know what naming convention you wanted to use. I described something as an [[INT16LE]] on [[BMC Format]]. [[User:Yellowantphil|Yellowantphil]] 20:12, 11 September 2011 (GMT)

: Not sure about the Sound vs Audio - I use the term 'audio' to mean both sound and music, but you're right, if there are separate sound and music categories we don't really need an audio one as well. Feel free to update. [[INT16LE]] is perfectly fine too! I added a note to the data types page. -- [[User:Malvineous|Malvineous]] 22:30, 11 September 2011 (GMT)

== GamePage template ==

Should the GamePage template add the page to its own category? It seems a little odd that [[Wacky Wheels]] is not in the Wacky Wheels category. [[User:Yellowantphil|Yellowantphil]] 04:51, 16 September 2011 (GMT)
: I decided against this because there is a link to the game's page in the category intro at the top of the page. It seemed unnecessary having another link in amongst all the other pages. This was also because the game page was really only meant to be a summary, there wasn't supposed to be a huge amount of detail on it, only links to other pages with the detail (which then would appear in the category list.) I would imagine that, eventually, [[Wacky Wheels]] would be tweaked to move a lot of the content onto subpages. -- [[User:Malvineous|Malvineous]] 12:58, 16 September 2011 (GMT)

== Scope of the wiki ==

I don’t know how extensive you want the information to be on ModdingWiki... I added a few lists of audio and graphics files a while ago, and there will probably be other information that I’ll find out that’s potentially helpful for level editing but not directly related to it. I can move some information to my website if it starts to become out of scope for your wiki. I also sometimes end up documenting everything imaginable... there’s some minutiae on my website and possibly on your wiki that I ought to go through and delete. [[User:Yellowantphil|Yellowantphil]] 05:28, 10 October 2011 (GMT)

:Hmm, that's a difficult one - I'm always in favour of documenting more rather than less. Generally speaking if it's related to a game and it would help either a programmer writing a utility or a someone trying to change a game manually then it should be documented. About the only thing that comes to mind that's over documenting is when some small calculation is expressed in a couple of different programming languages, but I've left that in so people can just copy it rather than trying to figure it out from the text. But the [[Wacky Wheels]] page is probably the gold standard for what all wiki pages should look like :-) Do you have anything in particular you're unsure of whether it would fit here? -- [[User:Malvineous|Malvineous]] 10:07, 10 October 2011 (GMT)

::I was mainly thinking of the list of VOC files on [[Wacky Wheels Music and Sound Effects]] and the list of <tt>*.sp</tt> files on [[Wacky Wheels Graphics Formats]]. I have an expanded list of the <tt>*.sp</tt> files on my computer but it isn’t finished yet. I guess there isn’t all that much more Wacky Wheels information to be added to this wiki though. There is still some modding information on my website that ought to be moved over here, so that would take up another page or two. I’ve been lazy about doing Wacky Wheels stuff lately, but I might find some time for it this weekend.

::By the way, I guess that guy from Cascadia Games emailed you. It’s pretty interesting that WW might become an iPhone app. He told me that he was going to be using his own game engine, which sounds a lot easier than trying to get a hold of the WW source code and porting it. —[[User:Yellowantphil|Yellowantphil]] 16:46, 15 October 2011 (GMT)

::: I was going to say the list of VOCs might be overkill, but then the list of .sp files might be useful. To be honest, it's the sort of thing that you could probably omit if you were feeling lazy, but likewise I don't mind at all if you choose to include it, so since it's already there I'm happy to keep it.

::: Yes I did get an e-mail from Cascadia, I was going to pass along your details but it sounds like you're already aware of it! Using their own engine might make it a bit smoother than the original, as the jerkiness of turning is my only criticism of the game. -- [[User:Malvineous|Malvineous]] 00:14, 16 October 2011 (GMT)

== Wacky Wheels ==

Basically all of the WW modding information from my website is here now. I moved one page when I realized it should probably be capitalized to match the rest of the pages on this site... you can delete the redirect at [[Wacky Wheels high score files]] if you want to.

Now, I need to remove most of the modding information from my website and refer people here. Then we’ll have reached the glorious future where all WW modding information is in one place. I’m going to keep those two text files of notes on my website though—the information in them is disorganized and I think not 100% accurate, but they might have some information that isn’t here yet.

By the way, how’s Camoto going? I’m planning to use it to make a new WW level, but I won’t have time for it for a few more months. —[[User:Yellowantphil|Yellowantphil]]

: Sounds good! Thanks for all the effort you've put in by moving it across. I think Wacky Wheels is now the most completely documented game on the wiki! Also can't hurt leaving your own info up - sometimes it's nice to go back to the original source if something is unclear. Camoto's going well, but unfortunately I haven't had much time to work on it over the last few weeks. You probably won't be able to make much of a level until I add in the ability to select a tile from the tileset, but that's in progress and hopefully will be ready by the time you are! Keep me posted when you do start your level(s?) -- [[User:Malvineous|Malvineous]] 12:22, 2 February 2012 (GMT)

::Well, as I was reading some of the information on my website, I noticed that it isn’t written very well. I wrote those pages back when I had very little experience programming. Anyway, I’m planning to redesign my website soon, and this will save me from having to rewrite a few of those pages.

::The tile editor in Camoto as it is now is still certainly useful—I can add new tile types to a level using a binary editor and then move them around in Camoto. I think that it shouldn’t be too hard to make a new WW level using the Gimp and Camoto plus some binary editing. I recall having some problems with the route editor for the computer players, but I didn’t look into it at the time—I’ll let you know when I’m working with Camoto again, and I’ll try to come up with some useful bug reports or fixes if I run into problems. —[[User:Yellowantphil|Yellowantphil]] 14:06, 2 February 2012 (GMT)

== Catacomb ==

Hey [[User:Malvineous|Malvineous]], do you know anyone who has properly read the [[Inverse_Frequency_Sound_format|Inverse Sound Frequency]] file format and got the sound playing? I'm struggling with some fine details in my game. Sounds play near what they should sound like, but the sound quality is all crackly and some sounds play totally incorrect. I followed a basic [http://web.archive.org/web/20000818033701/http://www.dd.chalmers.se/~f98anga/projects/keen/sounds2raw.c code sample] by Anders Gavare. Does your tool support this? Interested in helping me figure this out? My current code is available at [https://code.google.com/p/cataclone/source/browse/trunk/src/catacomb/catacomb_sound.c catacomb_sound.c] - [[User:Eros|Eros]] 11:57, 5 May 2012 (GMT)
: Should this be moved to my talk page? - [[User:Eros|Eros]] 11:59, 5 May 2012 (GMT)
:: Probably best to keep it on my talk page if you want me to respond in a timely manner :-) I based my old utility off Anders' one too, but it's been a long time since I looked at the code. My latest utility doesn't support sound effects yet. I know Levellass has written a few utilities to play and edit those sound files, so I think your best bet would probably be to post over at the [http://www.keenmodding.org Keen:Modding] forum. Do note that PC Speaker effects do sound crackly at the best of times, though! Also make sure you've got the right audio format (8-bit vs 16-bit, signed vs unsigned) - I remember some inconsistencies there causing some very distorted results for me. I love the name 'Cataclone' - does your code compile under Linux? -- [[User:Malvineous|Malvineous]] 13:21, 5 May 2012 (GMT)
::: I currently compile the code using Code::Blocks with GCC 4.6 -std=gnu99. It *should* compile under Linux. But I haven't tested that out yet. [[Catacomb]] sounds also have flags attached to each one, It's not exactly the same specification as what it says @ the [[Inverse_Frequency_Sound_format|Inverse Sound Frequency]] format page. Perhaps the flags would make a difference to the sounds? I have the sound setup @ [https://code.google.com/p/cataclone/source/browse/trunk/src/sound_manager.c sound_manager.c] in the sound_manager_init() method. I use AUDIO_S16 (signed 16-bit) @ 22050 Hz with 2 channels. I have not added support for the priority of the sounds yet, I plan on doing that after I get them playing properly.
::: I found some information on the [[ROTT]] sound format here: [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/_rt_soun.h _rt_soun.h]. This format should be similar to Catacomb as ROTT was developed by [[Apogee]] using the [[Doom]] engine. Here are the flags for the sounds that they define:
#define SD_OVERWRITE 0x01
#define SD_WRITE 0x02
#define SD_LOOP 0x04
#define SD_PITCHSHIFTOFF 0x08
#define SD_PLAYONCE 0x10
::: There are also many other sound files for ROTT: [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/rt_sound.c], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/rt_sound.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/snd_reg.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/snd_shar.h], [http://src.gnu-darwin.org/ports/games/rottdc/work/rottdc-1.0-2/rott/sndcards.h]
:::: I tried it last night and I was able to get it to compile (after a few changes, like using '/' instead of '\' in a couple of #includes) but all I got was a black window and a beep sound, then nothing. How far advanced is the project? Should I expect more than that? I would expect small variations in the file formats between games, but I would be surprised if the core sound data has changed over time. -- [[User:Malvineous|Malvineous]] 02:38, 6 May 2012 (GMT)
::::: On Windows, you can run around the levels, collide with walls, collect items, etc... I still need to implement monsters, AI and power shots. However, that beep means that the sounds playing. (see line 71 in main.c: catacomb_sounds_play("foundsound");). I just committed the catacomb_data.h file. Update it accordingly, you should now see much more than a black screen.
:::::: Oh wow, that works really well now! I see what you mean by the sounds. You might have to output the PCM data to a .wav/.raw file and look at it in a sound editor to see what's going on. It sounds like there might be wrapping or something going on. Also some sounds (like being blocked by a door) play multiple times over the top of themselves. I guess this is what you meant by priority not being implemented (although maybe you wouldn't need to handle priority if you can play multiple sounds at the same time, unlike the real PC Speaker.) One suggestion - if you do decide to support Linux, abstract the calls that open files so that they search for filenames instead - that way you don't have to rename all the Catacomb files to be uppercase, since Linux has a case-sensitive filesystem and most filenames are usually all lowercase. -- [[User:Malvineous|Malvineous]] 03:42, 6 May 2012 (GMT)
::::::: I have exported the raw data to a file, then imported the raw data into Audacity using various settings. All of them sound like they do in the game, crackly and sometimes distorted. I really think its some sort of post FX used by the flags. As for files, I'll code some sort of SafeFileOpen, SafeFileClose functions like the id codebase that open files regardless of case when i get around to implementing the Linux version. - [[User:Eros|Eros]] 03:54, 6 May 2012 (GMT)
:::::::: If you can e-mail me one of the files (preferably a 'quiet' one that's not supposed to be crackly) I can take a look if you like - malvineous@shikadi.net -- [[User:Malvineous|Malvineous]] 03:57, 6 May 2012 (GMT)

== Merge ==

Is there a way to tag two pages such that it is clear that they should be merged?
For example, [[Crystal Caves Tileset Format]] describes the same format as [[Duke 1 Tileset Graphics]].[[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 21:00, 15 July 2013 (GMT)

: You can mention it on the talk page for one of the articles. Any suggestions as to what we should call the merged page? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 03:09, 20 July 2013 (GMT)

::Dark Ages is the first game that got released that uses this format, so ''Dark Ages Tileset Format'' could be the name, like all those formats that are named after Commander Keen 1-3.
::Or we name it after Duke Nukem 1, because that game is probably more popular than Dark Ages, Crystal Caves and Secret Agent, like [[Commander Keen 1-3 Level format]], although Slordax used it before Commander Keen 1-3 did.[[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 19:13, 20 July 2013 (GMT)

::: Yes I was thinking along the same lines, naming it after the first game that used the format. But then the release date doesn't necessarily indicate which game "invented" the format, if one game took longer to develop and was released late. I was wondering whether there is a common thread amongst all these games, such as the same programmer or company we could use instead. In many ways I would prefer a name like "Replogle tileset format" or "Apogee EGA tileset format". What do you think? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 23:36, 20 July 2013 (GMT)

:::: I've read the [http://www.3drealms.com/news/2006/04/the_apogee_legacy_15.html | Apogee Legacy interview with Peder Jungck] again today. He wrote the ProGraphx Toolbox.
:::: DN1.EXE contains the string ''Version 1.0 EGA/VGAProGraphx EGA/VGA Toolbox'',
:::: CC1.EXE contains the string ''Version 1.5 320x200 PAN EGA/VGAProGraphx EGA/VGA Toolbox'',
:::: SAM1.EXE contains the string ''ProGraphx EGA/VGA Toolbox Version 2.0 320x200 EGA/VGA Copyright 1991 by Peder Jungck'' and
:::: DA3.EXE contains the string ''Version 1.0 EGA/VGAProGraphx EGA/VGA Toolbox'' (DA1.EXE and DA2.exe contain gibberish).
:::: So I would suggest ''ProGraphx Toolbox tileset format''. Peder also wrote a book about the toolbox called ''Graphics Programming & Animation: Ultra-Fast Assembly Routines for EGA/VGA Graphics Animation''. Maybe that book has a better name for the file format. [[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 11:03, 21 July 2013 (GMT)

::::: So we know of three different versions of the ProGraphx Toolbox. Dark Ages and Duke Nukem 1 use version 1.0. Each tileset is 8064 bytes long and is in a separate file. Crystal Caves uses version 1.5 and each tileset is 8003 bytes long, but they are all in the same file. Secret Agent uses version 2.0 Each tileset is again 8064 bytes long, they are all in the same file and the file is encrypted. [[User:Frenkel|Frenkel]] ([[User talk:Frenkel|talk]]) 17:00, 28 July 2013 (GMT)

:::::: Thanks for figuring all that out. I've merged the pages and changed the name to [[ProGraphx Toolbox tileset format]] as suggested. Please feel free to correct anything I have missed. -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 02:40, 4 August 2013 (GMT)

== Guidelines for proper Wiki Editing ==
Dear Malvineous! Could you post the guidelines (or guide) for proper editing of the Wiki? [[User:The coder|The coder]] ([[User talk:The coder|talk]])
: Hmm, there isn't really one, it's more about finding a similar page and matching the style found there! Copy and paste works well :-) There is [[ModdingWiki:Contributing]] but it's not very detailed. (BTW please put <nowiki>~~~~</nowiki> at the end of your messages, when you preview the page you will see this gets replaced with your name and the date automatically.) -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 21:59, 12 December 2014 (UTC)

== VGFM Music Format ==

Hello, Malvineous!

I accidentally found that [[VGFM Music Format]] is absolutely similar to the [http://www.vgmpf.com/Wiki/index.php?title=MUS_(AdLib) MUS (AdLib)] format which I finished researching yesterday.

And [[VGFM Instrument Format]] is similar to [http://www.vgmpf.com/Wiki/index.php?title=SND_(AdLib) SND (AdLib)].

These formats were developed by Ad Lib Inc, I found the sources and documentation in the Ad Lib developer's manual downloaded from old BBS board site :) And these formats are used not only in [[Vinyl Goddess From Mars]] game.

--[[User:Binarymaster|Binarymaster]] ([[User talk:Binarymaster|talk]]) 02:05, 22 January 2015 (UTC)

: Oh wow, what an interesting discovery!! Do you have any links to the official documentation? I'd really like to see what else they have to say about the format. And yes, we should definitely rename the articles here. What do you think they should be called? "Ad Lib Music Format" is probably a bit generic given they have a few, like .ROL... -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 09:45, 22 January 2015 (UTC)
:: Here it is: [http://files.mpoli.fi/software/programm/general/adlip.zip adlip.zip] - binaries and source code, probably from Ad Lib Programmer's Manual. MUS headers are described in CONVERT.C and CONVERT.H files. Fun fact that they also developed another similar format based on MIDI - [http://www.vgmpf.com/Wiki/index.php?title=MDI MDI]. It has similar musical features but stores all data in one file in MIDI format.
:: Well, I have no idea how to name it better, I think "Ad Lib Music Format" should be suitable for it :) --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 10:30, 22 January 2015 (UTC)

::: Many thanks!! I've updated the article pages with the info I could gain from the source code. There are still a few unresolved issues (like what exactly the default percussion pitch is) but it has certainly answered a number of questions. I called it "AdLib MIDI Format" because that's the name they use in one place in the source code, although it's not a very descriptive title! Thanks again for letting me know about this excellent find :-) -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 12:48, 24 January 2015 (UTC)

:::: That's good! I think maybe this format should be named as "AdLib MIDI Format v1.0", because there is also an improved version of it, probably v2.0 - [http://www.vgmpf.com/Wiki/index.php?title=MDI MDI] (I made a typo in previous posted link), it uses a single file in MIDI format.
:::: And about [[AdLib Timbre Bank Format]] article - BNK format originally was created in the 1987 with the first release of the [http://www.vgmpf.com/Wiki/index.php?title=AdLib_Visual_Composer AdLib Visual Composer], so actually Ad Lib Inc released its formats in this order:
:::: '''1)''' ROL & BNK (1987, with AdLib Visual Composer)
:::: '''2)''' MUS & SND/TIM (1988, with player and converter)
:::: '''3)''' MDI (1989, also with player and converter)
:::: Information about third format was placed [http://cd.textfiles.com/soundsensations/MISCPROG/AD-PROG/ here], though the link is not working now.
:::: --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 13:08, 24 January 2015 (UTC)

::::: Oh wow that's interesting too. I think the MUS/SND/TIM format should stay as "AdLib MIDI Format" with no version number, because that file format does have version fields so it's possible to have v1.0, v2.3, etc. within that format. The MDI article you linked to actually looks like conventional MIDI with some extra events for setting OPL instruments, so I think this belongs as one of the many backwards-compatible extensions of the [[MID Format]].

::::: With the instrument bank formats that's really unusual if BNK came first! It seems very odd for AdLib to produce the SND/TIM format if they already had the more efficient BNK format available. I was going from the dates in the text files from the programmer's guide you kindly posted, and bkformat.txt says in Jan 1989 they are in the process of converting their software to use BNK. Can you confirm there was BNK software earlier than this? I'm just thinking that Visual Composer may have come out in 1987, but maybe it didn't get BNK support added until later? -- [[User:Malvineous|Malvineous]] ([[User talk:Malvineous|talk]]) 01:30, 25 January 2015 (UTC)

:::::: Well, I'm sure that first version of Visual Composer was released with AdLib music card, but I don't know exactly about BNK support. It's really strange that Ad Lib downgraded the format (BNK is better in structure), but the known formats has converters which converts BNK to X format, but not from X to BNK - this makes sense that BNK was the first format. Also Visual Composer doesn't support other bank formats, only BNK.
:::::: BNK creation date 1987 was contributed by [http://www.vgmpf.com/Wiki/index.php?title=User:TheAlmightyGuru Dean Tersigni], I'll ask him about it.

:::::: Update: I also read information from bkformat.txt, and it seems you're right :)
:::::: So actually it was:
:::::: '''1)''' ROL & INS (1987, with AdLib Visual Composer v1.0)
:::::: '''2)''' MUS & SND/TIM (1988, with player and converter)
:::::: '''3)''' ROL & BNK (1989, with AdLib Visual Composer v1.5)
:::::: '''4)''' MDI (1989, also with player and converter)
:::::: Wow, that feel when restored original order of events! :D --[[User:Binarymaster|binarymaster]] ([[User talk:Binarymaster|talk]]) 01:51, 25 January 2015 (UTC)