ModdingWiki - User contributions [en-gb]

DSIK Module Format

2017-06-21T20:10:11Z

Corak: /* Tools */

{{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 = Yes
| canImport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .mtm .dsm .psm
| 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 = Any
| 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 = Windows
| 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]]

DSIK Module Format

2017-06-21T10:37:28Z

Corak: /* Tools */

{{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 = Yes
| canImport = [[MOD Format|.mod]] .stm [[S3M Format|.s3m]] .mtm .dsm .psm
| editHidden = No
| editMetadata = Yes
| 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 = Any
| 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 = Windows
| 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]]