pyIT (upgraded version) – Impulse Tracker Module Library

pyIT is a modernized version of the original PyIT library by Mike Burke. It builds upon the original implementation with bug fixes, compatibility improvements, new features, and long-term maintenance, while preserving its purpose as a library for working with Impulse Tracker (IT) module files.

It provides a complete toolkit to programmatically create, edit, and convert .it files, with support for patterns, instruments, samples, envelopes, and rendering to audio or SNES soundbanks.

This project was developed by refactoring the archived Python 2 version published as a GitHub Gist by Maddie Lim, which preserves the original PyIT implementation by Mike Burke. The codebase has since been modernized and expanded into a fully maintained Python 3.10+ implementation, with numerous bug fixes, compatibility improvements, refactoring, and new features.

Features

• Full IT file format support – read/write .it files with all header, pattern, instrument, sample, and envelope data.
• Pattern construction – build patterns from simple note sequences or guitar-style tablature.
• Instrument & sample creation – load WAV files, generate basic waveforms (sine, square, saw, etc.), and map samples to notes.
• Envelope editing – volume, pan, and pitch envelopes with loop and sustain points.
• Audio rendering – convert modules to OGG Vorbis using Schism Tracker (or a custom renderer).
• SNES integration – prepare IT files for smconv (PVSNESlib) to create soundbanks for Super Nintendo homebrew.
• Pure Python – no external runtime dependencies beyond Python and standard scientific libraries.

Installation

From PyPI

pip install pyITupgrade

From Source

Clone the repository and install in editable mode:

git clone https://github.com/BrunoRNS/pyITupgrade.git
cd pyITupgrade
pip install -e .

For development, install the test dependencies:

pip install -r test/test-requirements.txt

Detailed build instructions are available in BUILDING_FROM_SOURCE.md.

Quick Start

Load and inspect an IT file

from pyIT import ITfile

module = ITfile()
module.open("song.it")
print(f"Song: {module.SongName.decode()}, Patterns: {len(module.Patterns)}")

Create a simple pattern with PatternBuilder

from pyIT import PatternBuilder

builder = PatternBuilder(bpm=180, lines_per_note=2)
pattern = builder.build_pattern(["C-5", "A-4", None, "G-4"], instrument_id=1)

Add a WAV sample as an instrument

from pyIT import WavInstrumentBuilder

instrument, sample = WavInstrumentBuilder.create_from_wav("piano.wav")
for note in range(120):
    instrument.SampleTable[note] = [note, 1]   # map all notes to this sample
module.Instruments.append(instrument)
module.Samples.append(sample)

Render to OGG

from pyIT import IT2ogg

converter = IT2ogg("song.it", "song.ogg", sample_rate=44100)
converter.convert()

For more detailed usage, see the full documentation.

Dependencies

• Python 3.10+
• numpy, scipy, scipy-stubs – for waveform synthesis
• pydub, audioop-lts (only python 3.13+) – for OGG encoding (requires ffmpeg installed separately)

Optional test dependencies: pytest, pytest-mock, mutagen.

Building from Source

See BUILDING_FROM_SOURCE.md for instructions on building the package and creating a distributable wheel.

Testing

The test suite covers unit tests and integration tests (requires Schism Tracker, PVSNESlib, and a SNES emulator).
Run all tests with:

make test

Detailed testing instructions are in TESTING.md.

Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines on reporting issues, submitting pull requests, and coding standards.

Special Thanks

• Mike Burke – for creating the original PyIT implementation, which inspired and served as the foundation for this project.
• Maddie Lim (maddievision) – for publishing the original PyIT implementation as a GitHub Gist, making it accessible and preserving it for others to build upon.
• Schism Tracker Community – for creating and maintaining the excellent Schism Tracker, which powers the audio rendering capabilities of this library.
• PVSNESlib Developers – for the tools that enable IT modules to run on SNES hardware.

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for details.

Licensing Notice

Versions 1.0.4 and earlier were mistakenly released under GPL-3.0-or-later. During a review of the project's history and upstream sources, it was determined that the project contains code derived from the original PyIT implementation, including components originating from AGPL-licensed source files. To correctly reflect the licensing of the upstream codebase, the project is now distributed under AGPL-3.0-or-later. This change is intended as a correction of the project's licensing information. Beginning with version 1.0.5, all references to GPL-3.0-or-later have been removed from the repository and replaced with AGPL-3.0-or-later.

GPL-2.0-or-later Notice

The project also incorporates code originating from a historical Python 2 reference implementation published as a GitHub Gist. That code includes components licensed under GNU GPL v2.0 or later. Because the original license explicitly permits distribution under later GPL versions ("or any later version"), its inclusion is compatible with this project's licensing under AGPL-3.0-or-later.

Links

Project

• Repository
• Documentation
• Building from Source
• Testing Guide
• Contributing Guide
• Issues
• Releases / Changelog

References

• Original PyIT by Mike Burke
• Reference GitHub Gist by Maddie Lim (maddievision)

Dependencies

• Schism Tracker
• PVSNESlib