Metadata-Version: 2.4
Name: pyITupgrade
Version: 1.0.5
Summary: Python library for Impulse Tracker (IT) module files
Author: BrunoRNS, mike burke, maddie lim
License: AGPL-3.0-or-later
Project-URL: Home, https://github.com/BrunoRNS/pyITupgrade
Project-URL: Repository, https://github.com/BrunoRNS/pyITupgrade
Project-URL: Issues, https://github.com/BrunoRNS/pyITupgrade/issues
Project-URL: Documentation, https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/DOCS.md
Project-URL: Changelog, https://github.com/BrunoRNS/pyITupgrade/releases
Project-URL: OriginalImplementation, https://github.com/mRB0/pyIT
Project-URL: ReferenceGist, https://gist.github.com/maddievision/5019503
Project-URL: SchismTracker, https://github.com/schismtracker/schismtracker
Project-URL: PVSNESlib, https://github.com/alekmaul/pvsneslib
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.2.6
Requires-Dist: scipy>=1.15.3
Requires-Dist: scipy-stubs>=1.15.3.0
Requires-Dist: pydub>=0.25.1
Requires-Dist: audioop-lts; python_version >= "3.13"
Provides-Extra: test
Requires-Dist: pytest>=9.1.1; extra == "test"
Requires-Dist: pytest-mock>=3.12.0; extra == "test"
Requires-Dist: mutagen>=1.48.1; extra == "test"
Dynamic: license-file

# pyIT (upgraded version) – Impulse Tracker Module Library

**pyIT** is a modernized version of the original **[PyIT](https://github.com/mRB0/pyIT)** library by **[Mike Burke](https://github.com/mRB0)**. 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](https://gist.github.com/maddievision/5019503)** by **[Maddie Lim](https://github.com/maddievision)**, which preserves the original **[PyIT](https://github.com/mRB0/pyIT)** implementation by **[Mike Burke](https://github.com/mRB0)**. 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

```bash
pip install pyITupgrade
```

### From Source

Clone the repository and install in editable mode:

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

For development, install the test dependencies:

```bash
pip install -r test/test-requirements.txt
```

Detailed build instructions are available in [BUILDING_FROM_SOURCE.md](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/BUILDING_FROM_SOURCE.md).

## Quick Start

### Load and inspect an IT file

```python
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`

```python
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

```python
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

```python
from pyIT import IT2ogg

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

For more detailed usage, see the [full documentation](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/DOCS.md).

## 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](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/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:

```bash
make test
```

Detailed testing instructions are in [TESTING.md](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/TESTING.md).

## Contributing

We welcome contributions! Please read our [CONTRIBUTING.md](https://github.com/BrunoRNS/pyITupgrade/blob/main/CONTRIBUTING.md) for guidelines on reporting issues, submitting pull requests, and coding standards.

## Special Thanks

- **[Mike Burke](https://github.com/mRB0)** – for creating the original **[PyIT](https://github.com/mRB0/pyIT)** implementation, which inspired and served as the foundation for this project.
- **[Maddie Lim (maddievision)](https://github.com/maddievision)** – for publishing the original PyIT implementation as a **[GitHub Gist](https://gist.github.com/maddievision/5019503)**, 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](https://github.com/BrunoRNS/pyITupgrade/blob/main/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](https://gist.github.com/maddievision/5019503)**. 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](https://github.com/BrunoRNS/pyITupgrade)
- [Documentation](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/DOCS.md)
- [Building from Source](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/BUILDING_FROM_SOURCE.md)
- [Testing Guide](https://github.com/BrunoRNS/pyITupgrade/blob/main/docs/TESTING.md)
- [Contributing Guide](https://github.com/BrunoRNS/pyITupgrade/blob/main/CONTRIBUTING.md)
- [Issues](https://github.com/BrunoRNS/pyITupgrade/issues)
- [Releases / Changelog](https://github.com/BrunoRNS/pyITupgrade/releases)

### References

- [Original PyIT](https://github.com/mRB0/pyIT) by [Mike Burke](https://github.com/mRB0)
- [Reference GitHub Gist](https://gist.github.com/maddievision/5019503) by [Maddie Lim (maddievision)](https://github.com/maddievision)

### Dependencies

- [Schism Tracker](https://github.com/schismtracker/schismtracker)
- [PVSNESlib](https://github.com/alekmaul/pvsneslib)
