Amiga MOD Generator

A collection of Python tools for creating, inspecting, rendering, and analysing Amiga ProTracker-style .mod music. The main workflow is the parametric generator: choose musical parameters, generate deterministic or randomized music, and optionally render the result to WAV with ImTrakker. The repository also contains focused generators for platformer music, TwinWorld SoundFX-based tracks, and a data-driven recreation workflow for walkyandtalky.

What this repository does

• Generates standard 2-channel, 3-channel, or 4-channel MOD files from musical parameters.
• Synthesizes looped melodic instruments and one-shot drum samples in Python/NumPy.
• Loads raw 8-bit ST sample-pack files and maps their measured pitch into MOD instruments.
• Provides a Tkinter GUI for generation, ST sample search/preview/assignment, WAV rendering, and playback.
• Extracts musical information from an input WAV into a JSON transcription: melody, bass, chords, and drum activity.
• Builds a searchable catalog for large extracted ST sample collections.
• Includes utilities for sample waveform inspection, chord dumps, balance checks, and render comparison.

The generated output is tracker music, not a general-purpose audio synthesizer. MOD playback depends on tracker-compatible handling of periods, effects, sample loops, pattern orders, speed, and tempo.

Requirements

Runtime

• Windows, macOS, or Linux with Python 3.10+ recommended.
• Python packages used by the full toolset:

numpy
soundfile
librosa
scipy
matplotlib

The basic parametric generator primarily needs numpy. The transcription and analysis utilities additionally need soundfile, librosa, and scipy; show_samples.py needs matplotlib. Tkinter is required for the GUI and is normally included with the Windows Python installer.

• An Amiga MOD player is required for listening. The examples use ImTrakker and its imtrakker.exe command-line renderer.

Install Python dependencies

From PowerShell in this directory:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install numpy soundfile librosa scipy matplotlib

If PowerShell blocks activation, run the scripts through the environment directly, for example .\.venv\Scripts\python.exe generator.py, or adjust the local execution-policy setting according to your machine policy.

Quick start

Generate the built-in demo:

python generator.py

This writes generator_demo.mod beside the script. The generator prints the output size, pattern count, bar count, tempo, channel count, and an ImTrakker render command.

Generate a custom track:

python generator.py `
  --key Cm `
  --mode dorian `
  --bpm 126 `
  --sections "intro 4; verse 8; chorus 8; bridge 4; chorus 8; outro 4" `
  --progression "Cm A#M Gm Fm" `
  --style epic `
  --density 0.7 `
  --variation 0.6 `
  --seed 42 `
  --out my_track.mod

Render it to WAV when ImTrakker is available:

& "C:\Development\ImTrakker\build\imtrakker.exe" `
  .\my_track.mod --dump-wav 120 .\audio\my_track.wav

The render duration should be at least the song duration. A useful estimate is bars * 4 * 60 / bpm + 2 seconds.

Main generator: generator.py

generator.py is the primary command-line interface. It creates new music from a key, mode, progression, section layout, groove, density, variation, instruments, and random seed. A seed makes the generated arrangement reproducible.

Command-line options

Option	Meaning	Default
--key	Tonal center, such as Am, C, or F#m	Am
--mode	ionian, dorian, phrygian, lydian, mixolydian, aeolian, or locrian	inferred from key
--bpm	Tempo in beats per minute	130
--progression	Explicit chord names, separated by spaces	automatic
--progression-style	Named progression template	automatic
--sections	Semicolon-separated section names and bar counts	automatic
--style	light, upbeat, or epic	upbeat
--channels	MOD channel count: 2, 3, or 4	4
--density	Melody/event density from 0 to 1	0.65
--variation	Amount of change between repeated sections from 0 to 1	0.5
--swing	Shuffle amount from 0 to 1	0
--drumkit	Fixed groove, such as ambient, four, break, or tech	section-dependent
--seed	Integer random seed	random
--bars	Minimum song length in bars	0
--length	Target length in seconds; adds chorus cycles	0
--inst-bass	Built-in bass instrument name	automatic
--inst-chord	Built-in chord instrument name	automatic
--inst-lead	Built-in lead instrument name	automatic
--st-dir	Directory containing raw ST samples	none
--st-bass, --st-chord, --st-lead	ST sample filename for a role	none
--batch	Number of varied tracks to generate	0
--out	Output filename	generator_demo.mod

Use python generator.py --help for the authoritative option list.

Musical syntax

A section specification is a semicolon-separated list. Section names are normally intro, verse, chorus, bridge, and outro; the number after each name is the bar count:

intro 4; verse 8; chorus 8; bridge 4; outro 4

Explicit progressions use chord names such as Am F C G, Cm A#M Gm Fm, or F#m D A E. The parser supports major/minor chord spelling used by the generator. If no progression is supplied, the selected mode and progression style determine one automatically.

Built-in instrument families

Instrument names are defined in generator.py. Bass choices include bass, sub, tb303, squareb, sawhore, and tuba; chord choices include chord, organ, pad, and stringsE; lead choices include lead, squareL, sineL, bright, flute, and sawlead.

Example:

python generator.py --key D --mode dorian --bpm 118 `
  --progression-style blues --drumkit break `
  --inst-bass tb303 --inst-chord organ --inst-lead bright `
  --seed 9 --out dorian_break.mod

