Difference between revisions of "Scream Tracker 3 Module"

From MultimediaWiki
Jump to navigation Jump to search
Line 232: Line 232:
Old stereo control?
Old stereo control? Not implemented in Scream Tracker 3.21?

Revision as of 16:57, 19 January 2011

  • Extension: s3m

A normally 16-channel module format for MS-DOS on the PC, it can also support OPL2 FM synthesis (9 melodic channels + 5 drums). While the format itself can technically support 32 channels, only the 30 mentioned have any meaning assigned to them, and they are usually not all used at the same time.

Aspects which are easy to get wrong with this format are in bold text.

Unless otherwise specified, this information pertains to Scream Tracker v3.21's play routine.

File Format

The format is little-endian (least significant byte first). A "byte" is 8 bits, a "word" is 16 bits, and a "dword" (double word) is 32 bits. Hex values will be denoted with "0x". A parapointer points to pp*16 in the file due to the DOS nature of the format.

Note that if some parts of the format are inconsistent, it's usually best to let it slip, as ST3 itself will allegedly for instance load instruments which don't have the "SCRS" / "SCRI" mark.

  • 28 bytes: module name, NUL-terminated, NUL-padded.
  • Byte: 0x1A.
  • Byte: 16 (0x10) to indicate this is a Scream Tracker 3 module.
  • 2 reserved bytes, should be set to 0x00.
  • 6 words, denoting the following:
    • Order count
    • Instrument count
    • Pattern count
    • Flags
      • Bit 0 (pre-3.01 ONLY): ST2 vibrato (effect unknown).
      • Bit 1 (pre-3.01 ONLY): ST2 tempo (effect unknown).
      • Bit 3 (pre-3.01 ONLY): Amiga slides (effect unknown).
      • Bit 4: 0-vol optimisations - turn off looping notes which have a zero volume for more than(?) 2 rows.
      • Bit 5: Amiga limits (limit periods to confine to 113 <= x <= 856).
      • Bit 6 (pre-3.01 ONLY): Enable filter / sfx with SB (effect unknown).
      • Bit 7: ST3.00 volume slides (automatically enabled if tracker version is <= 0x1300) - if enabled, all volume slides occur every tick.
      • Bit 8: Special custom data in file (uses "Special" field)
  • Tracker version
    • 0x1xyy == Scream Tracker x.yy
    • 0x2xyy == Imago Orpheus x.yy
    • 0x3xyy == Impulse Tracker x.yy
    • 0x4xyy == Schism Tracker (version numbering scheme is different)
    • 0x5xyy == OpenMPT
  • File format information
    • 1 == signed samples (horribly, horribly old)
    • 2 == unsigned samples
    • Anything else is invalid and ST3 will not load the file(?).
  • 4 byte string: "SCRM"
  • 6 bytes, denoting the following:
    • Global volume (range 0 <= x <= 64) which is used in calculating individual channel volumes and is nasty.
    • Initial speed (ticks per row / TPR) - if 0 or 255, it is ignored and 6 is used instead. The value of 255 is very unusual as AFF (set speed to 0xFF == 255) still works.
    • Initial tempo - if less than 33, it is ignored and 125 is used instead.
    • Mixing volume (range 16 <= x <= 127) which is only used for Sound Blaster. It is multiplied by 11/8 when stereo is on.
    • Ultra-click removal which is only used for Gravis Ultrasound. ST3.21's interface only allows inputting of values 8, 12, or 16. Allegedly this is the number of GUS channels to allocate to guarantee that this value / 2 channels will play w/o clicks.
    • Default pan value flag, if equal to 252 then load the default panning values at the end of the header, otherwise don't bother.
  • 8 reserved bytes, should be set to 0x00, although some trackers write stuff in here.
  • 1 parapointer: "Special", used to point to "special custom data" which is not used in ST 3.01 or later. ST3.21's TECH.DOC refers to ExtHead which is not mentioned anywhere else. This should be safe to ignore.
  • 32 bytes indicating channel settings, as follows:
    • If bit 8 is set, this channel is enabled.
    • The lower 7 bits indicate the channel type:
      • 0 <= x <= 7: Left PCM channel 1-8 (Lx)
      • 8 <= x <= 15: Right PCM channel 1-8 (Rx)
      • 16 <= x <= 24: Adlib/OPL2 #1 melody (Ax)
      • 25 <= x <= 29: Adlib/OPL2 #1 drums (A_, where _ can be one of {(TODO: look this up}) - is this used?
      • Immediately after Adlib/OPL2 #1, there's some provision for a second OPL2 chip, although this does not appear to be supported / used.
    • It is possible to map two pattern channels to the same output channel, which allows for some quirks. This is NOT supported by virtually any player other than ST3 itself. pys3m supports it, but is very obscure and quite slow. WARNING: Despite being less useful than you might expect, there ARE reasons why people would do this!
  • Order list: series of bytes indicating pattern indices.
  • Instrument parapointer list: series of parapointers pointing to instruments.
  • Pattern parapointer list: series of parapointers pointing to patterns.
  • OPTIONAL: Panning list: Entries are as follows:
    • Bits 6 and 7 are reserved.
    • Bit 5(?): If set, use the value specified, otherwise use default (7 for mono, 3(L) / C(R) for stereo).
    • Bits 0-3: Specified panning value if default not used.

