mpump 1.3.10__py3-none-any.whl

mpump/__init__.py

@@ -0,0 +1,3 @@
+"""mpump — hot-plug MIDI sequencer."""
+
+__version__ = "1.3.10"

mpump/cli.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+mpump — hot-plug MIDI sequencer.
+
+Watches for USB MIDI devices and starts sequencing automatically.
+Plug or unplug devices at any time — loops start/stop automatically.
+
+Default: opens the terminal UI.  Pass --cli for headless operation.
+"""
+
+import argparse
+import sys
+
+from .devices import DEVICE_REGISTRY
+from .keys import parse_key, valid_key_names, DEFAULT_KEY, DEFAULT_OCTAVE, OCTAVE_MIN, OCTAVE_MAX
+from .patterns import get_pattern, list_patterns, GENRE_NAMES, GENRES
+from .patterns_t8 import (
+    get_t8_drum_pattern, get_t8_bass_pattern,
+    list_t8_patterns, list_t8_bass_patterns, T8_GENRE_NAMES, T8_BASS,
+)
+from . import extras as _extras  # noqa: F401 — injects "extras" genre
+from .patterns_j6 import (
+    get_j6_pattern, get_j6_chord_set, list_j6_patterns, J6_GENRE_NAMES, J6_GENRES,
+)
+from .scanner import DeviceScanner
+
+DEFAULT_GENRE      = "techno"
+DEFAULT_PATTERN    = 1
+DEFAULT_BPM        = 120
+DEFAULT_T8_GENRE        = "techno"
+DEFAULT_T8_PATTERN      = 1
+DEFAULT_T8_BASS_GENRE   = "techno"
+DEFAULT_T8_BASS_PATTERN = 1
+DEFAULT_J6_GENRE   = "techno"
+DEFAULT_J6_PATTERN = 1
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="mpump",
+        description="mpump — hot-plug MIDI sequencer (default: terminal UI, use --cli for headless)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "S-1 genres:  " + ", ".join(GENRE_NAMES) + "\n"
+            "T-8 genres:  " + ", ".join(T8_GENRE_NAMES) + "\n"
+            "J-6 genres:  " + ", ".join(J6_GENRE_NAMES) + "\n"
+            "Keys:        " + ", ".join(valid_key_names()) + "\n\n"
+            "UI key bindings:\n"
+            "  Tab        Switch focus between S-1, T-8 and J-6 panels\n"
+            "  ← / →      Previous / next genre\n"
+            "  ↑ / ↓      Previous / next pattern\n"
+            "  b / B      T-8 bass pattern down / up\n"
+            "  k / K      Key down / up  (not J-6)\n"
+            "  o / O      Octave down / up  (not J-6)\n"
+            "  Space      Pause / resume focused device\n"
+            "  = / -      BPM +5 / -5\n"
+            "  Enter      Commit browsed pattern / genre\n"
+            "  q          Quit\n\n"
+            "Other interfaces:\n"
+            "  mpump-web         Web UI (Mac + Python, control from any browser)\n"
+            "  mpump/server/     Browser sequencer (standalone, Web MIDI, 50 devices)\n"
+        ),
+    )
+    parser.add_argument(
+        "--cli", action="store_true",
+        help="Run in headless CLI mode instead of the terminal UI",
+    )
+    parser.add_argument(
+        "--bpm", type=int, default=DEFAULT_BPM, metavar="BPM",
+        help=f"Tempo in BPM (20–300, default {DEFAULT_BPM})",
+    )
+
+    # S-1 options
+    s1 = parser.add_argument_group("S-1 (monosynth)")
+    s1.add_argument(
+        "--genre", default=DEFAULT_GENRE, choices=GENRE_NAMES, metavar="GENRE",
+        help=f"Pattern genre: {', '.join(GENRE_NAMES)} (default: {DEFAULT_GENRE})",
+    )
+    s1.add_argument(
+        "--pattern", type=int, default=DEFAULT_PATTERN, metavar="N",
+        help=f"Pattern 1–10 within genre (default: {DEFAULT_PATTERN})",
+    )
+    s1.add_argument(
+        "--key", default=DEFAULT_KEY, metavar="KEY",
+        help=f"Root key, e.g. A, F#, Bb (default: {DEFAULT_KEY})",
+    )
+    s1.add_argument(
+        "--octave", type=int, default=DEFAULT_OCTAVE, metavar="N",
+        help=(
+            f"Root octave ({OCTAVE_MIN}–{OCTAVE_MAX}, default {DEFAULT_OCTAVE}). "
+            "A2=45, A3=57, A1=33"
+        ),
+    )
+
+    # T-8 options
+    t8 = parser.add_argument_group("T-8 (drum machine + bass)")
+    t8.add_argument(
+        "--t8-genre", default=DEFAULT_T8_GENRE, choices=T8_GENRE_NAMES,
+        metavar="GENRE",
+        help=f"T-8 drum genre (default: {DEFAULT_T8_GENRE})",
+    )
+    t8.add_argument(
+        "--t8-pattern", type=int, default=DEFAULT_T8_PATTERN, metavar="N",
+        help=f"T-8 drum pattern 1–10 (default: {DEFAULT_T8_PATTERN})",
+    )
+    t8.add_argument(
+        "--t8-bass-genre", default=DEFAULT_T8_BASS_GENRE, choices=T8_GENRE_NAMES,
+        metavar="GENRE",
+        help=f"T-8 bass genre, independent of drums (default: same as --t8-genre)",
+    )
+    t8.add_argument(
+        "--t8-bass-pattern", type=int, default=DEFAULT_T8_BASS_PATTERN, metavar="N",
+        help=f"T-8 bass pattern 1–10, independent of drums (default: {DEFAULT_T8_BASS_PATTERN})",
+    )
+    t8.add_argument(
+        "--t8-key", default=DEFAULT_KEY, metavar="KEY",
+        help=f"Root key for T-8 bass (default: {DEFAULT_KEY})",
+    )
+    t8.add_argument(
+        "--t8-octave", type=int, default=DEFAULT_OCTAVE, metavar="N",
+        help=f"Root octave for T-8 bass ({OCTAVE_MIN}–{OCTAVE_MAX}, default {DEFAULT_OCTAVE})",
+    )
+
+    # J-6 options
+    j6 = parser.add_argument_group("J-6 (chord synthesizer)")
+    j6.add_argument(
+        "--j6-genre", default=DEFAULT_J6_GENRE, choices=J6_GENRE_NAMES, metavar="GENRE",
+        help=f"J-6 chord genre: {', '.join(J6_GENRE_NAMES)} (default: {DEFAULT_J6_GENRE})",
+    )
+    j6.add_argument(
+        "--j6-pattern", type=int, default=DEFAULT_J6_PATTERN, metavar="N",
+        help=f"J-6 chord pattern 1–10 (default: {DEFAULT_J6_PATTERN})",
+    )
+
+    # Listing
+    parser.add_argument("--list",          action="store_true", help="List all synth patterns and exit")
+    parser.add_argument("--list-drums",    action="store_true", help="List all drum patterns and exit")
+    parser.add_argument("--list-bass",     action="store_true", help="List all bass patterns and exit")
+    parser.add_argument("--list-devices",  action="store_true", help="List all 50 supported devices and exit")
+    # Deprecated aliases
+    parser.add_argument("--list-t8",       action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("--list-t8-bass",  action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("--list-j6",       action="store_true", help="List all J-6 chord patterns and exit")
+
+    return parser.parse_args()
+
+
+def _print_devices() -> None:
+    print("Supported devices (50):\n")
+    print(f"  {'ID':<20} {'Label':<22} {'Mode':<12} {'Port match'}")
+    print(f"  {'─'*20} {'─'*22} {'─'*12} {'─'*20}")
+    for d in DEVICE_REGISTRY:
+        print(f"  {d.id:<20} {d.label:<22} {d.mode:<12} {d.port_match}")
+
+
+def main() -> None:
+    args = parse_args()
+
+    if args.list_devices:
+        _print_devices()
+        return
+
+    if args.list:
+        print(list_patterns())
+        return
+
+    if args.list_drums or args.list_t8:
+        print(list_t8_patterns())
+        return
+
+    if args.list_bass or args.list_t8_bass:
+        print(list_t8_bass_patterns())
+        return
+
+    if args.list_j6:
+        print(list_j6_patterns())
+        return
+
+    if not (20 <= args.bpm <= 300):
+        print("Error: --bpm must be between 20 and 300", file=sys.stderr)
+        sys.exit(1)
+
+    if not args.cli:
+        from .ui import run_ui
+        run_ui(
+            bpm=args.bpm,
+            s1_genre=args.genre,              s1_pattern=args.pattern,
+            s1_key=args.key,                  s1_octave=args.octave,
+            t8_genre=args.t8_genre,           t8_pattern=args.t8_pattern,
+            t8_bass_genre=args.t8_bass_genre, t8_bass_pattern=args.t8_bass_pattern,
+            t8_key=args.t8_key,               t8_octave=args.t8_octave,
+            j6_genre=args.j6_genre,           j6_pattern=args.j6_pattern,
+        )
+        return
+
+    # S-1 ----------------------------------------------------------------
+    try:
+        s1_root = parse_key(args.key, args.octave)
+    except ValueError as e:
+        print(f"Error (S-1 key): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        s1_pattern = get_pattern(args.genre, args.pattern)
+    except ValueError as e:
+        print(f"Error (S-1 pattern): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # T-8 ----------------------------------------------------------------
+    try:
+        t8_bass_root = parse_key(args.t8_key, args.t8_octave)
+    except ValueError as e:
+        print(f"Error (T-8 key): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        t8_drum = get_t8_drum_pattern(args.t8_genre, args.t8_pattern)
+    except ValueError as e:
+        print(f"Error (T-8 pattern): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        t8_bass, t8_bass_desc = get_t8_bass_pattern(args.t8_bass_genre, args.t8_bass_pattern)
+    except ValueError as e:
+        print(f"Error (T-8 bass pattern): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    t8_bass_name = T8_BASS[args.t8_bass_genre][args.t8_bass_pattern - 1][0]
+
+    # J-6 ----------------------------------------------------------------
+    try:
+        j6_pattern = get_j6_pattern(args.j6_genre, args.j6_pattern)
+    except ValueError as e:
+        print(f"Error (J-6 pattern): {e}", file=sys.stderr)
+        sys.exit(1)
+
+    j6_chord_set = get_j6_chord_set(args.j6_genre)
+    j6_pc        = j6_chord_set - 1   # PC value is 0-indexed
+
+    # Header -------------------------------------------------------------
+    s1_name, s1_desc, _ = GENRES[args.genre][args.pattern - 1]
+    from .patterns_t8 import T8_DRUMS
+    t8_name, t8_desc, _ = T8_DRUMS[args.t8_genre][args.t8_pattern - 1]
+    j6_name, j6_desc, _ = J6_GENRES[args.j6_genre][args.j6_pattern - 1]
+
+    print(f"mpump — {args.bpm} BPM  (Ctrl-C to quit)")
+    print(f"S-1  key={args.key}{args.octave}  {args.genre}  #{args.pattern}: {s1_name}")
+    print(f'     "{s1_desc}"')
+    print(f"T-8  key={args.t8_key}{args.t8_octave}")
+    print(f"     drums {args.t8_genre}  #{args.t8_pattern}: {t8_name}  —  {t8_desc}")
+    print(f"     bass  {args.t8_bass_genre}  #{args.t8_bass_pattern}: {t8_bass_name}  —  {t8_bass_desc}")
+    print(f"J-6  {args.j6_genre}  #{args.j6_pattern}: {j6_name}  (chord set #{j6_chord_set})")
+    print(f'     "{j6_desc}"')
+    print()
+
+    scanner = DeviceScanner(
+        bpm=args.bpm,
+        device_states={
+            "s1": {"pattern": s1_pattern, "root": s1_root},
+            "t8": {"drum_pattern": t8_drum, "bass_pattern": t8_bass, "bass_root": t8_bass_root},
+            "j6": {"pattern": j6_pattern, "program_change": j6_pc},
+        },
+    )
+    scanner.run()
+
+
+if __name__ == "__main__":
+    main()

mpump/devices.py

@@ -0,0 +1,193 @@
+# Data-driven device registry for 50 USB MIDI devices.
+#
+# Mirrors mpump/server/src/data/devices.ts — every device that the browser
+# sequencer supports is also listed here so the Python CLI/TUI/web backend
+# can auto-detect and sequence it.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class DeviceConfig:
+    id: str                # "s1", "tr6s", etc.
+    label: str             # "S-1", "TR-6S"
+    port_match: str        # substring to match in MIDI port name
+    mode: str              # "synth" | "drums" | "drums+bass"
+    channel: int           # main MIDI channel (0-indexed)
+    bass_channel: int | None = None   # bass channel for drums+bass
+    root_note: int = 45    # default root MIDI note
+    gate_frac: float = 0.5
+    drum_gate_frac: float = 0.10
+    bass_gate_frac: float = 0.50
+    base_velocity: int = 100
+    drum_map: dict[int, int] | None = None
+    has_key: bool = True
+    has_octave: bool = True
+    use_program_change: bool = False
+    send_clock: bool = False
+
+
+def _synth(
+    id: str, label: str, port_match: str, **kw,
+) -> DeviceConfig:
+    return DeviceConfig(
+        id=id, label=label, port_match=port_match, mode="synth",
+        channel=kw.pop("channel", 0), **kw,
+    )
+
+
+def _drums(
+    id: str, label: str, port_match: str, **kw,
+) -> DeviceConfig:
+    return DeviceConfig(
+        id=id, label=label, port_match=port_match, mode="drums",
+        channel=kw.pop("channel", 9), has_key=kw.pop("has_key", False),
+        has_octave=kw.pop("has_octave", False), root_note=kw.pop("root_note", 36),
+        **kw,
+    )
+
+
+def _drums_bass(
+    id: str, label: str, port_match: str, **kw,
+) -> DeviceConfig:
+    return DeviceConfig(
+        id=id, label=label, port_match=port_match, mode="drums+bass",
+        channel=kw.pop("channel", 9), bass_channel=kw.pop("bass_channel", 1),
+        **kw,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 50-device registry  (order matches devices.ts)
+# ---------------------------------------------------------------------------
+
+DEVICE_REGISTRY: list[DeviceConfig] = [
+    # ── Roland AIRA Compact ──────────────────────────────────────────────
+    _synth("s1", "S-1", "S-1", send_clock=True),
+    _drums_bass("t8", "T-8", "T-8", send_clock=True),
+    _synth("j6", "J-6", "J-6",
+           root_note=60, gate_frac=0.8, has_key=False, has_octave=False,
+           use_program_change=True, send_clock=True),
+
+    # ── Roland ────────────────────────────────────────────────────────────
+    _drums("tr6s", "TR-6S", "TR-6S"),
+    _drums("tr8s", "TR-8S", "TR-8S"),
+    _drums_bass("mc101", "MC-101", "MC-101", channel=0, bass_channel=1),
+    _drums_bass("mc707", "MC-707", "MC-707", channel=0, bass_channel=1),
+    _synth("sh4d", "SH-4d", "SH-4d"),
+    _synth("tb3", "TB-3", "TB-3"),
+    _synth("tb03", "TB-03", "Boutique"),
+    _synth("jdxi", "JD-Xi", "JD-Xi"),
+    _synth("ju06a", "JU-06A", "Boutique"),
+    _synth("se02", "SE-02", "Boutique"),
+    _synth("gaia2", "GAIA 2", "GAIA 2"),
+    _synth("sp404mk2", "SP-404MK2", "SP-404MK2",
+           root_note=36, gate_frac=0.3, has_key=False, has_octave=False),
+
+    # ── Korg ──────────────────────────────────────────────────────────────
+    _synth("minilogue_xd", "minilogue xd", "minilogue xd"),
+    _synth("monologue", "monologue", "monologue"),
+    _synth("nts1", "NTS-1", "NTS-1 digital kit"),
+    _drums_bass("drumlogue", "drumlogue", "drumlogue", channel=9, bass_channel=0),
+    _synth("minilogue", "minilogue", "minilogue"),
+    _synth("wavestate", "wavestate", "wavestate"),
+    _synth("opsix", "opsix", "opsix"),
+    _synth("modwave", "modwave", "modwave"),
+
+    # ── Novation ──────────────────────────────────────────────────────────
+    _drums_bass("circuit_tracks", "Circuit Tracks", "Circuit Tracks",
+                channel=9, bass_channel=0),
+    _drums("circuit_rhythm", "Circuit Rhythm", "Circuit Rhythm"),
+    _synth("bass_station_ii", "Bass Station II", "Bass Station II"),
+    _synth("peak", "Peak", "Peak"),
+
+    # ── Arturia ───────────────────────────────────────────────────────────
+    _synth("microfreak", "MicroFreak", "MicroFreak"),
+    _drums("drumbrute_impact", "DrumBrute Impact", "DrumBrute Impact"),
+
+    # ── Behringer ─────────────────────────────────────────────────────────
+    _synth("td3", "TD-3", "TD-3"),
+    _drums("rd6", "RD-6", "RD-6", channel=0,
+           drum_map={36: 36, 38: 40, 42: 42, 46: 46, 50: 39, 49: 51}),
+    _synth("crave", "Crave", "Crave"),
+    _synth("model_d", "Model D", "MODEL D"),
+    _synth("neutron", "Neutron", "Neutron"),
+    _synth("poly_d", "Poly D", "Poly D"),
+    _synth("k2", "K-2", "K-2"),
+    _synth("ms1", "MS-1", "MS-1"),
+    _synth("deepmind12", "DeepMind 12", "DeepMind 12"),
+    _synth("wasp_deluxe", "Wasp Deluxe", "Wasp Deluxe"),
+
+    # ── Elektron ──────────────────────────────────────────────────────────
+    _drums("syntakt", "Syntakt", "Syntakt", channel=0),
+    _drums("digitakt", "Digitakt", "Digitakt", channel=0,
+           drum_map={36: 24, 38: 25, 42: 26, 46: 27, 50: 28, 49: 29}),
+    _drums_bass("model_cycles", "Model:Cycles", "Model:Cycles",
+                channel=0, bass_channel=5),
+    _drums("model_samples", "Model:Samples", "Model:Samples", channel=0),
+    _drums("analog_rytm", "Analog Rytm MKII", "Analog Rytm MKII"),
+    _synth("analog_four", "Analog Four MKII", "Analog Four MKII"),
+
+    # ── Teenage Engineering ───────────────────────────────────────────────
+    _synth("opz", "OP-Z", "OP-Z", channel=4),
+    _drums_bass("ep133", "EP-133 K.O. II", "EP-133", channel=0, bass_channel=1),
+
+    # ── Sequential ────────────────────────────────────────────────────────
+    _synth("take5", "Take 5", "Take 5"),
+
+    # ── IK Multimedia ─────────────────────────────────────────────────────
+    _drums("uno_drum", "UNO Drum", "UNO Drum"),
+    _synth("uno_synth", "UNO Synth", "UNO Synth"),
+]
+
+# Fast lookup by id
+_REGISTRY_BY_ID: dict[str, DeviceConfig] = {d.id: d for d in DEVICE_REGISTRY}
+
+
+def get_device(device_id: str) -> DeviceConfig | None:
+    return _REGISTRY_BY_ID.get(device_id)
+
+
+def find_device(port_name: str) -> DeviceConfig | None:
+    """Return the first DeviceConfig whose port_match is a substring of *port_name*."""
+    for cfg in DEVICE_REGISTRY:
+        if cfg.port_match in port_name:
+            return cfg
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Backwards-compat: old DEVICES dict shape used by ui.py
+# ---------------------------------------------------------------------------
+
+def _compat_dict() -> dict[str, dict]:
+    """Build the old-style DEVICES dict for code that still uses it."""
+    out: dict[str, dict] = {}
+    for cfg in DEVICE_REGISTRY:
+        if cfg.mode == "drums+bass":
+            out[cfg.label] = {
+                "port_match": cfg.port_match,
+                "drum_channel": cfg.channel,
+                "bass_channel": cfg.bass_channel,
+                "bass_root": None,
+                "base_velocity": cfg.base_velocity,
+                "drum_pattern": None,
+                "bass_pattern": None,
+                "type": "t8",
+            }
+        else:
+            out[cfg.label] = {
+                "port_match": cfg.port_match,
+                "channel": cfg.channel,
+                "root_note": cfg.root_note,
+                "base_velocity": cfg.base_velocity,
+                "note_fraction": cfg.gate_frac,
+                "pattern": None,
+                "type": "synth",
+            }
+    return out
+
+
+DEVICES: dict[str, dict] = _compat_dict()

mpump/extras.py

@@ -0,0 +1,166 @@
+"""Persistence layer for user-created patterns stored in ~/.mpump/extras.json.
+
+On import, loads saved patterns and injects an "extras" genre into the
+shared genre dicts (GENRES, T8_DRUMS, T8_BASS, J6_GENRES) so all
+interfaces (web, TUI, CLI) see them automatically.
+
+Keys are mode-based: "synth", "drums", "bass", "chords".
+Old device-specific keys ("s1", "t8_drums", "t8_bass", "j6") are
+migrated automatically on load.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .patterns import GENRES, GENRE_NAMES
+from .patterns_j6 import J6_CHORD_SETS, J6_GENRE_NAMES, J6_GENRES
+from .patterns_t8 import T8_BASS, T8_DRUMS, T8_GENRE_NAMES
+
+EXTRAS_DIR = Path.home() / ".mpump"
+EXTRAS_FILE = EXTRAS_DIR / "extras.json"
+
+GENRE_KEY = "extras"
+
+# Old key → new key migration map
+_MIGRATE = {"s1": "synth", "t8_drums": "drums", "t8_bass": "bass", "j6": "chords"}
+
+# ── Serialisation helpers ─────────────────────────────────────────────────
+
+def _ser_step(s):
+    if s is None:
+        return None
+    return {"semi": s[0], "vel": s[1], "slide": s[2]}
+
+
+def _deser_step(s):
+    if s is None:
+        return None
+    return (s["semi"], s["vel"], s["slide"])
+
+
+def _ser_drum_step(s):
+    return [{"note": n, "vel": v} for n, v in s]
+
+
+def _deser_drum_step(s):
+    return [(h["note"], h["vel"]) for h in s]
+
+
+# ── Disk I/O ──────────────────────────────────────────────────────────────
+
+def _load_raw() -> dict:
+    if not EXTRAS_FILE.exists():
+        return {}
+    try:
+        with open(EXTRAS_FILE) as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+    # Migrate old keys if present
+    migrated = False
+    for old_key, new_key in _MIGRATE.items():
+        if old_key in data and new_key not in data:
+            data[new_key] = data.pop(old_key)
+            migrated = True
+        elif old_key in data and new_key in data:
+            # Merge old into new, then remove old
+            data[new_key].extend(data.pop(old_key))
+            migrated = True
+    if migrated:
+        _save_raw(data)
+    return data
+
+
+def _save_raw(data: dict):
+    EXTRAS_DIR.mkdir(parents=True, exist_ok=True)
+    with open(EXTRAS_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+
+# ── Convert JSON → tuple format expected by genre dicts ───────────────────
+
+def _to_melodic_tuples(patterns: list) -> list[tuple]:
+    return [
+        (p["name"], p["desc"], [_deser_step(s) for s in p["steps"]])
+        for p in patterns
+    ]
+
+
+def _to_drum_tuples(patterns: list) -> list[tuple]:
+    return [
+        (p["name"], p["desc"], [_deser_drum_step(s) for s in p["steps"]])
+        for p in patterns
+    ]
+
+
+# ── Inject / reload ──────────────────────────────────────────────────────
+
+def reload():
+    """(Re)load extras from disk and update the shared genre dicts in place."""
+    data = _load_raw()
+
+    GENRES[GENRE_KEY] = _to_melodic_tuples(data.get("synth", []))
+    T8_DRUMS[GENRE_KEY] = _to_drum_tuples(data.get("drums", []))
+    T8_BASS[GENRE_KEY] = _to_melodic_tuples(data.get("bass", []))
+    J6_GENRES[GENRE_KEY] = _to_melodic_tuples(data.get("chords", []))
+
+    for names in (GENRE_NAMES, T8_GENRE_NAMES, J6_GENRE_NAMES):
+        if GENRE_KEY not in names:
+            names.append(GENRE_KEY)
+
+    J6_CHORD_SETS.setdefault(GENRE_KEY, 1)
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+# Mode-based key map for public API (accepts both old and new names)
+_KEY_MAP = {
+    "s1": "synth", "synth": "synth",
+    "t8": "drums", "drums": "drums",
+    "t8_bass": "bass", "bass": "bass",
+    "j6": "chords", "chords": "chords",
+}
+
+_DRUM_KEYS = {"drums", "t8"}
+
+
+def save_pattern(device: str, name: str, desc: str, steps: list) -> bool:
+    """Persist a pattern to extras.  *device* is synth|drums|bass|chords (or legacy s1|t8|t8_bass|j6)."""
+    key = _KEY_MAP.get(device)
+    if not key:
+        return False
+
+    data = _load_raw()
+
+    if device in _DRUM_KEYS or key == "drums":
+        serialized = [_ser_drum_step(s) for s in steps]
+    else:
+        serialized = [_ser_step(s) for s in steps]
+
+    data.setdefault(key, []).append({"name": name, "desc": desc, "steps": serialized})
+    _save_raw(data)
+    reload()
+    return True
+
+
+def delete_pattern(device: str, idx: int) -> bool:
+    """Delete pattern at 0-based *idx* from the extras genre."""
+    key = _KEY_MAP.get(device)
+    if not key:
+        return False
+
+    data = _load_raw()
+    patterns = data.get(key, [])
+    if not (0 <= idx < len(patterns)):
+        return False
+
+    patterns.pop(idx)
+    _save_raw(data)
+    reload()
+    return True
+
+
+# Run on first import — all interfaces that ``import extras`` get the genre.
+reload()