bitcomposer 2.0.0rc2__tar.gz → 2.1.0__tar.gz

{bitcomposer-2.0.0rc2 → bitcomposer-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bitcomposer
-Version: 2.0.0rc2
+Version: 2.1.0
 Summary: Procedural 16-bit chiptune music generator — creates Impulse Tracker (.it) files
 Author-email: CatDogBark <catdogbark@pm.me>
 License-Expression: MIT
@@ -36,29 +36,31 @@ Dynamic: license-file
 [![Release](https://img.shields.io/github/v/release/CatDogBark/bitComposer)](https://github.com/CatDogBark/bitComposer/releases/latest)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-Procedural 16-bit game music. A player that composes the next song as the
-current one ends, with a live mixer, on Linux and Windows; a command line
-and a generator library underneath, pure Python with no dependencies,
+16-bit game music, written while you listen. A player that writes the next
+song as the current one ends, with a live mixer, on Linux and Windows; a
+command line and a library underneath, pure Python with no dependencies,
 writing Impulse Tracker `.it` modules any tracker player reads.
 
-Every run composes a new song: a motif-based melody with call-and-response
-phrasing, voice-led harmony, bass, arpeggio and drums, arranged into a form
-(verse–chorus, AABA, rondo, through-composed) with a drawn intro, an energy
-curve and a real ending, titled after what it drew, between 1:15 and 3:30
-long. Seven sounds, picked with `--sound`:
+Since 2.0 every song is written the way game soundtracks are put together:
+drawn whole from a vocabulary of counted habits (how the band is balanced,
+how its figures repeat and vary, where the tune comes back), taken from
+the readings of a soundtrack's songs. The vocabulary that ships was
+learned from Final Fantasy VI's 68 songs, as statistics with none of the
+game's notes or samples. The songs play on bitComposer's own sound set,
+generic instruments synthesised here, on one of Classic's four styled
+sets, or on a game's own samples. More under [What GENERATE
+writes](#what-generate-writes).
 
-- **snes** — sampled-style voices built the way the SNES made sound, through a BRR codec model and the SNES echo.
-- **ffvi**, **mana**, **evermore**, **megamanx** — style packs: an instrument set rebuilt from each game's own sound chip (every sample profiled, nothing copied) plus the arrangement habits of its score. Details under [Sounds](#sounds).
-- **genesis** — FM bells, brass, organ and bass.
-- **chip** — square, pulse and triangle waves. Closest to NES and Game Boy.
+Your own games too: the player's LIBRARY screen reads a game's SPC files
+into a pack of its samples and, with 40 songs or more, a vocabulary of its
+own to write from ([Packs from your games](#packs-from-your-games)).
 
-And packs of your own: the player's LIBRARY screen makes one from a game's
-own SPC files, the game's samples as its voices ([Packs from your
-games](#packs-from-your-games)).
+The 1.x generator stays as [Classic](#classic), with its own knobs and
+eight sounds, the chip and Genesis palettes among them.
 
-**[Listen in your browser](https://catdogbark.github.io/bitComposer/)** — the actual modules, played live by libopenmpt in WebAssembly: one song per sound, straight from the generator, regenerated with each release.
+**[Listen in your browser](https://catdogbark.github.io/bitComposer/)** — the actual modules, played live by libopenmpt in WebAssembly: five songs from the writer, seeds 1 to 5, and one each from six of Classic's sounds.
 
-**Reproducible, not frozen.** The same seed on the same version gives the same song, byte for byte. A new version may change what a seed draws, and the song message records the version that wrote the file.
+**Reproducible, not frozen.** The same seed on the same version gives the same song, byte for byte. A new version may change what a seed draws; a Classic song's message records the version that wrote it.
 
 ## Install
 
@@ -119,164 +121,90 @@ anything built on libopenmpt.
 Python 3.10 or newer. The generator has no dependencies; the player's
 window is Qt (PySide6, installed with the package).
 
-## Sounds
-
-A style pack pairs an instrument set with the arrangement habits of the score it imitates. Each is built from the game's SPC snapshots: every sample decoded and profiled, matched to the community's instrument tables where they exist, and re-synthesised; nothing from the games is in the repository.
-
-- `ffvi`: every voice modelled on the game's own sample bank and named by its instrument table: the chorused string section, flutes in chords, the dark synth lead of Locke and the Returners, trumpet, trombone, oboe, Terra's and Cyan's pan flutes, cello, choir, pipe organ and rock organ, the Aria's soprano, the Battle theme's distortion guitar, piano, harp, picked string, acoustic guitar, tubular bell, xylophone, a bass guitar and a kit of its own (kick, snare, hats, cymbal, timpani, wood block), with ostinato strings, a brass counter-line in the chorus, timpani rolls into sections and the game's short, wet echo. 
-- `mana`: every voice modelled on the game's own sample bank: a soft slow-breathed flute, bright chorused strings, an 'ah' choir, a high whistle, soft and synth brass, marimba, vibraphone, electric piano, tubular bell, reed, accordion, glass and sine pads, fingered, electric and slap basses and a kit of its own (kick, snare, hats, crash, tom, castanet), with major and pentatonic keys, syncopated harmony, bouncy arps, light swing, the kick and snare set back and the game's one-row echo. 
-- `evermore`: every voice modelled on the game's own sample bank: a slow bright string swell, a warm pad, a dark pad, a glass bell, a breathy flute, a reed, an "oo" choir, harp, tinker music box, piano, pluck and kalimba, a textured drone and a wind loop, a bass, and a quiet kit (soft kick, frame drum, brushes, hat, cymbal, wood ping), with slow tempos, sustained harmony, a drone bass, sparse or no drums, long linear forms and the game's sparing 80 ms echo. 
-- `megamanx`: every voice modelled on the game's own sample bank and named by it: a driven, chorused lead guitar, a chugging rhythm guitar on power chords, the overdrive guitar for arps and counter-lines, synth brass, strings, a guitar swell pad, a saw pad, organ, the boomer synth lead, square and bright leads, a hollow wave, a bell synth, an acoustic pluck, the orchestra hit for stabs, slap and synth basses on a riff, and a tight kit, at fast tempos in minor keys with the game's 48 ms slapback echo.
-
-`--sound` picks a palette or a pack in one word; left to chance, the four packs together weigh as much as plain snes.
-
-- **snes** — sampled-style voices rendered the way the SNES actually made sound: strings, brass, a formant choir, flute, organ, e-piano, bells, plucks and a gated drum kit at 16 kHz with loop points, passed through a BRR codec model for the grain, with the lead, harmony and arp through an echo modelled on the SNES unit's result: fading, darkening repeats on a beat fraction, drawn per song.
-- **genesis** — FM bells, brass, organ and bass.
-- **chip** — square, pulse and triangle waves.
-
-## What you can steer
-
-Everything defaults to `random`.
-
-```
---sound   chip|snes|genesis|ffvi|mana|evermore|megamanx  the sound in one word: a palette or a style pack (overrides the two below)
---style   chip|snes|genesis          sound palette
---pack    ffvi|mana|evermore|megamanx|none|random  style pack: an instrument set with the habits of the scores it imitates (a pack implies snes)
---pack-file PACK.json               a pack as data, with its own voices as WAV files (docs/PACKS.md); overrides --pack and --sound
---echo    on|off|random              echo (random: 70% of snes songs, never chip or genesis)
---echo-wet    light|normal|wet|random  how much of the lead, harmony and arp the echo carries
---echo-delay  eighth|dotted|quarter|slap|row|random  beat fraction between repeats, a 48 ms slap, or one row (random: weighted by tempo)
---echo-stereo bounce|centre|random     repeats alternate sides, or sit under their source
---keys    moving|home                moving: choruses/bridges may change key; home: stay put
---tempo   slow|medium|fast           80–110 / 110–140 / 140–180 BPM
---energy  chill|normal|intense       density and arrangement weight
---scale   minor|major|pentatonic
---form    standard|aaba|rondo|short|linear
---drum-density sparse|normal|busy    --no-fills    --swing off|light|heavy
---melody  simple|phrased             phrased = motif-based, has a hook
---harmony-voicing thin|full          two real voices, or three
---harmony-mode stabs|sustain|rhythmic
---bass-weight heavy|medium|light
---lead-shift SEMITONES               move the lead's window (negative lowers it); default: the sound's own
---name    title|timestamp            file naming; --prefix / --suffix add a marker ("(auto) " is the player's)
--s SEED   -n COUNT   -o FILE   -d DIR   -v
-```
-
-Some starting points:
-
-```bash
-# Overworld — bright, sampled palette with echo
-bitcomposer -d out --style snes --scale major --tempo medium --form standard
-
-# FM boss fight
-bitcomposer -d out --style genesis --tempo fast --energy intense --scale minor --drum-density busy --form short
-
-# Game Boy flavour — square waves, thin harmony, no echo
-bitcomposer -d out --style chip --echo off --harmony-voicing thin --bass-weight light --form short
-
-# Credits roll
-bitcomposer -d out --style snes --tempo slow --energy chill --scale major --drum-density sparse --no-fills --form linear
-```
-
-## How it works
-
-1. Pick a key and a scale weighted toward game music (minor pentatonic, dorian, harmonic minor, mixolydian…), then a progression for it. The tables include borrowed chords and secondary dominants — ♭VII, ♭VI, V/V — not just the diatonic set.
-2. Choose a form and its energy curve; decide which sections repeat. Repeated sections draw the same music from the same seed, so the hook comes back.
-3. Generate a motif (rhythm template plus contour) and vary it per bar in statement/answer pairs. Fourteen rhythm templates, six of them with 16th-note pushes and pickups.
-4. Each four-bar pattern holds a chord timeline; about half the time the back two bars move to a related chord. Melody resolves onto chord tones at each change. Harmony is two or three real voices placed near fixed anchors, so it steps rather than leaps and keeps the chord's third; the anchors are set per voice family (pads low and wide, brass and guitars mid and close), the top voice stays under the lead's line, and a stab holds for as long as the voice needs to speak. Bass and arp follow and rest with the section's energy.
-5. Drums come from one-bar templates by section and density, with fills, retriggered snare rolls and tick-level swing.
-6. Instruments are synthesized per song from the chosen palette and written as samples. SNES voices get attack-then-loop sustain and the BRR treatment.
-7. The echo: held lead notes and phrase endings come back as three fading, darkening repeats, the harmony and arp as lighter ones, each on return channels of their own, drums and bass dry. Everything is written as a 19-channel `.it` with the title and a song message (key, BPM, palette, form, seed, and a `layout:` line naming every channel's role) that trackers display.
-
-Each song gets a title that reads the song: its scale, sound, energy and
-tempo lean the words, so a slow minor Evermore piece and a fast Mega Man X
-track are named differently (*Lunar Snow*, *Lighthouse of Steel*, *The
-Power Plant of Sparks*).
-
-## Measuring instead of guessing
-
-`tools/analyze.py` parses `.it` files back from disk (stdlib only, independent
-of the generator) and scores a batch on the things that correlate with
-"sounds like a song": section reuse, motif repetition, rhythmic grid, chord
-voicing variety, voice motion, effect vocabulary, drum density.
-
-```bash
-python3 tools/analyze.py 'out/*.it'          # metric table
-python3 tools/analyze.py --grid out/song.it  # tracker-style pattern dump
-```
-
-[docs/ANALYSIS.md](docs/ANALYSIS.md) is the story of this project: the
-output was once limited by three silent arrangement bugs that nine commits
-of ear-checking never caught, and every improvement since has been measured
-before and after. Read it before changing the generator.
-
-Tests:
-
-```bash
-python3 -m unittest discover -s tests -v
-```
-
 ## What GENERATE writes
 
 ```bash
 bitcomposer -s 7 -v
 ```
 
-writes a whole song the way the idiom's writer does (`docs/IDIOM.md`): a
+writes a whole song the way the idiom's writer does ([docs/IDIOM.md](docs/IDIOM.md)): a
 plan for the band, each part's figures bar by bar, a tune with a theme that
 may come back, and the parts' balance, all drawn from a vocabulary of
 counted habits, played on bitComposer's own sound set (generic
 instruments, synthesised here from descriptions and modelled on no game's
 bank, each fitted to its part by register and speed; `--pack ffvi`,
 `mana`, `evermore` or `megamanx` borrows one of Classic's styled sets
-instead) and rendered through the SNES back end. A seed names one song on
+instead) and rendered through the SNES back end, under the player's
+performance (`bitcomposer/performance.py`): the theme comes back with the
+band, the loop plays twice, the echo and the vibrato on held notes of the tune
+are the vocabulary's own words (FFVI's 0.20 echo at 80 ms, its vibrato on a
+fifth of the tune's held notes). `--bare` writes without
+it, the way the Song Checks do; `--no-carry-theme` and `--no-band-returns`
+turn the two switches off. A seed names one song on
 every machine. `--carry-theme` draws the tune's phrases again until its
 theme comes back; `--band-returns` brings the chords, the bass or the
-accompaniment back with it. In the player this is GENERATE, with THEME
-and RETURNS beside it; Classic, the 1.x generator with its own knobs and
-the chip and Genesis sounds, is WRITER: classic in SET (`--classic` on the
-command line; the options above the flag are its).
+accompaniment back with it. In the player this is GENERATE on PLAY,
+and WRITE AND PLAY on WRITE, where the two switches and a seed field sit;
+[Classic](#classic), the 1.x generator, is WRITER: CLASSIC (1.X) there
+(`--classic` on the command line).
 
 Where the vocabulary comes from, plainly: the shipped one
-(`bitcomposer/vocabularies/default.json.gz`, 365 KB) was fitted on the
-readings of Final Fantasy VI's 67 songs, the game the writing was
+(`bitcomposer/vocabularies/default.json.gz`, 625 KB) was fitted on the
+readings of Final Fantasy VI's 68 songs, the game the writing was
 measured against round by round until it held up by ear
-(`docs/idiom/phase-4-writing.md`). It is the statistics of how that
+([docs/idiom/phase-4-writing.md](docs/idiom/phase-4-writing.md)). It is the statistics of how that
 music is put together, the counts of figures, moves, chord changes and
 balances, and none of the game's samples or notes; a release check
 (`tools/copycheck.py`) probes every four-bar window of hundreds of
 written tunes against the games' phrases and ships nothing that copies
-one. It is as far as the writing has gone; vocabularies fitted on more
-games follow. Importing a game (below) fits that game's own vocabulary
-beside its samples and recounts one over everything you have imported;
-SET's FROM row offers each once 40 songs stand behind it
-(`--vocabulary pack:NAME`, `--vocabulary library`).
+one. Each written song takes its skeleton from one of those songs, drawn,
+as measured from its reading: its form and bar counts where they fit, its
+tempo within a tenth, which parts play in each section, their levels and
+how busy each line is. None of that song's notes come with it: the notes
+are drawn from the counts over all of them. It is as far as the writing
+has gone; vocabularies fitted on more games follow. Importing a game
+(below) fits that game's own vocabulary beside its samples and recounts
+one over everything you have imported; WRITE offers each under WRITTEN
+FROM once 40 songs stand behind it (`--vocabulary pack:NAME`,
+`--vocabulary library`).
+
+Every word in the vocabulary, what it counts and why it exists, is in
+[the vocabulary](docs/idiom/VOCABULARY.md), and [the vocabulary's
+map](docs/idiom/vocabulary-map.md) draws, stage by stage, which words
+condition which.
 
 ## Packs from your games
 
-New in 1.2, and early. The player's LIBRARY screen makes a pack from a game's
-own music. IMPORT a game's SPC set (a folder of `.spc` files, a zip, or
+The player's LIBRARY screen makes a pack from a game's own
+music. IMPORT a game's SPC set (a folder of `.spc` files, a zip, or
 snesmusic.org's `.rsn`, a `.rar` or a `.7z`, which 7-Zip or unar on your
 machine unpacks) and each song is run through an emulator of the SNES sound
 hardware, read as music (the beat and bar, which voice is the melody, the
 bass, the chords and the drums, the form) and the soundtrack made into a
 pack: the samples the game plays each part with most, as its voices, a kit
 of its drums, and the habits the readings give straight (tempo, major or
-minor, how often a song has no drums, the echo). OPEN a pack to hear each
-voice in its part, see why it was put there (in how many songs, how many
-notes) and move it; USE puts it in SOUND; EXPORT writes it as one zip, and
-ADD brings an exported pack, or a pack file, back. Importing a game again
-starts its pack fresh.
-
-A pack carries the game's sound; how a song is arranged is still
-bitComposer's own, measured against the game's songs. The next stages
-teach the generator to write the way the readings show the composers did
-(`docs/TRANSLATOR.md`).
+minor, how often a song has no drums, the echo). SOUNDS shows each voice in
+its part, to hear it, see why it was put there (in how many songs, how
+many notes) and move it; USE ITS SOUNDS plays the next songs on them;
+EXPORT writes the pack as one zip, and ADD A PACK brings an exported pack,
+or a pack file, back. Importing a game again
+starts its pack fresh. A game imported under an earlier version is
+written the new way only once it is imported again: the newer reader
+reads its songs again, and its vocabulary is counted with the words an
+older import lacks.
+
+An import also counts the game's own tables into its pack. With 40 songs
+or more behind it the game has a vocabulary of its own: WRITE FROM IT in
+LIBRARY, or its card under WRITE's WRITTEN FROM, writes the next songs the
+way that game's are put together, and a library vocabulary recounted over
+everything you have imported sits beside them (`--vocabulary pack:NAME`,
+`--vocabulary library`). Under 40 songs a fitted vocabulary's drums are
+not yet the game's, so none is offered.
 
 The emulator, `bitcomposer-emu`, is a compiled package of its own with a
 wheel for Linux (x86_64 and aarch64), Windows and macOS, so no toolchain
 is needed. The Windows build carries it. On Linux,
-`pipx install "bitcomposer[import]"` installs both, or the panel's GET THE
+`pipx install "bitcomposer[import]"` installs both, or LIBRARY's GET THE
 EMULATOR adds it to a player already installed, and UPDATE keeps both
 current (`pip install "bitcomposer[import]"` elsewhere). Where no wheel
 matches, it builds from source (Rust; CONTRIBUTING.md has how).
@@ -301,10 +229,21 @@ them stay on your machine, in your data folder
 `bitcomposer-player` (Linux) and `bitComposer.exe` (Windows) are the same
 program, an application of four screens under one header:
 
-- **PLAY**: the song playing, its position, the transport, GENERATE, AUTO
-  (the "radio": the next song is written when this one ends), gain with a
-  soft limiter, each channel's level as the band, and the songs in the
-  folder with KEEP. Every song the player writes is provisional
+- **PLAY**: one panel for the song playing (its title with its key, tempo
+  and form, MORE for the rest of what its file says), its position, the
+  transport, GENERATE and AUTO
+  (the "radio": the next song is written when this one ends); gain with a
+  soft limiter, WIDTH (the stereo width heard: SPEAKERS plays each voice
+  where its song puts it, HEADPHONES pulls the pans toward centre), each
+  channel's level as the band, with an M and an S on every part (M mutes
+  it, S plays it alone, or with the other parts whose S is lit; a part's
+  echo goes with it; for the song playing only, never written into the
+  file), and the songs in the
+  folder with KEEP. GAIN & WIDTH and the band fold to their headings on a
+  click, and the song list takes whatever height the window has left, so
+  the songs scroll and the screen over them stays put. Every song plays at one level: the player measures a
+  song once and trims it as it plays, so a quiet song and a loud one sit
+  side by side (SET → LEVEL turns it off; the files are not changed). Every song the player writes is provisional
   (`(auto) <Title>.it`, so a file browser sorts them together) and pruned
   after ten unless kept.
 - **WRITE**: what the next song is written from (the vocabulary that
@@ -314,15 +253,16 @@ program, an application of four screens under one header:
   switch at the bottom, with its own knobs (sound, tempo, energy, scale,
   form, echo, bass, drums, harmony) and presets.
 - **LIBRARY**: the games you have read. IMPORT reads a game's SPC set
-  into its sounds and, at 40 songs, its own vocabulary; ADD brings in an
-  exported pack; each game can lend its sounds, be written from,
+  into its sounds and, at 40 songs, its own vocabulary; ADD A PACK brings
+  in an exported pack; each game can lend its sounds, be written from,
   be exported, renamed or deleted.
 - **SOUNDS**: a game's samples by part, each heard with a click and moved
   when the reading got it wrong.
 
 MIX (a live mixer per channel, with the kit and the echo as buses, and
-APPLY to write the mix into the file) and SET (start at login, update
-checks, release candidates) open as panels over the screen. The look is
+APPLY to write the mix into the file) and SET (one level for every song,
+start at login, update checks, release candidates) open as panels over
+the screen. The look is
 the SNES era's own pixels, as styling only: the controls are ordinary
 controls, the text is text, nothing sits on a fixed grid. The window
 opens no taller than the screen it lands on (scrolling on a small or
@@ -341,9 +281,127 @@ the release's installer and runs it. A player installed from a release
 candidate is offered the next candidate; a release player only releases,
 unless SET → CANDIDATES asks for candidates too.
 
+## Classic
+
+Classic is the 1.x generator, kept whole in 2.0: WRITER: CLASSIC (1.X) on
+the player's WRITE screen, `--classic` on the command line. It has no
+vocabulary. Every run composes a new song from rules and tables of its
+own: a motif-based melody with call-and-response phrasing, voice-led
+harmony, bass, arpeggio and drums, arranged into a form (verse–chorus,
+AABA, rondo, through-composed) with a drawn intro, an energy curve and a
+real ending, titled after what it drew, between 1:15 and 3:30 long. Eight
+sounds, picked with `--sound`:
+
+- **snes** — sampled-style voices built the way the SNES made sound, through a BRR codec model and the SNES echo.
+- **bit** — bitComposer's own sound set, the one the writer plays on by default: generic instruments synthesised here from descriptions, modelled on no game's bank.
+- **ffvi**, **mana**, **evermore**, **megamanx** — style packs: an instrument set rebuilt from each game's own sound chip (every sample profiled, nothing copied) plus the arrangement habits of its score. Details under [Sounds](#sounds).
+- **genesis** — FM bells, brass, organ and bass.
+- **chip** — square, pulse and triangle waves. Closest to NES and Game Boy.
+
+### Sounds
+
+A style pack pairs an instrument set with the arrangement habits of the score it imitates. Each is built from the game's SPC snapshots: every sample decoded and profiled, matched to the community's instrument tables where they exist, and re-synthesised; nothing from the games is in the repository.
+
+- `ffvi`: every voice modelled on the game's own sample bank and named by its instrument table: the chorused string section, flutes in chords, the dark synth lead of Locke and the Returners, trumpet, trombone, oboe, Terra's and Cyan's pan flutes, cello, choir, pipe organ and rock organ, the Aria's soprano, the Battle theme's distortion guitar, piano, harp, picked string, acoustic guitar, tubular bell, xylophone, a bass guitar and a kit of its own (kick, snare, hats, cymbal, timpani, wood block), with ostinato strings, a brass counter-line in the chorus, timpani rolls into sections and the game's short, wet echo. 
+- `mana`: every voice modelled on the game's own sample bank: a soft slow-breathed flute, bright chorused strings, an 'ah' choir, a high whistle, soft and synth brass, marimba, vibraphone, electric piano, tubular bell, reed, accordion, glass and sine pads, fingered, electric and slap basses and a kit of its own (kick, snare, hats, crash, tom, castanet), with major and pentatonic keys, syncopated harmony, bouncy arps, light swing, the kick and snare set back and the game's one-row echo. 
+- `evermore`: every voice modelled on the game's own sample bank: a slow bright string swell, a warm pad, a dark pad, a glass bell, a breathy flute, a reed, an "oo" choir, harp, tinker music box, piano, pluck and kalimba, a textured drone and a wind loop, a bass, and a quiet kit (soft kick, frame drum, brushes, hat, cymbal, wood ping), with slow tempos, sustained harmony, a drone bass, sparse or no drums, long linear forms and the game's sparing 80 ms echo. 
+- `megamanx`: every voice modelled on the game's own sample bank and named by it: a driven, chorused lead guitar, a chugging rhythm guitar on power chords, the overdrive guitar for arps and counter-lines, synth brass, strings, a guitar swell pad, a saw pad, organ, the boomer synth lead, square and bright leads, a hollow wave, a bell synth, an acoustic pluck, the orchestra hit for stabs, slap and synth basses on a riff, and a tight kit, at fast tempos in minor keys with the game's 48 ms slapback echo.
+
+`--sound` picks a palette or a pack in one word; left to chance, the four style packs together weigh as much as plain snes, and bit as much as one of them.
+
+- **snes** — sampled-style voices rendered the way the SNES actually made sound: strings, brass, a formant choir, flute, organ, e-piano, bells, plucks and a gated drum kit at 16 kHz with loop points, passed through a BRR codec model for the grain, with the lead, harmony and arp through an echo modelled on the SNES unit's result: fading, darkening repeats on a beat fraction, drawn per song.
+- **genesis** — FM bells, brass, organ and bass.
+- **chip** — square, pulse and triangle waves.
+
+### What you can steer
+
+With `--classic`, everything defaults to `random` but `--keys` (moving) and `--lead-shift` (the sound's own). Without it, of these a written song reads only `--pack`, `--pack-file`, `--echo off`, `--name`, `--prefix`, `--suffix` and the last line.
+
+```
+--sound   chip|snes|genesis|bit|ffvi|mana|evermore|megamanx  the sound in one word: a palette or a style pack (overrides the two below)
+--style   chip|snes|genesis          sound palette
+--pack    bit|ffvi|mana|evermore|megamanx|none|random  style pack: an instrument set with the habits of the scores it imitates (a pack implies snes)
+--pack-file PACK.json               a pack as data, with its own voices as WAV files (docs/PACKS.md); overrides --pack and --sound
+--echo    on|off|random              echo (random: 70% of snes songs, never chip or genesis)
+--echo-wet    light|normal|wet|random  how much of the lead, harmony and arp the echo carries
+--echo-delay  eighth|dotted|quarter|slap|row|random  beat fraction between repeats, a 48 ms slap, or one row (random: weighted by tempo)
+--echo-stereo bounce|centre|random     repeats alternate sides, or sit under their source
+--keys    moving|home                moving: choruses/bridges may change key; home: stay put
+--tempo   slow|medium|fast           80–110 / 110–140 / 140–180 BPM
+--energy  chill|normal|intense       density and arrangement weight
+--scale   minor|major|pentatonic
+--form    standard|aaba|rondo|short|linear
+--drum-density sparse|normal|busy    --no-fills    --swing off|light|heavy
+--melody  simple|phrased             phrased = motif-based, has a hook
+--harmony-voicing thin|full          two real voices, or three
+--harmony-mode stabs|sustain|rhythmic
+--bass-weight heavy|medium|light
+--lead-shift SEMITONES               move the lead's window (negative lowers it); default: the sound's own
+--name    title|timestamp            file naming; --prefix / --suffix add a marker ("(auto) " is the player's)
+-s SEED   -n COUNT   -o FILE   -d DIR   -v
+```
+
+Some starting points:
+
+```bash
+# Overworld — bright, sampled palette with echo
+bitcomposer --classic -d out --style snes --scale major --tempo medium --form standard
+
+# FM boss fight
+bitcomposer --classic -d out --style genesis --tempo fast --energy intense --scale minor --drum-density busy --form short
+
+# Game Boy flavour — square waves, thin harmony, no echo
+bitcomposer --classic -d out --style chip --echo off --harmony-voicing thin --bass-weight light --form short
+
+# Credits roll
+bitcomposer --classic -d out --style snes --tempo slow --energy chill --scale major --drum-density sparse --no-fills --form linear
+```
+
+### How it works
+
+1. Pick a key and a scale weighted toward game music (minor pentatonic, dorian, harmonic minor, mixolydian…), then a progression for it. The tables include borrowed chords and secondary dominants — ♭VII, ♭VI, V/V — not just the diatonic set.
+2. Choose a form and its energy curve; decide which sections repeat. Repeated sections draw the same music from the same seed, so the hook comes back.
+3. Generate a motif (rhythm template plus contour) and vary it per bar in statement/answer pairs. Fourteen rhythm templates, six of them with 16th-note pushes and pickups.
+4. Each four-bar pattern holds a chord timeline; about half the time the back two bars move to a related chord. Melody resolves onto chord tones at each change. Harmony is two or three real voices placed near fixed anchors, so it steps rather than leaps and keeps the chord's third; the anchors are set per voice family (pads low and wide, brass and guitars mid and close), the top voice stays under the lead's line, and a stab holds for as long as the voice needs to speak. Bass and arp follow and rest with the section's energy.
+5. Drums come from one-bar templates by section and density, with fills, retriggered snare rolls and tick-level swing.
+6. Instruments are synthesized per song from the chosen palette and written as samples. SNES voices get attack-then-loop sustain and the BRR treatment.
+7. The echo: held lead notes and phrase endings come back as three fading, darkening repeats, the harmony and arp as lighter ones, each on return channels of their own, drums and bass dry. Everything is written as a 19-channel `.it` with the title and a song message (key, BPM, palette, form, seed, and a `layout:` line naming every channel's role) that trackers display.
+
+Each song gets a title that reads the song: its scale, sound, energy and
+tempo lean the words, so a slow minor Evermore piece and a fast Mega Man X
+track are named differently (*Lunar Snow*, *Lighthouse of Steel*, *The
+Power Plant of Sparks*).
+
+## Measuring instead of guessing
+
+`tools/analyze.py` parses `.it` files back from disk (stdlib only, independent
+of the generator) and scores a batch on the things that correlate with
+"sounds like a song": section reuse, motif repetition, rhythmic grid, chord
+voicing variety, voice motion, effect vocabulary, drum density.
+
+```bash
+python3 tools/analyze.py 'out/*.it'          # metric table
+python3 tools/analyze.py --grid out/song.it  # tracker-style pattern dump
+```
+
+[docs/ANALYSIS.md](docs/ANALYSIS.md) is the story of this project: the
+output was once limited by three silent arrangement bugs that nine commits
+of ear-checking never caught, and every improvement since has been measured
+before and after. Read it before changing Classic. The writer has its own
+record: [docs/IDIOM.md](docs/IDIOM.md) for the plan, and [docs/idiom/phase-4-writing.md](docs/idiom/phase-4-writing.md)
+for its rounds, each measured against Final Fantasy VI's own songs and
+most passed by ear. What the written songs do that can sound odd, and why it
+stands, is in [docs/LIMITS.md](docs/LIMITS.md).
+
+Tests:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
 ## Windows
 
-Every release carries `bitComposer-setup.exe` (the installer) and `bitComposer-windows.zip` (the same `bitComposer` folder, no install), built by GitHub Actions on every push to main and attached on the tag: `bitComposer.exe`, the player, with Qt, libopenmpt and the SNES emulator (for importing a game's music) beside it; and `bitcomposer-cli.exe`, the command line. The installer installs for your user by default (no administrator prompt; all users is an option on its first page), and the player's UPDATE button runs the next one quietly and reopens the player. Each build also renders the player offscreen at common screen sizes and scalings (1366×768, 1920×1080 at 100% and 150%, 2560×1440 at 125%, 4K at 200%), kept as the workflow's `player-screenshots-windows` artifact. Songs are `.it` files; [OpenMPT](https://openmpt.org) and XMPlay play them too. Windows releases are to be code-signed through the SignPath Foundation's programme for open-source projects (see [Code signing policy](#code-signing-policy)); until that is in place they are unsigned, so SmartScreen asks once ("More info", "Run anyway"). With Python installed instead, `pipx install bitcomposer` gives the same programs as `bitcomposer-player` and `bitcomposer`.
+Every release carries `bitComposer-setup.exe` (the installer) and `bitComposer-windows.zip` (the same `bitComposer` folder, no install), built by GitHub Actions on every pull request into main and attached on the tag: `bitComposer.exe`, the player, with Qt, libopenmpt and the SNES emulator (for importing a game's music) beside it; and `bitcomposer-cli.exe`, the command line. The installer installs for your user by default (no administrator prompt; all users is an option on its first page), and the player's UPDATE button runs the next one quietly and reopens the player. Each build also renders the player offscreen at common screen sizes and scalings (1366×768, 1920×1080 at 100% and 150%, 2560×1440 at 125%, 4K at 200%), kept as the workflow's `player-screenshots-windows` artifact. Songs are `.it` files; [OpenMPT](https://openmpt.org) and XMPlay play them too. Windows releases are to be code-signed through the SignPath Foundation's programme for open-source projects (see [Code signing policy](#code-signing-policy)); until that is in place they are unsigned, so SmartScreen asks once ("More info", "Run anyway"). Smart App Control, where Windows 11 has it on, blocks unsigned programs outright with no such choice; bitComposer runs only with it off (Windows Security, App & browser control). With Python installed instead, `pipx install bitcomposer` gives the same programs as `bitcomposer-player` and `bitcomposer`.
 
 ## Code signing policy
 
@@ -364,7 +422,7 @@ bitComposer composes and plays music on your computer. It collects nothing about
 
 One thing goes over the network on its own: when the player starts, it asks GitHub's public releases list (`api.github.com`) whether a newer version exists, so it can offer the UPDATE button. That request carries only what any web request does (your IP address and the program's name), and [GitHub's privacy statement](https://docs.github.com/site-policy/privacy-policies/github-general-privacy-statement) covers it. Turn it off in the player under SET → PLAYER → UPDATES. Updating itself downloads only when you press UPDATE: the installer from GitHub on Windows, the package from PyPI with pipx. GET THE EMULATOR downloads the emulator from PyPI the same way, and only when you press it. Importing a game's music reads your files on your machine and sends nothing.
 
-The [listening page](https://catdogbark.github.io/bitComposer/) is a website: GitHub Pages serves it and Google Fonts serves its font, each under its own privacy policy. It plays the songs in your browser and keeps nothing.
+The [listening page](https://catdogbark.github.io/bitComposer/) is a website: GitHub Pages serves it and Google Fonts serves its fonts, each under its own privacy policy. It plays the songs in your browser and keeps nothing.
 
 ## License and contact