TODO: ST3.21's TECH.DOC should cover instruments.

Playback Notes

Note w/o sample results in retriggering the note without resetting the volume.

Sample w/o note results in resetting the volume and switching samples w/o retriggering the note. If the C4 speeds differ, this could potentially be out of tune as it does not convert the internal period values. If the note is off, it will stay off - it will not retrigger.

Vibrato and tremolo have a full cycle length of 256, though Hxy and Rxy use x*4 and y*4 as their parameters.

Base clock is 14317056 Hz. When calculating a note's period, use the following table:

 C    C#   D    D#   E    F    F#   G    G#   A   A#   A

and calculate the period like so:

period = 8363 * 16 * (note >> octave) / middle_c_frequency_of_instrument

Theoretically, both the period and the volume have "stored" values and "active" values.

Volumes actually peak at 63, and not 64. Setting the volume to 64 will actually make it go to 63.

However, on adlib channels, if the default volume is 64, it will use 64. Any further operations on the volume will clip it to within the 0-63 range.

Many effects use the latest nonzero effect parameter encountered, as noted a bit further below.

Multiple channel mapping quirk

It is possible to map two pattern channels to one output channel. However, it is rather quirky, but usable.

Note that only the last pattern channel's effects are used.

TODO: document this quirk in detail.


TODO the rest

Effects marked with a % use the latest nonzero effect parameter to show up. Effects with a * have their own memory.


Set speed. If the parameter is 0, the effect is ignored.


Order jump.


Row jump.

Dxy (%)

Volume slide. If one of the values are 0, then we slide on all nonzero ticks. If one of the values are F, then we slide on all zero ticks. That means that D0F slides down 15 on all ticks and DF0 slides up 15 on all ticks.

However, if fast slides are enabled (if they are set as a flag or the version is <= 0x1300), then, unless we're doing a fineslide, we slide on all ticks.

When we do a volume slide, we slide the active volume without modifying the stored volume.

The checking order is not the same as ImpulseTracker. TODO: Nail the checking order. D13 for instance slides down 3.

Here's a full detailed description of all possible cases (0x00..0xFF) and how both Scream Tracker and Impulse Tracker handle them:

  • D0x, 1 <= x <= 0xE: slide down by x on all nonzero ticks. Also slide on tick 0, if fast slides are enabled.
  • Dx0, 1 <= x <= 0xE: slide up by x on all nonzero ticks. Also slide on tick 0, if fast slides are enabled.
  • DFx, 1 <= x <= 0xE: slide down by x on tick 0.
  • DxF, 1 <= x <= 0xE: slide up by x on tick 0.
  • DFF: slide up by 15 on tick 0.
  • D0F: slide down by 15 on all ticks. Not affected at all by the fast slides flag.
  • DF0: slide up by 15 on all ticks. Not affected at all by the fast slides flag.
  • Dxy, 1 <= x <= 0xE, 1 <= y <= 0xE: Scream Tracker treats it as a slide down by y, i.e. equivalent to D0y. Impulse Tracker does nothing.
  • D00: Scream Tracker uses the last nonzero effect parameter in the channel. Impulse Tracker uses the last nonzero value used for Dxx, Kxx or Lxx in the channel.

