Crate ittech

Impulse Tracker module file parser and writer

Impulse Tracker is a multi-track digital sound tracker (music sequencer). Originally released in 1995 by Jeffrey Lim as freeware with commercial extensions, it was one of the last tracker programs for the DOS platform.

– Wikipedia (article link)

This crate is a parser (and in the near future also hopefuly a writer) for the Impulse Tracker native module file format. The Rust representation attempts to both express the module file in a manner that’s lossless for valid files and that forbids creating invalid files.

Lossy parsing and canonicalization

For files outside of the specification there are multiple ways to handle them, the parser can either abort or can canonicalize the value to some “most sane” value, or can try to skip the invalid part.

Currently the parser will panic in cases that are not yet supported (implemented), but this should not be the case once enough of the format is implemented.

If the feature log is enabled, the crate with log an info message whenever some data from the input is lost and should explain what value was found, what is wrong with it and how it has been fixed. The canonicalization logic is documented under the “Canonicalization” section on each specific value type. Please report issues with any inconsistencies between the parsed results of and the documentation.

Structure and modfile representation

The general structure of a complete modfile (.it) can be simplified to this self-referencing tree. Complete modfiles are parsed using the parser::module_file function.

Module
  ├ Order ┄┄┄┐
  │          ┊
  ├ Pattern <┘
  │ │
  │ └ Row
  │   │
  │   └ Command ┐
  │             ┊
  ├ Instrument <┘
  │         ┊
  └ Sample <┘

Module contains Orders, Patterns, Instruments and Samples. Orders reference Patterns through PatternIds, Commands reference Instruments through InstrumentIds and Instruments reference Samples through SampleIds.

Patterns are a 2D sparse matrices of Commands stored row-wise in Rows.

Instruments can also exist on their own in instrument files (.iti). InstrumentFile only contains a single Instrument and its referenced samples. These files are parsed using the parser::instrument_file function.

InstrumentFile
  ├ Instrument
  │         ┊
  └ Sample <┘

Samples can also exist in their own files (.its) as just a lone Sample. These files are parsed using the parser::sample_file function.

Additional resources

• https://github.com/OpenMPT/openmpt/blob/master/soundlib/ITTools.h
• https://github.com/OpenMPT/openmpt/blob/master/soundlib/ITTools.cpp
• https://github.com/OpenMPT/openmpt/blob/master/soundlib/Load_it.cpp

Modules

error

Error management

ittech_txt

ITTECH.TXT (documentation only)

parser

Parsing functions

writer

Writing functions

Structs

ActiveChannels

Active channels in a particular pattern or module.

Channel

Channel number

Command

Pattern command

DosFilename

Envelope

EnvelopeFlags

EnvelopeLoop

Instrument

InstrumentFile

InstrumentFlags

Move boolean flags out of values.

InstrumentId

Module

ModuleFlags

Name

Node

Note

Note pitch representation

Pattern

Pattern

PatternId

RangedU8

Row

Pattern row

Sample

SampleId

SampleLoop

SampleMap

Enums

EffectCategory

Effect category

EffectCmd

Effect column commands

FileType

Impulse Tracker file types

FilterMode

NoteCmd

Note column commands

Order

PanningSlide

Effect Pxx Panning slide

PlayDirection

Portamento

Effects Exx, Fxx

SetNewNoteAction

SetPastNote

SetSampleOffset

Effects Oxx and SAy combined

Special

Effect Sxx Special commands

SurroundMode

Tempo

Effect Txx Change tempo

VolumeCmd

Volume column commands

VolumeSlide

Effects Dxx, Kxx, Lxx, Nxx, Wxx

Waveform

Oscillator waveforms for commands S3x, S4x and S5x

Traits

Get