bitcomposer 1.0.0rc1__py3-none-any.whl

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/__main__.py

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

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

bitcomposer/bass.py

@@ -0,0 +1,173 @@
+"""
+Bass generation. (Arpeggios live in arp.py.)
+"""
+
+import random
+
+from . import theory
+from .pattern import ROWS_PER_BAR, ROWS_PER_BEAT
+
+
+# Riffs: (row in bar, interval from the root) of a one-bar figure that
+# repeats. Intervals stay chord-safe (root, fifth, octave, seventh), so a riff
+# fits major and minor alike. One riff per song, drawn by the composer from
+# the pack's weights; a stage theme has its own riff, not the game's.
+RIFFS = {
+    "rock":         [(0, 0), (2, 0), (4, 12), (6, 0), (8, 0), (10, 7), (12, 12), (14, 7)],
+    "gallop":       [(0, 0), (3, 0), (4, 0), (6, 12), (8, 0), (11, 0), (12, 0), (14, 7)],
+    "funk":         [(0, 0), (3, 12), (6, 0), (10, 7), (12, 0), (14, 10)],
+    "pedal_push":   [(0, 0), (2, 0), (4, 0), (6, 0), (7, 12), (8, 0), (10, 0), (12, 0), (14, 12)],
+    "octaves":      [(0, 0), (2, 12), (4, 0), (6, 12), (8, 0), (10, 12), (12, 7), (14, 12)],
+    "fifth_bounce": [(0, 0), (2, 7), (4, 0), (6, 7), (8, 12), (10, 7), (12, 0), (14, 7)],
+    "drop":         [(0, 0), (2, 0), (6, 0), (8, 12), (10, 10), (12, 7), (14, 0)],
+}
+RIFF = RIFFS["rock"]
+
+
+# The lowest bass note written, as MIDI (28 is E1, 41.2 Hz, a bass guitar's
+# low string). The windows below sit on it. Before the note conversion was
+# corrected the whole engine sounded an octave low and the bass reached
+# 13 Hz; the floor keeps any style's octave drop or cadence walk honest.
+BASS_FLOOR = 28
+
+
+def floor_bass(notes: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    """Every note below BASS_FLOOR raised by octaves until it is not."""
+    out = []
+    for row, note in notes:
+        while 0 < note < BASS_FLOOR:
+            note += 12
+        out.append((row, note))
+    return out
+
+
+def generate_bass(root: int, chord_type: str,
+                  rows: int, style: str = "steady",
+                  weight: str = "heavy",
+                  density: float = 1.0, riff: str | None = None,
+                  scale_notes: list[int] | None = None) -> list[tuple[int, int]]:
+    """Generate a bass line. Returns [(row, midi_note), ...].
+
+    density (0..1) thins the off-beat notes. The line previously played every
+    slot its style produced, unconditionally, for every pattern in the song —
+    the same "never rests" problem the arp had. Bar downbeats are always kept,
+    since the bass has to state the chord.
+    """
+    # Register depends on weight, in MIDI (the conversion to the pattern is
+    # exact since 2026-10-17; before that everything sounded an octave low).
+    if weight == "light":
+        # MIDI 40-51 (82-165 Hz) — punchier, more melodic
+        bass_root = root
+        while bass_root >= 52:
+            bass_root -= 12
+        while bass_root < 40:
+            bass_root += 12
+    elif weight == "medium":
+        # MIDI 34-45 (58-110 Hz) — middle ground
+        bass_root = root
+        while bass_root >= 46:
+            bass_root -= 12
+        while bass_root < 34:
+            bass_root += 12
+    else:
+        # MIDI 28-39 (41-78 Hz) — deep and heavy
+        bass_root = root
+        while bass_root >= 40:
+            bass_root -= 12
+        while bass_root < 28:
+            bass_root += 12
+
+    chord = theory.build_chord(bass_root, chord_type)
+    notes = []
+
+    # Sparser step sizes for lighter weights
+    if weight == "light":
+        step_scale = 2  # half as many notes
+    elif weight == "medium":
+        step_scale = 1.5
+    else:
+        step_scale = 1
+
+    if style == "steady":
+        step = int(8 * step_scale)
+        for row in range(0, rows, step):
+            notes.append((row, bass_root))
+    elif style == "octave":
+        step = int(4 * step_scale)
+        for i, row in enumerate(range(0, rows, step)):
+            if i % 2 == 0:
+                notes.append((row, bass_root))
+            else:
+                notes.append((row, bass_root + 12))
+    elif style == "walking":
+        step = int(4 * step_scale)
+        for i, row in enumerate(range(0, rows, step)):
+            note = chord[i % len(chord)]
+            notes.append((row, note))
+    elif style == "driving":
+        step = int(2 * step_scale)
+        for row in range(0, rows, step):
+            notes.append((row, bass_root))
+    elif style == "drone":
+        # One note per chord, held for the whole segment; the composer slides
+        # between roots (porta) so the drone moves without restriking.
+        notes.append((0, bass_root))
+    elif style == "riff":
+        # A one-bar riff that repeats: root on the beat, the octave and the
+        # fifth pushing between, the way a rock bass carries a stage theme.
+        figure = RIFFS.get(riff or "rock", RIFF)
+        # A riff's seventh is only in key for minor, dorian, mixolydian and
+        # minor pentatonic; in a major key it sat a semitone under the
+        # melody's note. Snap every interval to the nearest scale tone at or
+        # below it, so the seventh becomes the sixth where that is the key's
+        # note and stays a seventh where it is.
+        classes = {n % 12 for n in scale_notes} if scale_notes else None
+        for bar in range(0, rows, ROWS_PER_BAR):
+            for off, iv in figure:
+                if bar + off >= rows:
+                    continue
+                note = bass_root + iv
+                if classes and note % 12 not in classes:
+                    while note % 12 not in classes and note > bass_root - 12:
+                        note -= 1
+                notes.append((bar + off, note))
+
+    # A riff is a figure and repeats exactly; the thinning that lets the
+    # other styles rest would make it stumble from bar to bar.
+    if density < 1.0 and style != "riff":
+        notes = [
+            (row, note) for row, note in notes
+            if row % ROWS_PER_BAR == 0 or random.random() < density
+        ]
+
+    return notes
+
+
+def pick_section_bass(bass_weight: str, section_energy: float,
+                      bass_style: str) -> str:
+    """Choose bass style for a section based on weight and energy."""
+    if bass_style in ("drone", "riff"):
+        return bass_style              # a drone or a riff does not lift with the section
+    if bass_weight == "light":
+        if section_energy > 0.85:
+            return random.choice(["steady", "walking"])
+        return random.choice(["steady", "steady", "walking"])
+    elif section_energy < 0.5:
+        return random.choice(["steady", "steady"])
+    elif section_energy > 0.85:
+        return random.choice(["driving", "octave", bass_style])
+    return bass_style
+
+
+def generate_bass_timeline(segments: list[tuple[int, int, int, str]],
+                           style: str = "steady", weight: str = "heavy",
+                           density: float = 1.0,
+                           riff: str | None = None,
+                           scale_notes: list[int] | None = None) -> list[tuple[int, int]]:
+    """generate_bass over [(start_row, end_row, root, chord_type), ...]."""
+    notes = []
+    for start, end, root, chord_type in segments:
+        part = generate_bass(root, chord_type, end - start, style, weight, density, riff=riff,
+                             scale_notes=scale_notes)
+        notes.extend((start + row, note) for row, note in part)
+    return notes