spectrumizer 0.1.0__tar.gz

spectrumizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Ángel Esteve Marco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spectrumizer-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: spectrumizer
+Version: 0.1.0
+Summary: Generate ZX Spectrum AY (PT3) music from MIDI and other sources.
+Author-email: Miguel Ángel Esteve Marco <esteve@telemaco.es>
+License: MIT
+Project-URL: Homepage, https://github.com/revengator/spectrumizer
+Project-URL: Repository, https://github.com/revengator/spectrumizer
+Project-URL: Issues, https://github.com/revengator/spectrumizer/issues
+Keywords: zx-spectrum,ay-3-8910,pt3,vortex-tracker,chiptune,midi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mido<2.0,>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: demos
+Requires-Dist: lameenc>=1.5; extra == "demos"
+Dynamic: license-file
+
+# spectrumizer
+
+[![CI](https://github.com/revengator/spectrumizer/actions/workflows/ci.yml/badge.svg)](https://github.com/revengator/spectrumizer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Live demos](https://img.shields.io/badge/%E2%96%B6-live%20demos-brightgreen.svg)](https://revengator.github.io/spectrumizer/)
+
+Generate **ZX Spectrum AY music (`.pt3`)** from public sources (MIDI now;
+MusicXML/scores planned). The output is a standard Vortex Tracker / Sergey
+Bulba PT3 module, so anything it produces drops straight into a Spectrum game
+that ships a PT3 replayer.
+
+Instead of typing every arrangement note-by-note in Python, you feed a source
+file and spectrumizer arranges it down to the AY's 3 channels (+ noise).
+
+**▶ Hear it in your browser:** [demo page](https://revengator.github.io/spectrumizer/)
+· or the [Demos](#demos) section below.
+
+> ⚠️ **Licence:** spectrumizer does **not** launder licences. The licence of the
+> SOURCE governs the OUTPUT — a `.pt3` from a copyrighted MIDI is still
+> copyrighted. Only bundle **public-domain or your own** music into a release.
+> Read [`LICENSING.md`](LICENSING.md).
+
+## Install
+
+```bash
+pip install -e .            # from a clone — installs the `spectrumizer` command + deps
+```
+
+Or, without installing the package:
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+```
+
+All deps are pure-Python (`mido`), so the same wheels work on Intel & Apple
+Silicon — no native build step.
+
+## Use
+
+```bash
+# faithful 3-voice reduction
+spectrumizer song.mid -o song.pt3                 # or: python -m spectrumizer song.mid -o song.pt3
+
+# chiptune flavour: octave-doubled leads + synth drums when the source has none
+spectrumizer song.mid -o song.pt3 --style chiptune
+
+# tune the AY octave by ear, change grid/tempo
+spectrumizer song.mid --transpose -12 --rows-per-beat 4 --speed 6 \
+    --name "MY THEME" --author "ME"
+
+# dynamics: MIDI velocity drives per-note volume (on by default)
+spectrumizer song.mid -o song.pt3 --no-dynamics      # ...or flat per-channel volume
+
+# generate and immediately hear it (renders through a software AY, then plays)
+spectrumizer song.mid -o song.pt3 --play
+```
+
+Run `spectrumizer --help` for all flags.
+
+## How it works
+
+```
+MIDI ─(inputs/midi.py, mido)→ IR ─(arrange/)→ 3 AY channels ─(pt3/)→ .pt3
+```
+
+- **`spectrumizer/pt3/`** — the proven PT3 emitter (note encoding, channel packer,
+  samples, ornaments, file writer). The byte format is verified against the real
+  player; don't change it blindly.
+- **`spectrumizer/arrange/`** — the hard part:
+  - `quantize` — map time to PT3's row grid (derive `speed` from tempo).
+  - `reduce` — peel the source polyphony into ≤3 monophonic lines (lead / bass /
+    harmony) via a greedy high/low "skyline".
+  - `embellish` — chiptune passes (octave leads, synth drums; chord arps planned).
+  - dynamics — MIDI velocity → per-note AY volume, normalised so the piece's
+    loudest note hits each channel's ceiling (on by default; `--no-dynamics`).
+  - Channel allocation: **A = lead, B = bass, C =** real drums if present, else
+    synth drums (chiptune), else harmony (faithful).
+- **`spectrumizer/ir.py`** — the source-agnostic note model both inputs target.
+
+### PT3 invariants baked in (from the player source)
+
+The player ends a pattern when **channel A** hits its `0x00` terminator and then
+resets all three channels — so every channel of a pattern encodes **exactly**
+`ROWS_PER_PATTERN` (64) rows, and row 0 is never an empty rest (the packer drops
+leading rests). `arrange/model.py` enforces both.
+
+## Listen to it (no Spectrum needed)
+
+spectrumizer ships its own playback path: a small software **AY-3-8910** that
+renders a `.pt3` to a stereo `.wav` (classic ABC panning — A left, B centre,
+C right) and plays it through your system audio player (`afplay` on macOS;
+`ffplay` / `aplay` / `paplay` / `sox` elsewhere).
+
+```bash
+spectrumizer-play song.pt3            # render song.wav and play it
+spectrumizer-play song.pt3 --no-play  # just write the .wav
+spectrumizer-play song.pt3 --seconds 30   # cap length, looping the song's tail
+spectrumizer-play song.pt3 --rate 22050   # faster render (lower fidelity)
+spectrumizer-play song.pt3 --tuning equal # equal-tempered instead of the PT3 table
+spectrumizer-play song.pt3 --stereo mono  # mono (default abc = A-left/B-centre/C-right)
+spectrumizer-play song.pt3 --noise-period 5  # force a noise period (default: the module's real one)
+```
+
+The synth (`spectrumizer/audio.py`) plus the PT3 interpreter
+(`spectrumizer/pt3/player.py`, the inverse of the encoder) only implement the
+subset of PT3 this tool emits — notes, OFF, sample/ornament/volume, NtSkip. Pitch
+uses the **exact PT3 tone table** (the table-1 periods from the real Bulba player,
+so notes land where the chip puts them; pass `--tuning equal` for the old
+equal-tempered approximation). Treat it as a faithful **audition**, not a
+cycle-exact emulation. For the real thing, drop the `.pt3` into the PT3 slot of a
+128K Spectrum build running a Bulba/Vortex replayer, rebuild, and run it in an
+emulator (e.g. ZEsarUX).
+
+## Demos
+
+Hear every mode in your browser on the **[demo page](https://revengator.github.io/spectrumizer/)**
+(GitHub Pages, nothing to install) — or click a clip to play it in GitHub's file
+viewer. All are `examples/ode-to-joy.mid` rendered through the built-in software
+AY; regenerate with `pip install -e ".[demos]" && python examples/make_demos.py`.
+
+| Demo | What it shows |
+|---|---|
+| ▶ [Faithful](docs/audio/faithful.mp3) | 3-voice reduction |
+| ▶ [Chiptune](docs/audio/chiptune.mp3) | octave lead + synth drums |
+| ▶ [No dynamics](docs/audio/chiptune-flat.mp3) | flat volume — vs the velocity dynamics |
+| ▶ [Equal-tempered](docs/audio/chiptune-equal.mp3) | vs the exact PT3 tone table |
+| ▶ [Mono](docs/audio/chiptune-mono.mp3) | vs the default ABC stereo |
+
+## Tests
+
+```bash
+pip install -e ".[dev]"     # installs pytest
+pytest -q
+```
+
+## Status
+
+- **Generate:** MIDI → PT3, faithful + chiptune, with velocity-driven dynamics.
+- **Audition:** built-in software-AY playback to a stereo WAV — exact PT3 tone
+  table, real per-frame noise period, ABC panning (`spectrumizer-play` / `--play`).
+- **Planned:** MusicXML (music21) input, chord arpeggios, AY hardware envelopes
+  (buzzer bass), general PT3 playback (envelope/slides), raw-AY/`.vtx` export.
+
+## Origin
+
+spectrumizer grew out of hand-written, per-track PT3 composer scripts for a ZX
+Spectrum game, generalising them into a single reusable arranger. It is now a
+standalone, game-agnostic tool.
+
+## Credits
+
+- **Sergey Bulba** — the PT3 module format and the Vortex Tracker / PT3 replayer
+  this tool targets, including the NoteTableCreator tone-table data the audition
+  synth uses for exact Spectrum pitches.
+- **Ivan Roshin** — NoteTableCreator, the source of those packed AY tone tables.
+
+These credits acknowledge the format and reference data; spectrumizer's encoder,
+decoder and synth are independent implementations (see [`LICENSE`](LICENSE)).
+
+## Licence
+
+[MIT](LICENSE) © Miguel Ángel Esteve Marco. Note: the MIT licence covers
+**spectrumizer's own code**, not the music you run through it — see
+[`LICENSING.md`](LICENSING.md).

spectrumizer-0.1.0/README.md

@@ -0,0 +1,166 @@
+# spectrumizer
+
+[![CI](https://github.com/revengator/spectrumizer/actions/workflows/ci.yml/badge.svg)](https://github.com/revengator/spectrumizer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Live demos](https://img.shields.io/badge/%E2%96%B6-live%20demos-brightgreen.svg)](https://revengator.github.io/spectrumizer/)
+
+Generate **ZX Spectrum AY music (`.pt3`)** from public sources (MIDI now;
+MusicXML/scores planned). The output is a standard Vortex Tracker / Sergey
+Bulba PT3 module, so anything it produces drops straight into a Spectrum game
+that ships a PT3 replayer.
+
+Instead of typing every arrangement note-by-note in Python, you feed a source
+file and spectrumizer arranges it down to the AY's 3 channels (+ noise).
+
+**▶ Hear it in your browser:** [demo page](https://revengator.github.io/spectrumizer/)
+· or the [Demos](#demos) section below.
+
+> ⚠️ **Licence:** spectrumizer does **not** launder licences. The licence of the
+> SOURCE governs the OUTPUT — a `.pt3` from a copyrighted MIDI is still
+> copyrighted. Only bundle **public-domain or your own** music into a release.
+> Read [`LICENSING.md`](LICENSING.md).
+
+## Install
+
+```bash
+pip install -e .            # from a clone — installs the `spectrumizer` command + deps
+```
+
+Or, without installing the package:
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+```
+
+All deps are pure-Python (`mido`), so the same wheels work on Intel & Apple
+Silicon — no native build step.
+
+## Use
+
+```bash
+# faithful 3-voice reduction
+spectrumizer song.mid -o song.pt3                 # or: python -m spectrumizer song.mid -o song.pt3
+
+# chiptune flavour: octave-doubled leads + synth drums when the source has none
+spectrumizer song.mid -o song.pt3 --style chiptune
+
+# tune the AY octave by ear, change grid/tempo
+spectrumizer song.mid --transpose -12 --rows-per-beat 4 --speed 6 \
+    --name "MY THEME" --author "ME"
+
+# dynamics: MIDI velocity drives per-note volume (on by default)
+spectrumizer song.mid -o song.pt3 --no-dynamics      # ...or flat per-channel volume
+
+# generate and immediately hear it (renders through a software AY, then plays)
+spectrumizer song.mid -o song.pt3 --play
+```
+
+Run `spectrumizer --help` for all flags.
+
+## How it works
+
+```
+MIDI ─(inputs/midi.py, mido)→ IR ─(arrange/)→ 3 AY channels ─(pt3/)→ .pt3
+```
+
+- **`spectrumizer/pt3/`** — the proven PT3 emitter (note encoding, channel packer,
+  samples, ornaments, file writer). The byte format is verified against the real
+  player; don't change it blindly.
+- **`spectrumizer/arrange/`** — the hard part:
+  - `quantize` — map time to PT3's row grid (derive `speed` from tempo).
+  - `reduce` — peel the source polyphony into ≤3 monophonic lines (lead / bass /
+    harmony) via a greedy high/low "skyline".
+  - `embellish` — chiptune passes (octave leads, synth drums; chord arps planned).
+  - dynamics — MIDI velocity → per-note AY volume, normalised so the piece's
+    loudest note hits each channel's ceiling (on by default; `--no-dynamics`).
+  - Channel allocation: **A = lead, B = bass, C =** real drums if present, else
+    synth drums (chiptune), else harmony (faithful).
+- **`spectrumizer/ir.py`** — the source-agnostic note model both inputs target.
+
+### PT3 invariants baked in (from the player source)
+
+The player ends a pattern when **channel A** hits its `0x00` terminator and then
+resets all three channels — so every channel of a pattern encodes **exactly**
+`ROWS_PER_PATTERN` (64) rows, and row 0 is never an empty rest (the packer drops
+leading rests). `arrange/model.py` enforces both.
+
+## Listen to it (no Spectrum needed)
+
+spectrumizer ships its own playback path: a small software **AY-3-8910** that
+renders a `.pt3` to a stereo `.wav` (classic ABC panning — A left, B centre,
+C right) and plays it through your system audio player (`afplay` on macOS;
+`ffplay` / `aplay` / `paplay` / `sox` elsewhere).
+
+```bash
+spectrumizer-play song.pt3            # render song.wav and play it
+spectrumizer-play song.pt3 --no-play  # just write the .wav
+spectrumizer-play song.pt3 --seconds 30   # cap length, looping the song's tail
+spectrumizer-play song.pt3 --rate 22050   # faster render (lower fidelity)
+spectrumizer-play song.pt3 --tuning equal # equal-tempered instead of the PT3 table
+spectrumizer-play song.pt3 --stereo mono  # mono (default abc = A-left/B-centre/C-right)
+spectrumizer-play song.pt3 --noise-period 5  # force a noise period (default: the module's real one)
+```
+
+The synth (`spectrumizer/audio.py`) plus the PT3 interpreter
+(`spectrumizer/pt3/player.py`, the inverse of the encoder) only implement the
+subset of PT3 this tool emits — notes, OFF, sample/ornament/volume, NtSkip. Pitch
+uses the **exact PT3 tone table** (the table-1 periods from the real Bulba player,
+so notes land where the chip puts them; pass `--tuning equal` for the old
+equal-tempered approximation). Treat it as a faithful **audition**, not a
+cycle-exact emulation. For the real thing, drop the `.pt3` into the PT3 slot of a
+128K Spectrum build running a Bulba/Vortex replayer, rebuild, and run it in an
+emulator (e.g. ZEsarUX).
+
+## Demos
+
+Hear every mode in your browser on the **[demo page](https://revengator.github.io/spectrumizer/)**
+(GitHub Pages, nothing to install) — or click a clip to play it in GitHub's file
+viewer. All are `examples/ode-to-joy.mid` rendered through the built-in software
+AY; regenerate with `pip install -e ".[demos]" && python examples/make_demos.py`.
+
+| Demo | What it shows |
+|---|---|
+| ▶ [Faithful](docs/audio/faithful.mp3) | 3-voice reduction |
+| ▶ [Chiptune](docs/audio/chiptune.mp3) | octave lead + synth drums |
+| ▶ [No dynamics](docs/audio/chiptune-flat.mp3) | flat volume — vs the velocity dynamics |
+| ▶ [Equal-tempered](docs/audio/chiptune-equal.mp3) | vs the exact PT3 tone table |
+| ▶ [Mono](docs/audio/chiptune-mono.mp3) | vs the default ABC stereo |
+
+## Tests
+
+```bash
+pip install -e ".[dev]"     # installs pytest
+pytest -q
+```
+
+## Status
+
+- **Generate:** MIDI → PT3, faithful + chiptune, with velocity-driven dynamics.
+- **Audition:** built-in software-AY playback to a stereo WAV — exact PT3 tone
+  table, real per-frame noise period, ABC panning (`spectrumizer-play` / `--play`).
+- **Planned:** MusicXML (music21) input, chord arpeggios, AY hardware envelopes
+  (buzzer bass), general PT3 playback (envelope/slides), raw-AY/`.vtx` export.
+
+## Origin
+
+spectrumizer grew out of hand-written, per-track PT3 composer scripts for a ZX
+Spectrum game, generalising them into a single reusable arranger. It is now a
+standalone, game-agnostic tool.
+
+## Credits
+
+- **Sergey Bulba** — the PT3 module format and the Vortex Tracker / PT3 replayer
+  this tool targets, including the NoteTableCreator tone-table data the audition
+  synth uses for exact Spectrum pitches.
+- **Ivan Roshin** — NoteTableCreator, the source of those packed AY tone tables.
+
+These credits acknowledge the format and reference data; spectrumizer's encoder,
+decoder and synth are independent implementations (see [`LICENSE`](LICENSE)).
+
+## Licence
+
+[MIT](LICENSE) © Miguel Ángel Esteve Marco. Note: the MIT licence covers
+**spectrumizer's own code**, not the music you run through it — see
+[`LICENSING.md`](LICENSING.md).

spectrumizer-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectrumizer"
+description = "Generate ZX Spectrum AY (PT3) music from MIDI and other sources."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Miguel Ángel Esteve Marco", email = "esteve@telemaco.es" }]
+keywords = ["zx-spectrum", "ay-3-8910", "pt3", "vortex-tracker", "chiptune", "midi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Sound/Audio :: Conversion",
+    "Topic :: Multimedia :: Sound/Audio :: MIDI",
+]
+dynamic = ["version"]
+dependencies = ["mido>=1.3,<2.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+demos = ["lameenc>=1.5"]      # MP3 encoder for examples/make_demos.py (pip wheel, no system ffmpeg)
+
+[project.scripts]
+spectrumizer = "spectrumizer.cli:main"
+spectrumizer-play = "spectrumizer.play:main"
+
+[project.urls]
+Homepage = "https://github.com/revengator/spectrumizer"
+Repository = "https://github.com/revengator/spectrumizer"
+Issues = "https://github.com/revengator/spectrumizer/issues"
+
+[tool.setuptools]
+packages = [
+    "spectrumizer",
+    "spectrumizer.arrange",
+    "spectrumizer.inputs",
+    "spectrumizer.pt3",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "spectrumizer.__version__" }

spectrumizer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spectrumizer-0.1.0/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-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-0.1.0/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-0.1.0/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