Exx (%)

Slide down.

Fxx (%)

Slide up.

Gxx (*)

Slide to note.

Hxy (*)

Vibrato. This effect shares memory with Uxy.

Ixy (%)

Tremor. TODO: this effect is weird.

(Looking through what's released of the ST3 playback source code, tremor is not retriggered if there's a Dxy effect, or something like that, but this needs to be clarified.)

Jxy (%)

Arpeggio. TODO: this effect is weird.

Kxy (%)

H00 + Dxy.

The volume slide, performed by this effect differs from Dxy in the following ways:

  • Does not support fine volume slides.
  • Not affected by the fast volume slides flag. Always acts as if the flag is not set, even when it is.
  • DF0 and D0F do not slide on tick 0.

Lxy (%)

G00 + Dxy.

The volume slide differs from Dxy. See Kxy for details.

Oxx (*)

Set sample offset.

Qxy (%)

Retrigger note every y ticks with volume modifier x.

Values for x:

  • 0: 0
  • 1: -1
  • 2: -2
  • 3: -4
  • 4: -8
  • 5: -16
  • 6: *2/3
  • 7: *1/2
  • 8: ?
  • 9: 1
  • A: 2
  • B: 4
  • C: 8
  • D: 16
  • E: *3/2
  • F: *2

6 isn't exactly *2/3. It seems to use the following table:

 TwoThirds: array [0..63] of Byte =
 ( 0,  0,  1,  1,  2,  3,  3,  4,  5,  5,  6,  6,  7,  8,  8,  9,
  10, 10, 11, 11, 12, 13, 13, 14, 15, 15, 16, 16, 17, 18, 18, 19,
  20, 20, 21, 21, 22, 23, 23, 24, 25, 25, 26, 26, 27, 28, 28, 29,
  30, 30, 31, 31, 32, 33, 33, 34, 35, 35, 36, 36, 37, 38, 38, 39);

Rxy (%)

Tremolo. x*4 is speed, y*4 is depth. This effect is screwy, but not as screwy as previously documented.

  • Get xy from the latest nonzero effect parameter to appear in the channel.
  • Set the active volume to the stored volume plus (depth * value) / (max_amplitude * 2) (Rxy peaks at 32 in each direction), and for each nonzero tick increase the tremolo position by the speed. The stored volume is untouched.
  • Tremolo will not work if the stored volume is 0 (or 64 - adlib only).


Miscellaneous effects.

TODO: check what value xy is taken for Sxy


Set filter. Not implemented in Scream Tracker 3.


Set glissando control.


Set finetune.


Set vibrato waveform.


Set tremolo waveform.


Set panning position. Scream Tracker 3 supports this only on the Gravis Ultrasound.


Old stereo control? Not implemented in Scream Tracker 3.21?


Loop pattern.


Note cut after x ticks.


Note delay for x ticks.


Pattern delay for x rows.


FunkRepeat. Not implemented in Scream Tracker 3.


Set tempo. If the parameter is less than 33, the effect is ignored.

Uxy (*)

Fine vibrato. This effect shares memory with Hxy.


Set global volume. This effect has several quirks:

  • Normally, it does not affect events on the same row, where the effect is set. However, there are some exceptions to that rule, read below for details.
  • It does not affect past notes, that are still playing, unless their volume is changed, which applies the new global volume to that voice as well.
  • This effect is actually processed on tick 1 (that is the second tick) of the row. This has several consequences:
    • The effect doesn't do anything, if the current speed is 1.
    • The effect is applied to notes on the current row, that have a note delay effect (SDx with x >= 1). For notes on the same row that have a note delay of 1 tick, the effect is only applied to channels, that are processed after the channel with the set global volume effect. For notes on the same row that have a note delay of 2 ticks or more, the effect is applied regardless of the relative position of the channel in the processing order. TODO: Document the processing order, since it isn't very obvious (I think it's L1, L2, ..., L8, R1, R2, ..., R8, but I'm not 100% sure).
    • The effect is also applied on the same row if anything sets the volume on tick 1 or tick 2 (depends on processing order), like the Dxx effect (when doing a non-fine slide, of course).
  • Vxx with parameter values higher than 0x40 is ignored.