Batch generation

Batch mode creates several tracks with varied keys, modes, progressions, tempos, styles, grooves, instruments, structures, and channel counts:

python generator.py --batch 12 --seed 123 --out batch.mod

The output stem is used to name the files, for example batch_1.mod, batch_2.mod, and so on. Batch mode is useful for quickly producing alternatives; retain the seed and command line if a result needs to be recreated.

Graphical interface: generator_gui.py

Run:

python generator_gui.py

The GUI exposes the main generator parameters, section presets, density/variation/swing controls, built-in instruments, and the ST sample catalog. Its output actions are:

• Generate .mod — create the tracker file only.
• Generate + render .wav — create the MOD and ask ImTrakker to render it into audio\.
• Generate + play in ImTrakker — create the MOD and open it in ImTrakker.
• Open .mod in ImTrakker — open the last generated file or choose another MOD.
• Play .wav — play the most recently rendered WAV using the operating system.

The GUI auto-detects ImTrakker at two paths under C:\Development\ImTrakker. If it is installed elsewhere, pass its executable explicitly:

python generator_gui.py --imtrakker "D:\Apps\ImTrakker\imtrakker.exe"

ST samples can be searched, previewed, assigned to bass/chord/lead, or randomized. Assignments are passed to the same generator engine used by the CLI.

ST sample packs and catalog

The repository expects extracted raw sample files under st_packs\extracted\<PACK>. These files are intentionally ignored by Git because a complete sample collection can be large. st_catalog.json is the generated searchable index.

Rebuild the catalog after adding or removing packs:

python catalog_st.py --rebuild

Search all packs:

python catalog_st.py bass

Search one pack and increase the result limit:

python catalog_st.py bigsnare --pack ST-05 --limit 200

List pack counts:

python catalog_st.py --list-packs

A raw ST sample is treated as signed 8-bit PCM. The generator folds the source into a clean loop, estimates its fundamental by autocorrelation, and uses that measured root to transpose the sample more reliably than trusting a filename alone.

Audio transcription and recreation workflow

transcribe.py analyses audio\walkyandtalky.wav on a 16th-note grid at 130 BPM. It separates harmonic and percussive material, extracts bass and lead estimates, detects kick/snare/hat activity, and estimates a per-bar chord root and quality. It writes transcription.json:

python transcribe.py

The data-driven MOD builder is sunnyland_mod_v2.py. It reads the transcription and writes walkyandtalky_4ch.mod:

python sunnyland_mod_v2.py

This is a recreation pipeline, not the same as generator.py: it follows detected source material rather than inventing a new arrangement. Earlier variants (sunnyland_mod.py and sunnyland_mod_4ch.py) remain useful for comparing approaches.

Additional generators

platformer.py

