bitcomposer 1.0.0rc1__tar.gz

bitcomposer-1.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatDogBark
+
+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.

bitcomposer-1.0.0rc1/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: bitcomposer
+Version: 1.0.0rc1
+Summary: Procedural 16-bit chiptune music generator — creates Impulse Tracker (.it) files
+Author-email: CatDogBark <186357707+CatDogBark@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/CatDogBark/bitComposer
+Project-URL: Repository, https://github.com/CatDogBark/bitComposer
+Project-URL: Issues, https://github.com/CatDogBark/bitComposer/issues
+Project-URL: Changelog, https://github.com/CatDogBark/bitComposer/blob/main/CHANGELOG.md
+Keywords: chiptune,tracker,music,procedural,16-bit,snes,genesis,impulse-tracker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bitComposer
+
+[![CI](https://github.com/CatDogBark/bitComposer/actions/workflows/ci.yml/badge.svg)](https://github.com/CatDogBark/bitComposer/actions/workflows/ci.yml)
+[![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. Pure Python, no dependencies, writes Impulse
+Tracker `.it` modules you can play in any tracker player, and a KDE Plasma
+player that generates while you listen.
+
+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`:
+
+- **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.
+
+**[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.
+
+**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.
+
+## Install
+
+From PyPI, with [pipx](https://pipx.pypa.io/) so it lands on your PATH
+without touching the system Python (Debian and Fedora refuse a plain
+`pip install` there):
+
+```bash
+pipx install bitcomposer
+bitcomposer -d out            # writes out/<Title>.it
+bitcomposer -d out -s 42 -v   # reproducible, with details
+```
+
+On Windows, the release zip needs no Python at all; see [Windows](#windows).
+From a clone, for development:
+
+```bash
+git clone https://github.com/CatDogBark/bitComposer.git
+cd bitComposer
+python3 -m bitcomposer -d out
+```
+
+Play the result with [OpenMPT](https://openmpt.org/) (Windows),
+[Schism Tracker](https://schismtracker.org/), VLC, Audacious, `xmp`, or
+anything built on libopenmpt.
+
+Python 3.10 or newer, no dependencies. The window (`bitcomposer-gui`) uses
+tkinter, which Debian and Ubuntu ship separately as `python3-tk`.
+
+## 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)
+--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
+--name    title|timestamp            file naming; --suffix adds a marker
+-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 seed-derived two-word title that leans with its scale:
+*Haunted Orchard*, *Neon Causeway*, *Rusted Foundry*.
+
+## 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
+```
+
+## Windows
+
+Every release carries `bitComposer-windows.zip` with two executables built by GitHub Actions on every push and attached on the tag: `bitComposer.exe`, a small window (sound, echo, energy, tempo, how many, save folder, Generate), and `bitcomposer-cli.exe`, the command line. Songs are `.it` files; [OpenMPT](https://openmpt.org) plays them and will play a whole folder as a playlist. The executables are not code-signed, so SmartScreen asks once. With Python installed instead, `pipx install bitcomposer` gives the same two commands as `bitcomposer` and `bitcomposer-gui`. A Windows player with the Plasma widget's features is a 1.x item (see the roadmap).
+
+## Companion player (optional, Linux + KDE Plasma 6)
+
+<img src="docs/images/widget.png" alt="The Plasma widget: now playing, transport, gain, generate and settings, playlist" width="420">
+
+`companion/` holds a desktop player stack: a libopenmpt D-Bus daemon with
+MPRIS2, a Plasma 6 panel widget with transport, gain, generator settings,
+presets and a per-channel mixer, and an auto-generate "radio" mode that
+composes the next track as the current one ends.
+
+```bash
+./companion/install.sh --check   # see what it would do
+./companion/install.sh           # install, enable the daemon
+```
+
+See [docs/INSTALL.md](docs/INSTALL.md). The generator does not depend on
+any of this.
+
+## License
+
+MIT. Every instrument is synthesized; no samples were taken from any game.

bitcomposer-1.0.0rc1/README.md

@@ -0,0 +1,170 @@
+# bitComposer
+
+[![CI](https://github.com/CatDogBark/bitComposer/actions/workflows/ci.yml/badge.svg)](https://github.com/CatDogBark/bitComposer/actions/workflows/ci.yml)
+[![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. Pure Python, no dependencies, writes Impulse
+Tracker `.it` modules you can play in any tracker player, and a KDE Plasma
+player that generates while you listen.
+
+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`:
+
+- **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.
+
+**[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.
+
+**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.
+
+## Install
+
+From PyPI, with [pipx](https://pipx.pypa.io/) so it lands on your PATH
+without touching the system Python (Debian and Fedora refuse a plain
+`pip install` there):
+
+```bash
+pipx install bitcomposer
+bitcomposer -d out            # writes out/<Title>.it
+bitcomposer -d out -s 42 -v   # reproducible, with details
+```
+
+On Windows, the release zip needs no Python at all; see [Windows](#windows).
+From a clone, for development:
+
+```bash
+git clone https://github.com/CatDogBark/bitComposer.git
+cd bitComposer
+python3 -m bitcomposer -d out
+```
+
+Play the result with [OpenMPT](https://openmpt.org/) (Windows),
+[Schism Tracker](https://schismtracker.org/), VLC, Audacious, `xmp`, or
+anything built on libopenmpt.
+
+Python 3.10 or newer, no dependencies. The window (`bitcomposer-gui`) uses
+tkinter, which Debian and Ubuntu ship separately as `python3-tk`.
+
+## 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)
+--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
+--name    title|timestamp            file naming; --suffix adds a marker
+-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 seed-derived two-word title that leans with its scale:
+*Haunted Orchard*, *Neon Causeway*, *Rusted Foundry*.
+
+## 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
+```
+
+## Windows
+
+Every release carries `bitComposer-windows.zip` with two executables built by GitHub Actions on every push and attached on the tag: `bitComposer.exe`, a small window (sound, echo, energy, tempo, how many, save folder, Generate), and `bitcomposer-cli.exe`, the command line. Songs are `.it` files; [OpenMPT](https://openmpt.org) plays them and will play a whole folder as a playlist. The executables are not code-signed, so SmartScreen asks once. With Python installed instead, `pipx install bitcomposer` gives the same two commands as `bitcomposer` and `bitcomposer-gui`. A Windows player with the Plasma widget's features is a 1.x item (see the roadmap).
+
+## Companion player (optional, Linux + KDE Plasma 6)
+
+<img src="docs/images/widget.png" alt="The Plasma widget: now playing, transport, gain, generate and settings, playlist" width="420">
+
+`companion/` holds a desktop player stack: a libopenmpt D-Bus daemon with
+MPRIS2, a Plasma 6 panel widget with transport, gain, generator settings,
+presets and a per-channel mixer, and an auto-generate "radio" mode that
+composes the next track as the current one ends.
+
+```bash
+./companion/install.sh --check   # see what it would do
+./companion/install.sh           # install, enable the daemon
+```
+
+See [docs/INSTALL.md](docs/INSTALL.md). The generator does not depend on
+any of this.
+
+## License
+
+MIT. Every instrument is synthesized; no samples were taken from any game.

bitcomposer-1.0.0rc1/bitcomposer/__init__.py

@@ -0,0 +1,6 @@
+"""bitcomposer — Procedural 16-bit chiptune music generator."""
+
+__version__ = "1.0.0rc1"
+
+# The registry first, then the packs that register their voices into it.
+from . import samples, packs  # noqa: E402,F401

bitcomposer-1.0.0rc1/bitcomposer/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python3 -m bitcomposer` as a synonym for `python3 -m bitcomposer.cli`."""
+
+from .cli import main
+
+main()

bitcomposer-1.0.0rc1/bitcomposer/arp.py

@@ -0,0 +1,192 @@
+"""
+Arpeggio figures.
+
+The arp used to be a direction — up, down, up-down or random — stepping
+through the chord tones every eighth note for the whole song, one setting
+per song, with random velocity jitter. That reads as a sequencer running in
+the background. Game arps are *figures*: short rhythmic shapes with accents
+and rests that recur with the section, climb, and leave room for the lead.
+
+A figure is one bar of (row, degree, accent) steps. `degree` indexes a
+ladder of chord tones that starts on the chord's root in octave 4 and
+climbs through the chord — so 0 is the root, 1 the next chord tone up, and
+for a triad 3 is the root an octave higher. Negative degrees reach below.
+Steps are 16 rows to the bar; a figure can be sparser than that.
+"""
+
+import random
+
+from .pattern import ROWS_PER_BAR
+
+# Accent levels, as a fraction of the section's arp volume.
+S, N, W = 1.0, 0.8, 0.62   # strong, normal, weak
+
+FIGURES = {
+    # name: {"steps": [(row, degree, accent), ...], "energy": (lo, hi), "climb": bool}
+    "sparse_pulse": {
+        "steps": [(0, 0, S), (8, 3, N)],
+        "energy": (0.0, 0.55), "climb": False},
+    "quarter_up": {
+        "steps": [(0, 0, S), (4, 1, W), (8, 2, N), (12, 3, W)],
+        "energy": (0.0, 0.7), "climb": False},
+    "classic_up": {
+        "steps": [(0, 0, S), (2, 1, W), (4, 2, N), (6, 3, W),
+                  (8, 0, S), (10, 1, W), (12, 2, N), (14, 3, W)],
+        "energy": (0.4, 1.0), "climb": True},
+    "up_down": {
+        "steps": [(0, 0, S), (2, 1, W), (4, 2, N), (6, 3, W),
+                  (8, 2, S), (10, 1, W), (12, 0, N), (14, 1, W)],
+        "energy": (0.4, 1.0), "climb": False},
+    "broken_octave": {   # 1-5-8-5, the Mega Man figure
+        "steps": [(0, 0, S), (2, 2, W), (4, 3, N), (6, 2, W),
+                  (8, 0, S), (10, 2, W), (12, 3, N), (14, 2, W)],
+        "energy": (0.5, 1.0), "climb": True},
+    "pedal_bounce": {    # root pedal against the chord above it
+        "steps": [(0, 0, S), (2, 3, W), (4, 0, N), (6, 4, W),
+                  (8, 0, S), (10, 3, W), (12, 0, N), (14, 5, W)],
+        "energy": (0.5, 1.0), "climb": False},
+    "sync_push": {       # dotted-eighth push
+        "steps": [(0, 0, S), (3, 2, W), (6, 3, N), (8, 0, S), (11, 2, W), (14, 3, N)],
+        "energy": (0.5, 1.0), "climb": True},
+    "offbeat_stabs": {   # chord tones on the "and"s, bass has the beat
+        "steps": [(2, 3, N), (6, 2, N), (10, 3, S), (14, 4, N)],
+        "energy": (0.5, 1.0), "climb": False},
+    "gallop": {
+        "steps": [(0, 0, S), (3, 0, W), (4, 2, N), (8, 0, S), (11, 0, W), (12, 3, N)],
+        "energy": (0.7, 1.0), "climb": False},
+    "run16": {           # sixteenth-note run over two octaves
+        "steps": [(r, d, (S if r % 8 == 0 else (N if r % 4 == 0 else W)))
+                  for r, d in zip(range(16), [0, 1, 2, 3, 4, 5, 4, 3, 2, 1, 0, 1, 2, 3, 4, 5])],
+        "energy": (0.8, 1.0), "climb": False},
+    "cascade": {         # falling from the top of the chord
+        "steps": [(0, 5, S), (2, 4, W), (4, 3, N), (6, 2, W),
+                  (8, 5, S), (10, 4, W), (12, 3, N), (14, 1, W)],
+        "energy": (0.5, 1.0), "climb": False},
+}
+
+
+def pick_figures(energy_pref: str, weights: dict[str, float] | None = None) -> dict[str, str]:
+    """Choose a figure per section role for the song.
+
+    Verse and chorus always differ, so the chorus arp is part of the hook
+    rather than the same loop as everything else. The bridge gets a third
+    figure; intros and outros use the sparse pulse. A style pack may pass
+    weights over figure names; figures it weights at zero are out and the
+    chorus draw is weighted.
+    """
+    if weights:
+        pool = [f for f in FIGURES if weights.get(f, 0) > 0]
+        chorus_pool = [f for f in pool if FIGURES[f]["energy"][0] >= 0.4] or pool
+        chorus = random.choices(chorus_pool, [weights[f] for f in chorus_pool], k=1)[0]
+        rest = [f for f in pool if f != chorus]
+        random.shuffle(rest)
+        return {"verse": rest[0], "chorus": chorus, "bridge": rest[1] if len(rest) > 1 else rest[0],
+                "intro": "sparse_pulse", "outro": "quarter_up"}
+    if energy_pref == "chill":
+        pool = ["quarter_up", "classic_up", "up_down", "pedal_bounce", "sparse_pulse"]
+    elif energy_pref == "intense":
+        pool = ["classic_up", "broken_octave", "sync_push", "gallop", "run16",
+                "offbeat_stabs", "cascade"]
+    else:
+        pool = ["classic_up", "up_down", "broken_octave", "pedal_bounce", "sync_push",
+                "offbeat_stabs", "cascade", "quarter_up"]
+    # The chorus runs at the top of the energy curve, so its figure must be
+    # one built for that; the verse and bridge can take anything in the pool.
+    chorus_pool = [f for f in pool if FIGURES[f]["energy"][0] >= 0.4]
+    chorus = random.choice(chorus_pool)
+    rest = [f for f in pool if f != chorus]
+    random.shuffle(rest)
+    return {"verse": rest[0], "chorus": chorus, "bridge": rest[1] if len(rest) > 1 else rest[0],
+            "intro": "sparse_pulse", "outro": "quarter_up"}
+
+
+def _ladder(chord_notes: list[int], base_octave_root: int = 48) -> list[int]:
+    """Chord tones from the root placed in octave 4, climbing three octaves."""
+    pcs = sorted({n % 12 for n in chord_notes})
+    root_pc = chord_notes[0] % 12
+    pcs = pcs[pcs.index(root_pc):] + pcs[:pcs.index(root_pc)]   # start on the root
+    root = base_octave_root + root_pc
+    while root >= base_octave_root + 12:
+        root -= 12
+    ladder = []
+    for octave in (-1, 0, 1, 2):
+        for pc in pcs:
+            n = root + ((pc - root_pc) % 12) + 12 * octave
+            ladder.append(n)
+    return ladder
+
+
+def colour_tones(chord_notes: list[int], scale_notes: list[int]) -> list[int]:
+    """The 7th and the 9th above the chord's root, as the scale spells them.
+
+    Returned as pitch offsets from the root (10 or 11 for the 7th, 13 or 14
+    for the 9th, 15 means "none"), so they work in any octave. Game-music
+    arps on strings and harps nearly always carry one of these — it is what
+    makes a harp run sound like a score rather than a music box — but they
+    must come from the scale: a major 7th over a mixolydian chord, or a
+    natural 9th in phrygian, is a wrong note.
+    """
+    pcs = {n % 12 for n in scale_notes}
+    root = chord_notes[0] % 12
+    out = []
+    for cands in ((10, 11), (14, 13)):            # 7th, then 9th
+        for off in cands:
+            if (root + off) % 12 in pcs:
+                out.append(off)
+                break
+    return out
+
+
+def generate_arp(segments: list[tuple[int, int, list[int]]], figure_name: str,
+                 energy: float, melody_rows: set[int] | None = None,
+                 scale_notes: list[int] | None = None, colour: bool = False,
+                 rows_per_bar: int = ROWS_PER_BAR) -> list[tuple[int, int, float]]:
+    """Realise a figure over a chord timeline.
+
+    segments is [(start_row, end_row, chord_notes), ...]. Returns
+    [(row, midi_note, accent), ...]. A bar may rest at low energy (never at
+    high); a climbing figure plays its even bars an octave up; and where the
+    melody is busy in a bar (melody_rows carries its onsets) the figure's
+    weak steps are dropped so the arp fills gaps rather than fighting the lead.
+
+    With colour (the SNES palette), the figure's octave-root step becomes
+    the chord's 7th or 9th, alternating by bar, drawn from the scale via
+    colour_tones. Lower steps keep the triad, so the shimmer sits on top.
+    """
+    fig = FIGURES[figure_name]
+    out = []
+    total = segments[-1][1] if segments else 0
+    bar_index = 0
+    for bar_start in range(0, total, rows_per_bar):
+        seg = next((s for s in segments if s[0] <= bar_start < s[1]), segments[0])
+        chord = seg[2]
+        ladder = _ladder(chord)
+        base = len(ladder) // 4 * 1      # index of the root in octave 4
+        per_octave = len(ladder) // 4
+        if energy < 0.8 and random.random() > energy + 0.25:
+            bar_index += 1
+            continue   # this bar rests
+        shift = per_octave if (fig["climb"] and bar_index % 2 == 1) else 0
+        busy = False
+        if melody_rows:
+            onsets = sum(1 for r in melody_rows if bar_start <= r < bar_start + rows_per_bar)
+            busy = onsets >= 5
+        tints = colour_tones(chord, scale_notes) if (colour and scale_notes) else []
+        tint = tints[bar_index % len(tints)] if tints else None
+        for row_off, degree, accent in fig["steps"]:
+            if busy and accent == W:
+                continue
+            idx = base + degree + shift
+            if not (0 <= idx < len(ladder)):
+                continue
+            note = ladder[idx]
+            # The octave-root step (and any further octave of it) carries
+            # the colour tone, an octave below the root it replaces so the
+            # 7th/9th sits just above the triad rather than far on top.
+            if tint is not None and degree > 0 and degree % per_octave == 0:
+                note = ladder[idx - per_octave] + tint
+            row = bar_start + row_off
+            if row < total:
+                out.append((row, note, accent))
+        bar_index += 1
+    return out