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.
- Full IT file format support – read/write
.itfiles 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.
pip install pyITupgradeClone 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.txtDetailed build instructions are available in BUILDING_FROM_SOURCE.md.
from pyIT import ITfile
module = ITfile()
module.open("song.it")
print(f"Song: {module.SongName.decode()}, Patterns: {len(module.Patterns)}")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)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)from pyIT import IT2ogg
converter = IT2ogg("song.it", "song.ogg", sample_rate=44100)
converter.convert()For more detailed usage, see the full documentation.
- Python 3.10+
numpy,scipy,scipy-stubs– for waveform synthesispydub,audioop-lts (only python 3.13+)– for OGG encoding (requiresffmpeginstalled separately)
Optional test dependencies: pytest, pytest-mock, mutagen.
See BUILDING_FROM_SOURCE.md for instructions on building the package and creating a distributable wheel.
The test suite covers unit tests and integration tests (requires Schism Tracker, PVSNESlib, and a SNES emulator).
Run all tests with:
make testDetailed testing instructions are in TESTING.md.
We welcome contributions! Please read our CONTRIBUTING.md for guidelines on reporting issues, submitting pull requests, and coding standards.
- 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.
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.
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.
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.