Creates a self-contained 3-channel platformer track with bounce bass, blip lead, bell lead, pad, and synthesized drums:

python platformer.py --key C --bpm 120 `
  --sections "intro 4;verse 8;chorus 8;bridge 4;chorus 8;outro 4" `
  --seed 7 --out bg.mod

sfx_songs.py

Builds four tracks from real instruments extracted from TwinWorld's title.sfx. This script contains machine-specific paths into the TwinWorld checkout and requires that source asset and sfx_to_mod import to exist. It is not portable without adjusting those paths.

show_samples.py

Reads sample headers and PCM from a MOD and writes waveform plots. Update its hard-coded input/output paths before use if your files are not under the original SunnyLand checkout.

showchords.py

Prints the per-bar chord progression stored in transcription.json:

python showchords.py

balance.py and compare2.py

These are project-specific analysis scripts. balance.py renders full, drums-only, and melodic-only variants and compares RMS/peak levels. compare2.py compares an original WAV and a rendered WAV using per-bar energy correlation, chroma correlation, spectral centroid, tempo, and peak level. Both contain hard-coded paths and should be edited before reuse in another checkout.

Generated MOD internals

The generator writes a classic ProTracker-compatible file with:

1. A 20-byte title.
2. 31 sample headers.
3. Song length and restart position.
4. A 128-entry pattern order table.
5. A channel signature such as 2CHN, 3CHN, or M.K..
6. Packed pattern rows and tracker effects.
7. Sample PCM data, including loop metadata where appropriate.

The music is arranged at 16 rows per bar and four bars per pattern. The engine uses tracker effects including arpeggio (0xy), vibrato (4xy), note cuts, speed/tempo changes, and sample retriggers. The effective playback tempo is represented by MOD speed/tempo values rather than by embedding rendered audio.

Reproducibility and output hygiene

• Use --seed whenever you want a track to be reproducible.
• Keep generated .mod and .wav files outside source control unless they are intentional examples; .mod and WAV files are ignored by the current .gitignore.
• Do not commit chat_history_*.jsonl, local logs, or extracted sample packs.
• st_catalog.json contains paths generated on the machine that built it. Rebuild it if the project moves or if paths need to be portable.
• The scripts write outputs relative to the script directory in several places, so invoke them from the repository or verify the output path printed by the script.

Troubleshooting

ModuleNotFoundError

Activate the virtual environment and install the packages listed above. The basic generator.py path does not require the audio-analysis packages, but GUI, transcription, and comparison features have additional dependencies.

GUI opens but rendering does not work

Confirm that the ImTrakker executable exists and launch with --imtrakker. The GUI logs render stdout/stderr in its output panel. Generation itself does not require ImTrakker.

No ST samples appear

Confirm that st_packs\extracted exists, contains pack directories, and that st_catalog.json was rebuilt. The catalog command reports the scanned file and pack totals.

A generated MOD is silent or sounds wrong

Open it in a tracker-compatible player and check the printed channel signature and pattern count. Verify that the selected sample is non-empty, that the output was not truncated, and that the player supports the MOD effects used. Rendering through ImTrakker is a useful independent playback check.

Transcription fails at startup

Verify audio\walkyandtalky.wav exists and is readable. The analysis assumes 44.1 kHz-compatible audio processing and uses librosa/scipy filters; malformed or missing input must be fixed before rerunning.

Development notes

The codebase is intentionally script-oriented. generator.py contains synthesis, instrument registration, arrangement, pattern construction, and MOD serialization in one module. If extending it, preserve the sample dictionary fields (name, wave, n_frames, kind, finetune, and vol) expected by the serializer and keep generated sample lengths/loop points valid for tracker playback.

Before committing a change, run the relevant script with a small deterministic example and inspect the produced MOD in a tracker or render it to WAV. For changes to transcription, regenerate transcription.json and compare the resulting render with the source using compare2.py after updating its paths.

License and source assets

No license file or dependency lockfile is currently present. Check the provenance and redistribution terms for any included or extracted audio assets before publishing generated tracks or sample packs.