Crate ittech

Crate ittech 

Source
Expand description

§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

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