# Maxentius MIDI Converter

**v1.0.1** — by [Maxentius Plays](https://maxentiusplays.com/)

Convert MIDI files into `.uge` tracker files compatible with [hUGETracker](https://nickfa.ro/index.php/HUGETracker) for Game Boy music composition.

---

## Getting Started

1. Download `Maxentius MIDI Converter.exe`
2. Double-click to run — no installation required
3. Select a MIDI file, adjust settings, click **Run Conversion**
4. Output is saved to the `output/` folder next to the `.exe`

---

## Settings Reference

### MIDI Source

| Field | Description |
|---|---|
| **MIDI File** | Path to the `.mid` input file. Use the **Browse** button to open a file picker. |

---

### Song Info

| Field | Description |
|---|---|
| **Title** | Song name written into the `.uge` file header. Defaults to the MIDI filename. |
| **Author** | Author name written into the `.uge` file header. |
| **Comment** | Optional comment written into the `.uge` file header. |

---

### Timing

| Field | Default | Description |
|---|---|---|
| **Ticks / Row** | `6` | How many MIDI ticks map to one tracker row. Lower = faster playback; higher = slower. Affects note granularity and tempo. |
| **Est. BPM** | *(calculated)* | Estimated playback BPM, shown live as you adjust Ticks/Row. Calculated as approximately `900 ÷ ticks_per_row`. |

---

### Voice Split (Pitch Thresholds)

The converter splits MIDI notes across three Game Boy channels by pitch. These thresholds control the split points.

| Field | Default | Description |
|---|---|---|
| **P1 Min Pitch** | `60` | MIDI note number. Notes at or above this pitch go to **Pulse 1**. |
| **P2 Min Pitch** | `48` | MIDI note number. Notes at or above this pitch (but below P1 Min) go to **Pulse 2**. Notes below this go to **Wave**. |

**MIDI pitch reference:** C4 (middle C) = 60, C3 = 48, C5 = 72.

> Example with defaults: Pitch 72+ → Pulse 1, Pitch 48–71 → Pulse 2, Pitch 0–47 → Wave.

---

### Channel Settings

Each Game Boy channel has independent settings. The four channels are:

- **Pulse 1** (square wave, melody — typically highest pitch)
- **Pulse 2** (square wave, harmony — typically mid pitch)
- **Wave** (custom waveform, bass/lead)
- **Noise** (percussion — maps non-melodic MIDI notes)

#### Octave Shift

| Field | Default | Range | Description |
|---|---|---|---|
| **P1 Oct** | `-1` | `-4` to `+4` | Shifts Pulse 1 notes up or down by octaves after conversion. |
| **P2 Oct** | `-1` | `-4` to `+4` | Shifts Pulse 2 notes up or down by octaves. |
| **Wv Oct** | `+1` | `-4` to `+4` | Shifts Wave channel notes up or down by octaves. |
| **Ns Oct** | `0` | `-4` to `+4` | Shifts Noise channel notes up or down by octaves. |

Use octave shift to correct pitch if a channel sounds too high or too low after conversion.

#### Duty Cycle (Pulse 1 & Pulse 2 only)

Controls the tone character of the square wave channels.

| Value | Sound Character |
|---|---|
| `12.5%` | Thin, buzzy |
| `25%` | Brighter, hollow |
| `50%` | Full, rounded square wave |
| `75%` | Same as 25% (inverted) |

#### Waveform (Wave channel only)

Selects the waveform shape for the Wave channel.

| Waveform | Character |
|---|---|
| `Sine` | Smooth, mellow tone |
| `Triangle` | Soft, flute-like |
| `Square 50%` | Buzzy, bright |
| `Sawtooth Up` | Bright, harsh |
| `Sawtooth Dn` | Bright, harsh (reverse) |
| `Organ` | Richer, organ-like (sine + 2nd harmonic) |

#### Volume

| Field | Default | Range | Description |
|---|---|---|---|
| **P1 Vol** | `15` | `0–15` | Volume level for Pulse 1 notes. |
| **P2 Vol** | `15` | `0–15` | Volume level for Pulse 2 notes. |
| **Wv Vol** | `15` | `0–15` | Volume level for Wave channel notes. |
| **Ns Vol** | `15` | `0–15` | Volume level for Noise channel notes. |

#### Wave Output Level (Wave channel only)

Hardware-level volume control for the Wave channel, independent of the note volume.

| Value | Output |
|---|---|
| `100%` | Full volume |
| `50%` | Half volume |
| `25%` | Quarter volume |
| `Mute` | Silent |

---

## Output

Converted `.uge` files are saved to the `output/` folder in the same directory as the `.exe`. Files are automatically named after the input MIDI file with a `.uge` extension. Existing files with the same name are overwritten.

Open the output `.uge` file in [hUGETracker](https://nickfa.ro/index.php/HUGETracker) to edit, preview, and export to Game Boy ROM.

---

## Tips

- **Tempo too fast?** Increase Ticks/Row.
- **Channels overlapping oddly?** Adjust the P1/P2 pitch thresholds to redistribute notes.
- **Wave channel too quiet?** Set Wave Output Level to `100%` and increase Wv Vol.
- **Pitch sounds wrong?** Use the Octave Shift spinboxes to move a channel up or down.
- **Noise channel empty?** Noise picks up any notes that don't land on Pulse 1, 2, or Wave after the split — this is normal for melodic MIDI files with no percussion track.

---

## Compatibility

- **Output format:** hUGETracker v6 `.uge`
- **Input:** Standard MIDI format 0 or format 1 (single or multi-track)
- **OS:** Windows 10/11 (64-bit)
- **Requirements:** None — fully self-contained `.exe`

---

## About

**Maxentius MIDI Converter** is a free tool by [Maxentius Plays](https://maxentiusplays.com/).

Visit the blog for Game Boy music tutorials, tracker guides, and more.

> © 2026 Maxentius Plays — v1.0.1

---

## Changelog

### v1.0.1
- Fixed: output `.uge` files now correctly save to the `output/` folder next to the `.exe`. Previously, when running as a compiled executable, output was written to a temporary directory and lost on exit.

### v1.0.0
- Initial release.
