spectrumizer 0.1.0__py3-none-any.whl

spectrumizer/__init__.py

@@ -0,0 +1,13 @@
+"""spectrumizer — generate ZX Spectrum AY (PT3) music from public sources.
+
+Pipeline:  source -> IR (ir.Song) -> arrange (3 AY channels) -> PT3 bytes.
+
+LICENCE GUARDRAIL: spectrumizer does NOT launder licences. The licence of the
+SOURCE governs the OUTPUT. Only public-domain or your own material is safe to
+bundle into a game. See LICENSING.md.
+"""
+
+from .ir import Song, Note
+
+__all__ = ["Song", "Note"]
+__version__ = "0.1.0"

spectrumizer/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m spectrumizer ...`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spectrumizer/arrange/__init__.py

@@ -0,0 +1,126 @@
+"""Arranger: IR Song -> PT3 bytes.
+
+Channel allocation (3 AY channels, A governs pattern length so it gets the lead):
+  A = lead (top voice)
+  B = bass (bottom voice)
+  C = real drums if the source has them; else synth drums in chiptune style;
+      else the harmony (middle voice) in faithful style.
+
+`--style faithful|chiptune` selects which passes run — same engine, composable
+passes, not two code paths.
+"""
+
+from __future__ import annotations
+
+from ..ir import Song, Note
+from ..pt3 import (
+    midi_to_pt3_byte, NOTE_TO_BYTE, build_pt3,
+    DEFAULT_SAMPLES, DEFAULT_ORNAMENTS,
+    S_LEAD, S_BASS, S_HARMONY, S_SNARE, S_KICK, ORN_EMPTY,
+)
+from .model import Placed, rasterize, pack_patterns, ROWS_PER_PATTERN
+from .quantize import plan_grid, note_rows
+from .reduce import assign_voices
+from .embellish import octave_short_lead, synth_drums
+
+# GM percussion keys we treat as a kick (everything else on ch10 -> snare).
+GM_KICK_KEYS = {35, 36}
+DRUM_NOTE_BYTE = NOTE_TO_BYTE['C-4']     # dummy pitch; drum samples mute tone
+
+
+def vol_from_velocity(velocity: int, ceil: int, vmax: int) -> int:
+    """Map a MIDI velocity to an AY volume in 1..ceil, scaled so the piece's
+    loudest note reaches the channel's ceiling. `vmax <= 0` disables dynamics
+    (returns the ceiling), so a flat-velocity source stays at full volume."""
+    if vmax <= 0:
+        return ceil
+    return max(1, min(ceil, round(ceil * velocity / vmax)))
+
+
+def _line_to_placed(line: list[Note], rows_per_beat: int, total_rows: int,
+                    transpose: int, ceil_vol: int = 15, vmax: int = 0) -> list[Placed]:
+    out: list[Placed] = []
+    for n in line:
+        s, e = note_rows(n.start, n.end, rows_per_beat, total_rows)
+        if s >= total_rows:
+            continue
+        opts = {} if vmax <= 0 else {'vol': vol_from_velocity(n.velocity, ceil_vol, vmax)}
+        out.append(Placed(s, e, midi_to_pt3_byte(n.pitch, transpose), opts))
+    return out
+
+
+def _drums_to_placed(drums: list[Note], rows_per_beat: int, total_rows: int,
+                     ceil_vol: int = 13, vmax: int = 0) -> list[Placed]:
+    out: list[Placed] = []
+    for n in drums:
+        s, _ = note_rows(n.start, n.end, rows_per_beat, total_rows)
+        if s >= total_rows:
+            continue
+        sample = S_KICK if (n.pitch in GM_KICK_KEYS or n.pitch <= 36) else S_SNARE
+        opts = {'sample': sample}
+        if vmax > 0:
+            opts['vol'] = vol_from_velocity(n.velocity, ceil_vol, vmax)
+        out.append(Placed(s, s + 1, DRUM_NOTE_BYTE, opts))
+    return out
+
+
+def arrange(song: Song, *, style: str = 'faithful', rows_per_beat: int = 4,
+            speed: int | None = None, transpose: int = 0,
+            name: str | None = None, author: str = 'SPECTRUMIZER',
+            loop_pos: int = 0, dynamics: bool = True) -> tuple[bytes, dict]:
+    """Arrange `song` and return (pt3_bytes, stats).
+
+    `dynamics`: map MIDI velocity to per-note AY volume (on by default); the
+    loudest note in the piece sits at each channel's ceiling. False = flat
+    per-channel volume.
+    """
+    speed_v, total_rows = plan_grid(song, rows_per_beat, speed)
+
+    use_drum_channel = song.has_drums or style == 'chiptune'
+    n_pitched = 2 if use_drum_channel else 3
+    lead, bass, harmony = assign_voices(song.notes, n_pitched)
+
+    vmax = max((n.velocity for n in song.notes), default=0) if dynamics else 0
+    lead_p = _line_to_placed(lead, rows_per_beat, total_rows, transpose, 15, vmax)
+    bass_p = _line_to_placed(bass, rows_per_beat, total_rows, transpose, 14, vmax)
+
+    if song.has_drums:
+        dmax = max((n.velocity for n in song.drums), default=0) if dynamics else 0
+        c_p = _drums_to_placed(song.drums, rows_per_beat, total_rows, 13, dmax)
+        c_sample, c_vol, c_kind = S_SNARE, 13, 'drums'
+    elif style == 'chiptune':
+        c_p = synth_drums(total_rows, rows_per_beat, DRUM_NOTE_BYTE, S_SNARE, S_KICK)
+        c_sample, c_vol, c_kind = S_SNARE, 13, 'synth-drums'
+    else:
+        c_p = _line_to_placed(harmony, rows_per_beat, total_rows, transpose, 10, vmax)
+        c_sample, c_vol, c_kind = S_HARMONY, 10, 'harmony'
+
+    if style == 'chiptune':
+        octave_short_lead(lead_p, short_thresh_rows=rows_per_beat)
+
+    specs = [
+        (rasterize(lead_p, total_rows), S_LEAD, 15, ORN_EMPTY),
+        (rasterize(bass_p, total_rows), S_BASS, 14, ORN_EMPTY),
+        (rasterize(c_p, total_rows), c_sample, c_vol, ORN_EMPTY),
+    ]
+    patterns = pack_patterns(specs, total_rows)
+
+    pt3 = build_pt3(patterns, dict(DEFAULT_SAMPLES), dict(DEFAULT_ORNAMENTS),
+                    name=name or song.name or "SPECTRUMIZED",
+                    author=author, speed=speed_v, loop_pos=loop_pos)
+
+    stats = {
+        'style': style,
+        'dynamics': dynamics,
+        'speed': speed_v,
+        'rows_per_beat': rows_per_beat,
+        'total_rows': total_rows,
+        'patterns': len(patterns),
+        'tempo_bpm': round(song.tempo_bpm, 1),
+        'voices': {'lead': len(lead), 'bass': len(bass),
+                   'channel_c': c_kind,
+                   'harmony': len(harmony) if c_kind == 'harmony' else 0,
+                   'drums': len(song.drums)},
+        'bytes': len(pt3),
+    }
+    return pt3, stats

spectrumizer/arrange/embellish.py

@@ -0,0 +1,38 @@
+"""Chiptune embellishers (only run for --style chiptune).
+
+MVP passes:
+  * octave_short_lead — octave-double SHORT lead notes (the classic AY brightener;
+    held notes stay single-voice so they don't warble).
+  * synth_drums       — a backbeat (kick on beats 1&3, snare on 2&4) when the
+    source has no drum track, so chiptune output still has percussive drive.
+
+Planned next: chord arpeggios via ORN_MAJOR/ORN_MINOR (the ornament builders are
+already wired in pt3.ornaments) to fake polyphony on a single channel.
+"""
+
+from __future__ import annotations
+
+from .model import Placed
+from ..pt3 import ORN_OCTAVE, ORN_EMPTY
+
+
+def octave_short_lead(lead: list[Placed], short_thresh_rows: int) -> None:
+    """In place: octave ornament on notes shorter than the threshold."""
+    for p in lead:
+        p.opts['ornament'] = ORN_OCTAVE if (p.end - p.start) < short_thresh_rows else ORN_EMPTY
+
+
+def synth_drums(total_rows: int, rows_per_beat: int, drum_byte: int,
+                snare_sample: int, kick_sample: int) -> list[Placed]:
+    """A simple 4/4 backbeat occupying one channel (drums = noise, tone off)."""
+    placed: list[Placed] = []
+    n_beats = total_rows // rows_per_beat
+    for b in range(n_beats):
+        row = b * rows_per_beat
+        if row >= total_rows:
+            break
+        if b % 4 in (0, 2):
+            placed.append(Placed(row, row + 1, drum_byte, {'sample': kick_sample}))
+        else:
+            placed.append(Placed(row, row + 1, drum_byte, {'sample': snare_sample}))
+    return placed

spectrumizer/arrange/model.py

@@ -0,0 +1,74 @@
+"""Row-grid model + the bridge to the PT3 channel packer.
+
+A `Placed` note is a pitched/percussive event already quantised to integer rows.
+`rasterize` turns a channel's Placed notes into a per-row cell list (REST / OFF /
+note / (note, opts)); `pack_patterns` slices the song into fixed-size patterns
+and encodes each channel, enforcing the player's two hard invariants (see
+pt3.encode): every channel of a pattern encodes exactly ROWS_PER_PATTERN rows,
+and row 0 is never a dropped leading rest.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..pt3 import encode_channel, REST, OFF
+
+ROWS_PER_PATTERN = 64
+
+
+@dataclass
+class Placed:
+    start: int                       # start row (inclusive)
+    end: int                         # end row (exclusive)
+    note: int                        # PT3 note byte
+    opts: dict = field(default_factory=dict)   # vol / ornament / sample
+
+
+def rasterize(placed: list[Placed], total_rows: int) -> list:
+    """Channel Placed notes -> per-row cells of length total_rows."""
+    cells: list = [REST] * total_rows
+    placed = sorted(placed, key=lambda p: p.start)
+    for idx, p in enumerate(placed):
+        if p.start >= total_rows:
+            continue
+        cells[p.start] = (p.note, dict(p.opts)) if p.opts else p.note
+        nxt = placed[idx + 1].start if idx + 1 < len(placed) else total_rows
+        # cut the note (OFF) when there is a real gap before the next onset.
+        if p.end < nxt and 0 <= p.end < total_rows and cells[p.end] == REST:
+            cells[p.end] = OFF
+    return cells
+
+
+def pack_patterns(specs: list[tuple], total_rows: int,
+                  rows_per_pattern: int = ROWS_PER_PATTERN
+                  ) -> list[tuple[bytes, bytes, bytes]]:
+    """Encode 3 channels into a list of (A, B, C) byte triples.
+
+    specs: 3 tuples (cells, default_sample, default_volume, default_ornament),
+    one per AY channel, each `cells` of length total_rows. A held note that
+    crosses a pattern boundary is re-attacked at row 0 (pitch continuity);
+    genuine silence at row 0 is anchored with OFF so the packer doesn't drop it.
+    """
+    assert total_rows % rows_per_pattern == 0
+    n_pat = total_rows // rows_per_pattern
+    last_note: list = [None, None, None]
+    patterns: list[tuple[bytes, bytes, bytes]] = []
+
+    for pi in range(n_pat):
+        chans: list[bytes] = []
+        for ci, (cells, sample, vol, orn) in enumerate(specs):
+            sl = list(cells[pi * rows_per_pattern:(pi + 1) * rows_per_pattern])
+            if sl and sl[0] == REST:
+                sl[0] = last_note[ci] if last_note[ci] is not None else OFF
+            for cell in sl:
+                if cell == REST:
+                    continue
+                if cell == OFF:
+                    last_note[ci] = None
+                else:
+                    last_note[ci] = cell[0] if isinstance(cell, tuple) else cell
+            chans.append(encode_channel(sl, default_sample=sample,
+                                        default_volume=vol, ornament=orn))
+        patterns.append((chans[0], chans[1], chans[2]))
+    return patterns

spectrumizer/arrange/quantize.py

@@ -0,0 +1,36 @@
+"""Time -> PT3 row grid.
+
+PT3 has no tempo field beyond `speed` (frames per row). At the Spectrum's 50 Hz
+interrupt, rows/sec = bpm*rows_per_beat/60, so frames/row = 3000/(bpm*rpb).
+"""
+
+from __future__ import annotations
+
+import math
+
+from ..ir import Song
+from .model import ROWS_PER_PATTERN
+
+
+def plan_grid(song: Song, rows_per_beat: int = 4, speed: int | None = None,
+              rows_per_pattern: int = ROWS_PER_PATTERN) -> tuple[int, int]:
+    """Return (speed, total_rows). total_rows is rounded up to a whole number
+    of patterns."""
+    bpm = song.tempo_bpm or 120.0
+    if speed is None:
+        speed = round(3000.0 / (bpm * rows_per_beat))
+        speed = max(1, min(31, speed))
+
+    rows = math.ceil(song.length_beats * rows_per_beat)
+    rows = max(rows, rows_per_pattern)
+    rows = ((rows + rows_per_pattern - 1) // rows_per_pattern) * rows_per_pattern
+    return speed, rows
+
+
+def note_rows(start_beat: float, end_beat: float, rows_per_beat: int,
+              total_rows: int) -> tuple[int, int]:
+    s = round(start_beat * rows_per_beat)
+    e = round(end_beat * rows_per_beat)
+    s = max(0, min(total_rows - 1, s))
+    e = max(s + 1, min(total_rows, e))
+    return s, e

spectrumizer/arrange/reduce.py

@@ -0,0 +1,48 @@
+"""Polyphony reduction: many source voices -> at most 3 monophonic AY lines.
+
+`extract_line` peels one monophonic voice off a note set with a high/low
+preference (a greedy "skyline"): when two notes overlap, the preferred one wins
+and truncates the other. Calling it top-then-bottom-then-top yields lead / bass /
+harmony, with everything else dropped.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from ..ir import Note
+
+
+def extract_line(notes: list[Note], prefer: str = 'high'
+                 ) -> tuple[list[Note], list[Note]]:
+    """Return (line, leftover). `line` is monophonic (non-overlapping)."""
+    work = sorted((dataclasses.replace(n) for n in notes),
+                  key=lambda n: (n.start, n.pitch))
+    line: list[Note] = []
+    leftover: list[Note] = []
+    for n in work:
+        if line and n.start < line[-1].end - 1e-9:
+            prev = line[-1]
+            better = (n.pitch > prev.pitch) if prefer == 'high' else (n.pitch < prev.pitch)
+            if better:
+                if n.start - prev.start > 1e-9:
+                    prev.dur = n.start - prev.start      # truncate the loser
+                    line.append(n)
+                else:
+                    line.pop(); leftover.append(prev); line.append(n)
+            else:
+                leftover.append(n)
+        else:
+            line.append(n)
+    return line, leftover
+
+
+def assign_voices(notes: list[Note], n_pitched: int
+                  ) -> tuple[list[Note], list[Note], list[Note]]:
+    """Split into (lead, bass, harmony). harmony is empty if n_pitched < 3."""
+    lead, rem = extract_line(notes, 'high')
+    bass, rem2 = extract_line(rem, 'low')
+    harmony: list[Note] = []
+    if n_pitched >= 3:
+        harmony, _ = extract_line(rem2, 'high')
+    return lead, bass, harmony

spectrumizer/audio.py

@@ -0,0 +1,195 @@
+"""AY-3-8910 synthesiser + WAV rendering for PT3 playback.
+
+A deliberately small software AY: three square-wave tone generators, one 17-bit
+LFSR noise generator, per-channel tone/noise mixing and a 16-level logarithmic
+DAC. No envelope generator — spectrumizer's samples carry amplitude per tick, so
+the envelope path is never used. The point is to *audition* a module on any
+machine, not to be a cycle-exact emulator; pitch uses the exact PT3 tone table by
+default (`build_pt3_table`), with an equal-tempered fallback (`tuning='equal'`).
+"""
+
+from __future__ import annotations
+
+import math
+import shutil
+import struct
+import subprocess
+import wave
+from array import array
+
+from .pt3.player import Module, iter_frames, FRAME_HZ
+
+# AY clock on the 128K / +2 (Hz). Tone freq = clock / (16 * period).
+AY_CLOCK = 1773400
+DEFAULT_RATE = 44100
+
+# 16-level AY (not YM) DAC, normalised 0..1.
+AY_VOL = [
+    0.0, 0.00999, 0.01445, 0.02106, 0.03070, 0.04555, 0.06450, 0.10736,
+    0.12659, 0.20499, 0.29221, 0.37284, 0.49253, 0.63532, 0.80558, 1.0,
+]
+
+
+# --- the exact PT3 tone table (the real Spectrum pitches) ---------------------
+# Tone table #1 (the id the writer stamps), taken from the NoteTableCreator data
+# in Sergey Bulba's PT3 player (`T_PACK`, first physical table): the 12 packed
+# octave periods 0x06EC..0x0D10. The player stores them lowest-pitch first, so
+# we reverse to put C (largest period) at index 0, then build the 8 octaves by
+# the player's own successive /2 — `period(note) = base[note%12] >> note//12`.
+# (The player's two ±1 end-corrections are sub-cent and omitted.)
+PT3_T1_OCTAVE = [
+    0x0D10, 0x0C55, 0x0BA4, 0x0AFC, 0x0A5F, 0x09CA,   # C  C# D  D# E  F
+    0x093D, 0x08B8, 0x083B, 0x07C5, 0x0755, 0x06EC,   # F# G  G# A  A# B
+]
+
+
+def build_pt3_table() -> list:
+    """The exact PT3 tone-table-1 periods for note indices 0..95 (0 == C-1)."""
+    return [PT3_T1_OCTAVE[n % 12] >> (n // 12) for n in range(96)]
+
+
+def build_equal_table(clock: int = AY_CLOCK) -> list:
+    """Equal-tempered AY tone periods (A4=440) — the legacy approximation."""
+    table = []
+    for idx in range(96):
+        freq = 440.0 * 2.0 ** ((idx + 24 - 69) / 12.0)   # idx 0 -> MIDI 24 (C1)
+        table.append(max(1, min(4095, round(clock / (16.0 * freq)))))
+    return table
+
+
+_PT3_PERIOD = build_pt3_table()
+_EQ_PERIOD = build_equal_table()
+
+
+def render_pcm(module: Module, *, sample_rate: int = DEFAULT_RATE,
+               loops: int = 1, max_seconds: float | None = None,
+               noise_period: int | None = None, tuning: str = 'pt3',
+               stereo: str = 'abc', separation: float = 0.7,
+               gain: float = 0.9) -> tuple[array, int]:
+    """Render a parsed module to 16-bit PCM; returns ``(pcm, channels)``.
+
+    `tuning`: 'pt3' (default, the exact Spectrum tone table) or 'equal'.
+    `noise_period`: None (default) tracks the module's real per-frame AY noise
+    register (R6); pass 1..31 to force a fixed period.
+    `stereo`: 'abc' (A-left / B-centre / C-right, the classic ZX layout), 'acb',
+    or 'mono'. `separation`: 0..1 stereo width (0 = narrow, 1 = hard pan).
+    """
+    periods = _EQ_PERIOD if tuning == 'equal' else _PT3_PERIOD
+    spf = sample_rate // FRAME_HZ                      # output samples per frame
+    pcm = array('h')
+
+    # Per-channel L/R panning weights for channels A, B, C.
+    if stereo == 'mono':
+        channels = 1
+        pan_l = pan_r = (1.0, 1.0, 1.0)
+        norm_l = norm_r = 1.0 / 3.0
+    else:
+        channels = 2
+        sep = max(0.0, min(1.0, separation))
+        pos = {'abc': ('L', 'C', 'R'), 'acb': ('L', 'R', 'C')}.get(stereo,
+                                                                   ('L', 'C', 'R'))
+        wl = {'L': 1.0, 'R': 1.0 - sep, 'C': 0.7071}
+        wr = {'L': 1.0 - sep, 'R': 1.0, 'C': 0.7071}
+        pan_l = tuple(wl[p] for p in pos)
+        pan_r = tuple(wr[p] for p in pos)
+        norm_l = 1.0 / max(1e-6, sum(pan_l))
+        norm_r = 1.0 / max(1e-6, sum(pan_r))
+
+    phase = [0.0, 0.0, 0.0]
+    noise_acc = 0.0
+    lfsr = 1
+    noise_level = 1.0
+
+    for frame, noise_r6 in iter_frames(module, loops=loops, max_seconds=max_seconds):
+        # Precompute each channel's constant-per-frame parameters.
+        ch = []
+        for note_idx, amp, tone_on, noise_on in frame:
+            if amp <= 0 or note_idx is None:
+                ch.append(None)
+                continue
+            period = periods[note_idx] if 0 <= note_idx < 96 \
+                else periods[max(0, min(95, note_idx))]
+            inc = (AY_CLOCK / (16.0 * period)) / sample_rate
+            ch.append((inc, AY_VOL[amp], tone_on, noise_on))
+
+        # AY noise period this frame: the module-derived R6 (0 -> hardware 1),
+        # or a fixed override. Recomputed per frame so it tracks the song.
+        npd = noise_period if noise_period is not None else ((noise_r6 & 0x1F) or 1)
+        noise_step = (AY_CLOCK / 16.0 / npd) / sample_rate
+
+        for _s in range(spf):
+            # advance the shared noise LFSR
+            noise_acc += noise_step
+            while noise_acc >= 1.0:
+                noise_acc -= 1.0
+                newbit = (lfsr ^ (lfsr >> 3)) & 1
+                lfsr = (lfsr >> 1) | (newbit << 16)
+                noise_level = float(lfsr & 1)
+
+            left = right = 0.0
+            for ci in range(3):
+                c = ch[ci]
+                if c is None:
+                    continue
+                inc, vol, tone_on, noise_on = c
+                ph = phase[ci] + inc
+                if ph >= 1.0:
+                    ph -= int(ph)
+                phase[ci] = ph
+                t_eff = 1.0 if (not tone_on or ph < 0.5) else 0.0
+                n_eff = 1.0 if (not noise_on or noise_level >= 1.0) else 0.0
+                out = vol * t_eff * n_eff
+                left += out * pan_l[ci]
+                right += out * pan_r[ci]
+
+            lv = int(left * norm_l * gain * 32767.0)
+            pcm.append(-32768 if lv < -32768 else 32767 if lv > 32767 else lv)
+            if channels == 2:
+                rv = int(right * norm_r * gain * 32767.0)
+                pcm.append(-32768 if rv < -32768 else 32767 if rv > 32767 else rv)
+
+    return pcm, channels
+
+
+def write_wav(path: str, pcm: array, sample_rate: int = DEFAULT_RATE,
+              channels: int = 1) -> None:
+    with wave.open(path, 'wb') as w:
+        w.setnchannels(channels)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate)
+        w.writeframes(pcm.tobytes() if hasattr(pcm, 'tobytes') else struct.pack(
+            f'<{len(pcm)}h', *pcm))
+
+
+# Players to try, in order; first one found on PATH wins.
+_PLAYERS = (
+    ('afplay', []),
+    ('ffplay', ['-nodisp', '-autoexit', '-loglevel', 'quiet']),
+    ('aplay', ['-q']),
+    ('paplay', []),
+    ('play', ['-q']),                  # SoX
+)
+
+
+def play_wav(path: str) -> bool:
+    """Play a WAV with the first available system player. Returns success."""
+    for exe, flags in _PLAYERS:
+        found = shutil.which(exe)
+        if found:
+            subprocess.run([found, *flags, path], check=False)
+            return True
+    return False
+
+
+def duration_seconds(module: Module, *, loops: int = 1,
+                     max_seconds: float | None = None) -> float:
+    """Total play length in seconds (cheap: sums rows, no synthesis)."""
+    if max_seconds is not None:
+        return float(max_seconds)
+    speed = module.speed
+    frames = 0
+    from .pt3.player import _positions
+    for pidx in _positions(module, loops, unbounded=False):
+        if pidx < len(module.patterns):
+            frames += max(len(c) for c in module.patterns[pidx]) * speed
+    return frames / FRAME_HZ

spectrumizer/cli.py

@@ -0,0 +1,102 @@
+"""spectrumizer CLI: MIDI -> PT3."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+LICENCE_REMINDER = (
+    "reminder: the OUTPUT inherits the SOURCE's licence. Only bundle public-domain "
+    "or your own music into a release. See spectrumizer/LICENSING.md."
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="spectrumizer",
+        description="Generate ZX Spectrum AY (PT3) music from a MIDI source.")
+    p.add_argument("input", help="input .mid / .midi file")
+    p.add_argument("-o", "--output", help="output .pt3 (default: input with .pt3)")
+    p.add_argument("--style", choices=["faithful", "chiptune"], default="faithful",
+                   help="faithful 3-voice reduction, or chiptune embellishments "
+                        "(octave leads + synth drums). Default: faithful.")
+    p.add_argument("--rows-per-beat", type=int, default=4,
+                   help="grid resolution (4 = sixteenth notes). Default: 4.")
+    p.add_argument("--speed", type=int, default=None,
+                   help="PT3 speed (frames/row). Default: derived from tempo.")
+    p.add_argument("--transpose", type=int, default=0,
+                   help="semitones to shift all pitches (tune AY octave by ear).")
+    p.add_argument("--name", default=None, help="PT3 module title (<=32 chars).")
+    p.add_argument("--author", default="SPECTRUMIZER",
+                   help="PT3 module author (<=32 chars).")
+    p.add_argument("--loop-pos", type=int, default=0,
+                   help="position to loop back to after the song ends. Default 0.")
+    p.add_argument("--no-dynamics", dest="dynamics", action="store_false",
+                   help="flat per-channel volume instead of mapping MIDI velocity "
+                        "to AY volume (dynamics are on by default).")
+    p.add_argument("--play", action="store_true",
+                   help="after writing the .pt3, render it to audio and play it "
+                        "(software AY). See also the `spectrumizer-play` command.")
+    p.add_argument("-q", "--quiet", action="store_true",
+                   help="suppress the stats summary.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not os.path.isfile(args.input):
+        print(f"spectrumizer: input not found: {args.input}", file=sys.stderr)
+        return 2
+
+    out = args.output or (os.path.splitext(args.input)[0] + ".pt3")
+
+    # Imported lazily so `--help` works without mido installed.
+    from .inputs.midi import load_midi
+    from .arrange import arrange
+
+    song = load_midi(args.input)
+    if not song.notes and not song.drums:
+        print("spectrumizer: no notes found in input.", file=sys.stderr)
+        return 1
+
+    pt3, stats = arrange(
+        song, style=args.style, rows_per_beat=args.rows_per_beat,
+        speed=args.speed, transpose=args.transpose,
+        name=args.name, author=args.author, loop_pos=args.loop_pos,
+        dynamics=args.dynamics)
+
+    with open(out, "wb") as f:
+        f.write(pt3)
+
+    if not args.quiet:
+        v = stats["voices"]
+        print(f"spectrumizer: {args.input} -> {out}")
+        print(f"  style={stats['style']}  speed={stats['speed']}  "
+              f"tempo~{stats['tempo_bpm']}bpm  patterns={stats['patterns']}  "
+              f"bytes={stats['bytes']}")
+        print(f"  A=lead({v['lead']})  B=bass({v['bass']})  "
+              f"C={v['channel_c']}"
+              + (f"({v['harmony']})" if v['channel_c'] == 'harmony' else "")
+              + (f"  drums={v['drums']}" if v['drums'] else ""))
+        print(f"  {LICENCE_REMINDER}")
+
+    if args.play:
+        from .pt3.player import parse_module
+        from . import audio
+        module = parse_module(pt3)
+        wav = os.path.splitext(out)[0] + ".wav"
+        pcm, channels = audio.render_pcm(module)
+        audio.write_wav(wav, pcm, channels=channels)
+        if not args.quiet:
+            print(f"  playing {wav} ...")
+        if not audio.play_wav(wav):
+            print(f"spectrumizer: no system audio player found; open {wav} manually.",
+                  file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spectrumizer/inputs/__init__.py

@@ -0,0 +1 @@
+"""Input adapters: source format -> IR (spectrumizer.ir.Song)."""