Pad Grid

a playable synth instrument with record, replay and training modes.

▶ Run in browser

Tags: 2d audio ui touch

An 8x8 grid of pads where every sound is synthesised at runtime, with no audio files. Columns step through the chosen musical scale and rows climb by octaves, so anything you play stays in key. Each press lights its pad with a glow, a burst of sparks and a ripple, all drawn in on_draw.

How it is built:

• AudioSynth bakes each note once, the first time it is played, from Oscillator.sine partials shaped by Exponential and ADSR envelopes, plus WhiteNoise through a LowPass for the percussion’s attack. The plucked string is a custom AudioSource: a Karplus-Strong delay line, written as a render method returning NumPy samples.

• A pool of AudioPlayer voices plays the notes, so several ring at once. A new note takes the voice that falls silent soonest, cutting it short only when every voice is still ringing.

• Input.pointers holds the mouse, every finger and a pen, each with its own press, drag and release, so eight fingers play eight pads and dragging across the grid is a glissando. A touchscreen or pen that measures pressure sets the note’s velocity; otherwise the panel’s velocity mode does: Fixed, or Wobble, where the faster the mouse was moving the louder the note.

• The keys are actions in the class’s input_context: one action per keyboard pad, polled with Input.just_pressed and just_released.

• The control panel is an anchored Panel holding a VBoxContainer of Button rows, a DropDown and Slider widgets. Each exclusive choice (instrument, velocity, mode) is a ButtonGroup of toggle buttons, and Loop, Quant and Retrig are single toggle buttons.

Modes: Perform just plays. Record captures what you play, snapped to 16th notes at the BPM slider’s tempo when Quant is on. Replay plays the phrase back, looping when Loop is on, and the BPM slider retimes it. Train lights the next note of the phrase and waits for you to hit it; Follow runs the phrase in time and lights each pad as it comes due, leaving every note for you to play. With Retrig on, pressing a pad again layers the new note over the ringing one.

Controls: click, tap or drag across the pads. The bottom four rows are also the keyboard rows Z to comma, A to K, Q to I and 1 to 8. Page Up and Page Down, or the panel’s OCT buttons, shift the octave; F1 to F6 pick an instrument.

Source

# /// simvx
# tags = ["2d", "audio", "ui", "touch"]
# web = { width = 1280, height = 720 }
# ///
"""Pad Grid: a playable synth instrument with record, replay and training modes.

An 8x8 grid of pads where every sound is synthesised at runtime, with no audio
files. Columns step through the chosen musical scale and rows climb by octaves,
so anything you play stays in key. Each press lights its pad with a glow, a
burst of sparks and a ripple, all drawn in ``on_draw``.

How it is built:

- ``AudioSynth`` bakes each note once, the first time it is played, from
  ``Oscillator.sine`` partials shaped by ``Exponential`` and ``ADSR``
  envelopes, plus ``WhiteNoise`` through a ``LowPass`` for the percussion's
  attack. The plucked string is a custom ``AudioSource``: a Karplus-Strong
  delay line, written as a ``render`` method returning NumPy samples.
- A pool of ``AudioPlayer`` voices plays the notes, so several ring at once.
  A new note takes the voice that falls silent soonest, cutting it short only
  when every voice is still ringing.
- ``Input.pointers`` holds the mouse, every finger and a pen, each with its
  own press, drag and release, so eight fingers play eight pads and dragging
  across the grid is a glissando. A touchscreen or pen that measures pressure
  sets the note's velocity; otherwise the panel's velocity mode does: Fixed,
  or Wobble, where the faster the mouse was moving the louder the note.
- The keys are actions in the class's ``input_context``: one action per
  keyboard pad, polled with ``Input.just_pressed`` and ``just_released``.
- The control panel is an anchored ``Panel`` holding a ``VBoxContainer`` of
  ``Button`` rows, a ``DropDown`` and ``Slider`` widgets. Each exclusive
  choice (instrument, velocity, mode) is a ``ButtonGroup`` of toggle buttons,
  and Loop, Quant and Retrig are single toggle buttons.

Modes: Perform just plays. Record captures what you play, snapped to 16th
notes at the BPM slider's tempo when Quant is on. Replay plays the phrase back,
looping when Loop is on, and the BPM slider retimes it. Train lights the next
note of the phrase and waits for you to hit it; Follow runs the phrase in time
and lights each pad as it comes due, leaving every note for you to play. With
Retrig on, pressing a pad again layers the new note over the ringing one.

Controls: click, tap or drag across the pads. The bottom four rows are also
the keyboard rows Z to comma, A to K, Q to I and 1 to 8. Page Up and Page Down,
or the panel's OCT buttons, shift the octave; F1 to F6 pick an instrument.
"""

import math
from bisect import bisect_right
from collections import deque
from dataclasses import dataclass, field
from enum import StrEnum
from functools import cache
from operator import attrgetter
from typing import NamedTuple

import numpy as np

from simvx.core import (
    ADSR,
    Anchor,
    AudioClip,
    AudioPlayer,
    AudioSynth,
    Button,
    ButtonGroup,
    DropDown,
    Exponential,
    HBoxContainer,
    Input,
    Key,
    Label,
    LowPass,
    Node,
    Oscillator,
    Panel,
    PenAxis,
    PointerState,
    PointerType,
    Property,
    SizingMode,
    Slider,
    VBoxContainer,
    Vec3,
    WhiteNoise,
)
from simvx.core.audio_synth import AudioSource
from simvx.graphics import App

GRID = 8
VOICES = 16  # how many notes can ring at once
PANEL_WIDTH, MARGIN = 210, 10
DIM = (0.5, 0.5, 0.6, 1.0)

PAD_KEYS = [  # bottom row first
    [Key.Z, Key.X, Key.C, Key.V, Key.B, Key.N, Key.M, Key.COMMA],
    [Key.A, Key.S, Key.D, Key.F, Key.G, Key.H, Key.J, Key.K],
    [Key.Q, Key.W, Key.E, Key.R, Key.T, Key.Y, Key.U, Key.I],
    [Key.KEY_1, Key.KEY_2, Key.KEY_3, Key.KEY_4, Key.KEY_5, Key.KEY_6, Key.KEY_7, Key.KEY_8],
]
INSTRUMENT_KEYS = [Key.F1, Key.F2, Key.F3, Key.F4, Key.F5, Key.F6]


class Scale(StrEnum):
    CHROMATIC = "Chromatic"
    MAJOR = "Major"
    MINOR = "Minor"
    PENTATONIC = "Pentatonic"
    BLUES = "Blues"


SCALE_STEPS = {
    Scale.CHROMATIC: range(12),
    Scale.MAJOR: (0, 2, 4, 5, 7, 9, 11),
    Scale.MINOR: (0, 2, 3, 5, 7, 8, 10),
    Scale.PENTATONIC: (0, 3, 5, 7, 10),
    Scale.BLUES: (0, 3, 5, 6, 7, 10),
}


class Instrument(StrEnum):
    BELLS = "Bells"
    PAD = "Pad"
    PLUCK = "Pluck"
    SYNTH = "Synth"
    GLASS = "Glass"
    PERC = "Perc"


# The colour of the first pad and of the last, per instrument; the grid blends between them.
PALETTES = {
    Instrument.BELLS: (Vec3(0.2, 0.5, 1.0), Vec3(0.6, 0.9, 1.0)),
    Instrument.PAD: (Vec3(0.2, 0.1, 0.5), Vec3(0.7, 0.3, 0.9)),
    Instrument.PLUCK: (Vec3(0.1, 0.5, 0.3), Vec3(0.4, 1.0, 0.6)),
    Instrument.SYNTH: (Vec3(0.6, 0.1, 0.4), Vec3(1.0, 0.4, 0.7)),
    Instrument.GLASS: (Vec3(0.3, 0.6, 0.7), Vec3(0.7, 1.0, 1.0)),
    Instrument.PERC: (Vec3(0.7, 0.2, 0.1), Vec3(1.0, 0.6, 0.2)),
}
# Long enough for the slowest partial to fade to near silence, so no note ends with a click.
SECONDS = {
    Instrument.BELLS: 1.0,
    Instrument.PAD: 1.5,
    Instrument.PLUCK: 0.8,
    Instrument.SYNTH: 2.0,
    Instrument.GLASS: 2.5,
    Instrument.PERC: 0.5,
}


class VelocityMode(StrEnum):
    FIXED = "Fixed"
    WOBBLE = "Wobble"


class Mode(StrEnum):
    PERFORM = "Perform"
    RECORD = "Record"
    REPLAY = "Replay"
    TRAIN = "Train"
    FOLLOW = "Follow"


MODE_COLOURS = {
    Mode.PERFORM: (0.3, 1.0, 0.5, 1.0),
    Mode.RECORD: (1.0, 0.3, 0.3, 1.0),
    Mode.REPLAY: (0.3, 0.6, 1.0, 1.0),
    Mode.TRAIN: (1.0, 0.8, 0.2, 1.0),
    Mode.FOLLOW: (1.0, 0.6, 0.2, 1.0),
}


def note_name(semitone: int) -> str:
    """C0 is semitone 0, so 57 is A4."""
    return f"{('C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B')[semitone % 12]}{semitone // 12}"


# Sound


class Pluck(AudioSource):
    """A Karplus-Strong string: a burst of soft noise circulating in a delay line that loses energy each lap."""

    def __init__(self, freq: float):
        self.freq = freq

    def render(self, cursor_samples: int, n_samples: int, sample_rate: int) -> np.ndarray:
        period = max(2, round(sample_rate / self.freq))
        string = np.random.default_rng(round(self.freq)).uniform(-1.0, 1.0, period)
        for _ in range(3):  # smooth the noise so the attack is soft
            string = (string + np.roll(string, 1)) / 2
        laps = []
        for _ in range(-(-(cursor_samples + n_samples) // period)):
            laps.append(string)
            string = 0.4975 * (string + np.roll(string, -1))  # average neighbours and damp
        return np.concatenate(laps)[cursor_samples : cursor_samples + n_samples].astype(np.float32)


@cache
def tone(instrument: Instrument, semitone: int) -> AudioClip:
    """One note of an instrument, baked the first time it is asked for."""
    freq = 440.0 * 2 ** ((semitone - 57) / 12)
    duration = SECONDS[instrument]
    synth = AudioSynth()

    def fading(rate: float) -> Exponential:
        return Exponential(end=math.exp(-rate * duration))  # exp(-rate * t) over the clip

    def sine(ratio: float, gain: float, envelope) -> None:
        synth.add(Oscillator.sine(freq * ratio), envelope=envelope, gain=gain)

    match instrument:
        case Instrument.BELLS:  # a music box: quick-fading overtones and a slow chorus beat
            for ratio, gain, rate in ((1, 0.2, 5), (2, 0.03, 8), (3, 0.016, 12), (1.002, 0.024, 5)):
                sine(ratio, gain, fading(rate))
        case Instrument.PAD:  # a held chord of soft harmonics that swells in and out
            swell = ADSR(attack=0.08, decay=0.0, sustain=1.0, release=0.2)
            for ratio, gain in ((1, 0.16), (2, 0.05), (3, 0.016), (1.003, 0.024)):
                sine(ratio, gain, swell)
        case Instrument.PLUCK:
            synth.add(Pluck(freq), envelope=ADSR(attack=0.003, decay=0.0, release=0.03), gain=0.3)
        case Instrument.SYNTH:  # odd harmonics make a soft square wave; a detuned voice widens it
            for ratio, gain in ((1, 0.14), (3, 0.035), (5, 0.014), (1.005, 0.07)):
                sine(ratio, gain, fading(2.5))
        case Instrument.GLASS:  # two nearly equal sines beat against each other and shimmer
            sine(1, 0.15, fading(2))
            sine(1.004, 0.1, fading(2))
        case Instrument.PERC:  # a thud, a click an octave and a fifth up, and a breath of noise
            sine(1, 0.25, fading(10))
            sine(3, 0.1, fading(40))
            synth.add(WhiteNoise(seed=semitone), envelope=fading(300), filter=LowPass(2000), gain=0.15)
    return synth.bake(duration, channels=1)


@dataclass
class Voice:
    player: AudioPlayer
    ends: float = 0.0  # tree time at which its note has faded out
    pad: int = -1  # the pad whose note it is playing


# Recording


class Note(NamedTuple):
    time: float  # seconds from the start of the recording, at the recorded tempo
    pad: int
    velocity: float
    instrument: Instrument


@dataclass
class Phrase:
    """A recorded run of pad presses that can be replayed, looped and practised."""

    notes: list[Note] = field(default_factory=list)
    bpm: float = 120.0
    loop: bool = False
    quantize: bool = False
    playing: bool = False
    recorded_bpm: float = 120.0
    started: float = 0.0
    clock: float = 0.0
    cursor: int = 0  # the next note to replay
    target: int = 0  # the next note to practise

    @property
    def length(self) -> float:
        return self.notes[-1].time + 0.5 if self.notes else 0.0

    @property
    def progress(self) -> float:
        if not self.notes:
            return 0.0
        return self.clock / self.length if self.playing else self.target / len(self.notes)

    def record(self, now: float) -> None:
        self.notes.clear()
        self.recorded_bpm, self.started = self.bpm, now

    def add(self, now: float, pad: int, velocity: float, instrument: Instrument) -> None:
        t = now - self.started
        if self.quantize:
            sixteenth = 15.0 / self.bpm
            t = round(t / sixteenth) * sixteenth
        self.notes.append(Note(t, pad, velocity, instrument))

    def play(self) -> None:
        self.playing, self.clock, self.cursor, self.target = bool(self.notes), 0.0, 0, 0

    def advance(self, dt: float) -> list[Note]:
        """Move the playhead on, retimed by the tempo, and return the notes it passed."""
        if not self.playing:
            return []
        self.clock += dt * self.bpm / self.recorded_bpm
        due = self._take_due()
        if self.clock >= self.length:
            if self.loop:
                self.clock -= self.length
                self.cursor = 0
                due += self._take_due()
            else:
                self.playing = False
        return due

    def _take_due(self) -> list[Note]:
        end = bisect_right(self.notes, self.clock, key=attrgetter("time"))
        due, self.cursor = self.notes[self.cursor : end], end
        return due

    def next_target(self) -> Note | None:
        return self.notes[self.target] if self.notes else None

    def hit_target(self) -> None:
        self.target = (self.target + 1) % len(self.notes)


@dataclass
class PadState:
    pressed: bool = False
    brightness: float = 0.0  # 0 idle, 1 fully lit
    velocity: float = 0.0
    pressed_at: float = -1.0
    release_at: float = 0.0  # a replayed press lets itself go at this time; 0 for a held one
    target: bool = False


class PadGrid(Node):
    """An 8x8 synth pad instrument with a control panel on the right."""

    dynamic = True  # breathing pads, sparks and ripples animate every frame

    input_context = {
        **{f"pad_{row * GRID + col}": [key] for row, keys in enumerate(PAD_KEYS) for col, key in enumerate(keys)},
        **{f"instrument_{i}": [key] for i, key in enumerate(INSTRUMENT_KEYS)},
        "octave_up": [Key.PAGE_UP],
        "octave_down": [Key.PAGE_DOWN],
    }

    instrument = Property(Instrument.BELLS, on_change="_show_settings")
    scale = Property(Scale.PENTATONIC, on_change="_show_settings")
    octave_offset = Property(-1, range=(-3, 3), on_change="_show_settings")
    master_volume = Property(0.0, range=(-40.0, 12.0), hint="Master volume dB")
    velocity_mode = Property(VelocityMode.WOBBLE)
    retrigger = Property(False, hint="Layer a repeated pad's notes instead of cutting the last")

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.pads = [PadState() for _ in range(GRID * GRID)]
        self.phrase = Phrase()
        self.mode = Mode.PERFORM
        self.voices = [Voice(self.add_child(AudioPlayer())) for _ in range(VOICES)]
        self.mouse_motion = deque(maxlen=30)  # how far the mouse moved in each recent frame
        self.last_mouse = (0.0, 0.0)
        self.held = {}  # pointer id -> the pad it is holding down
        self._build_panel()

    def on_ready(self):
        for semitone in (60, 64, 67):  # a C major chime says the audio works
            self._sound(Instrument.BELLS, semitone, 0.5)

    # Notes

    def semitone(self, pad: int) -> int:
        """Columns step through the scale, spilling into the next octave; rows climb an octave each."""
        row, col = divmod(pad, GRID)
        steps = SCALE_STEPS[self.scale]
        octave, step = divmod(col, len(steps))
        return 36 + (self.octave_offset + row + octave) * 12 + steps[step]

    def _sound(self, instrument: Instrument, semitone: int, velocity: float, pad: int = -1) -> None:
        clip = tone(instrument, semitone)
        now = self.tree.now
        voice = min(self.voices, key=attrgetter("ends"))  # a silent one if any, else the nearest to silence
        voice.player.stop()
        voice.player.stream = clip
        voice.player.volume_db = self.master_volume + 20 * math.log10(max(0.01, velocity))
        voice.player.play()
        voice.ends, voice.pad = now + clip.duration, pad

    def _silence(self, pad: int) -> None:
        for voice in self.voices:
            if voice.pad == pad:
                voice.pad = -1
                if voice.player.is_playing():
                    voice.player.fade_out(0.08)

    def press(self, pad: int, velocity: float, *, replayed: bool = False, instrument: Instrument | None = None):
        """Play a pad; in Train and Follow only the phrase's next note counts."""
        state = self.pads[pad]
        target = self.phrase.next_target() if self.mode in (Mode.TRAIN, Mode.FOLLOW) and not replayed else None
        if target:
            if pad != target.pad:
                if self.mode is Mode.FOLLOW:
                    state.brightness = 0.5  # a dim flash and no sound marks a wrong pad
                return
            velocity = target.velocity
            self.phrase.hit_target()
            self._show_target()
        state.pressed, state.velocity, state.pressed_at = True, velocity, self.tree.now
        state.release_at = self.tree.now + 0.15 if replayed else 0.0
        if not self.retrigger:
            self._silence(pad)
        self._sound(instrument or self.instrument, self.semitone(pad), velocity, pad)
        if self.mode is Mode.RECORD and not replayed:
            self.phrase.add(self.tree.now, pad, velocity, self.instrument)

    def release(self, pad: int) -> None:
        self.pads[pad].pressed = False
        self.pads[pad].release_at = 0.0
        if self.instrument is Instrument.PAD:  # the other instruments ring out on their own
            self._silence(pad)

    def _velocity(self, pointer: PointerState | None = None) -> float:
        """How hard a pad was struck: measured pressure where the hardware has it, else the panel's mode."""
        caps = Input.capabilities
        if pointer is not None and (
            (pointer.pointer_type is PointerType.TOUCH and caps.touch_pressure)
            or (pointer.pointer_type is PointerType.PEN and PenAxis.PRESSURE in caps.pen_axes)
        ):
            return min(1.0, max(0.2, pointer.pressure))
        if self.velocity_mode is VelocityMode.FIXED:
            return 0.8
        if pointer is None:
            return 0.7  # a key has no wobble
        return max(0.15, min(1.0, sum(self.mouse_motion) / 50.0))

    # Modes

    def set_mode(self, mode: Mode) -> None:
        self.mode = mode
        self.phrase.playing = False
        match mode:
            case Mode.RECORD:
                self.phrase.record(self.tree.now)
            case Mode.REPLAY | Mode.FOLLOW:
                self.phrase.play()
            case Mode.TRAIN:
                self.phrase.target = 0
        self._show_target()
        self.mode_buttons[mode].checked = True
        self.mode_label.text = mode.upper()
        self.mode_label.text_colour = MODE_COLOURS[mode]

    def _show_target(self) -> None:
        for state in self.pads:
            state.target = False
        target = self.phrase.next_target()
        if target and self.mode in (Mode.TRAIN, Mode.FOLLOW):
            self.pads[target.pad].target = True

    def select_instrument(self, instrument: Instrument) -> None:
        self.instrument = instrument
        self.instrument_buttons[instrument].checked = True

    # Frame

    def on_update(self, dt: float):
        now = self.tree.now
        mouse = Input.mouse_position
        self.mouse_motion.append(math.dist(mouse, self.last_mouse))
        self.last_mouse = mouse

        if Input.just_pressed("octave_up"):
            self.octave_offset += 1
        if Input.just_pressed("octave_down"):
            self.octave_offset -= 1
        for i, instrument in enumerate(Instrument):
            if Input.just_pressed(f"instrument_{i}"):
                self.select_instrument(instrument)
        for pad in range(len(PAD_KEYS) * GRID):
            if Input.just_pressed(f"pad_{pad}"):
                self.press(pad, self._velocity())
            if Input.just_released(f"pad_{pad}"):
                self.release(pad)

        # Every pointer is its own voice. A drag onto a new pad lets the old one go.
        for pid, pointer in Input.pointers.items():
            pad = self.pad_at(pointer.position)
            if pointer.just_pressed and pad is not None:
                self.press(pad, self._velocity(pointer))
                self.held[pid] = pad
            elif pointer.contact and pid in self.held and pad is not None and pad != self.held[pid]:
                self.release(self.held[pid])
                self.press(pad, self._velocity(pointer))
                self.held[pid] = pad
            if pointer.just_released and pid in self.held:
                self.release(self.held.pop(pid))

        for note in self.phrase.advance(dt):
            if self.mode is Mode.REPLAY:
                self.press(note.pad, note.velocity, replayed=True, instrument=note.instrument)
            else:  # Follow lights the note and leaves playing it to you
                self.pads[note.pad].target = True

        for pad, state in enumerate(self.pads):
            if state.release_at and now >= state.release_at:
                self.release(pad)
            rate = 12.0 if state.pressed else -4.0
            state.brightness = min(1.0, max(0.0, state.brightness + dt * rate))

        count = len(self.phrase.notes)
        match self.mode:
            case Mode.RECORD:
                self.progress_label.text = f"Recording: {count} notes{' [Q]' if self.phrase.quantize else ''}"
            case Mode.PERFORM:
                self.progress_label.text = ""
            case _:
                loop = " [LOOP]" if self.phrase.loop else ""
                self.progress_label.text = f"{self.phrase.progress:.0%} ({count} notes){loop}"

    # Layout

    def grid_rect(self) -> tuple[float, float, float]:
        """The grid's top-left corner and the size of one cell, fitted beside the panel."""
        width, height = self.viewport_size
        area_w, area_h = width - PANEL_WIDTH - 3 * MARGIN, height - 2 * MARGIN
        cell = min(area_w, area_h) / GRID
        return MARGIN + (area_w - cell * GRID) / 2, (height - cell * GRID) / 2, cell

    def pad_rect(self, pad: int) -> tuple[float, float, float]:
        """A pad's top-left corner and side, row 0 at the bottom."""
        left, top, cell = self.grid_rect()
        row, col = divmod(pad, GRID)
        gap = max(2.0, cell * 0.08)
        return left + col * cell + gap / 2, top + (GRID - 1 - row) * cell + gap / 2, cell - gap

    def pad_at(self, point) -> int | None:
        left, top, cell = self.grid_rect()
        col, row = int((point[0] - left) // cell), GRID - 1 - int((point[1] - top) // cell)
        return row * GRID + col if 0 <= col < GRID and 0 <= row < GRID else None

    def pad_colour(self, pad: int) -> Vec3:
        low, high = PALETTES[self.instrument]
        return low.lerp(high, pad / (GRID * GRID - 1))

    # Drawing

    def on_draw(self, renderer):
        now = self.tree.now
        for pad, state in enumerate(self.pads):
            x, y, side = self.pad_rect(pad)
            centre = (x + side / 2, y + side / 2)
            base = self.pad_colour(pad)
            glow = 0.25 + 0.03 * math.sin(now * 1.5 + pad * 0.3)  # a slow idle breath
            if state.target:
                glow = max(glow, 0.55 + 0.15 * math.sin(now * 6.0))
            r, g, b = np.minimum(1.0, base * (glow + state.brightness * (0.75 + 0.25 * state.velocity)))
            radius = min(max(2.0, side * 0.08), side / 2)
            rounded_rect(renderer, x, y, side, radius, (r, g, b, 1.0))
            if side > 10:  # a bevel: lit top edge, shaded bottom edge
                renderer.rect((x + radius, y), (side - 2 * radius, 2), fill=(r + 0.15, g + 0.15, b + 0.15, 0.4))
                renderer.rect((x + radius, y + side - 2), (side - 2 * radius, 2), fill=(r * 0.3, g * 0.3, b * 0.3, 0.5))
            if state.brightness > 0.05:
                halo = (r, g, b, 0.2 * state.brightness * state.velocity)
                renderer.circle(centre, side * 0.7 * state.brightness, fill=halo, segments=16)

            age = now - state.pressed_at
            if age < 0.3 and state.velocity > 0.1:
                draw_sparks(renderer, centre, age / 0.3, state, base)
            if age < 0.4:  # a ripple ring spreading from the pad
                ring = (*base, 0.3 * (1.0 - age / 0.4) * state.velocity)
                renderer.circle(centre, side * (0.5 + 1.5 * age / 0.4), stroke=ring, width=2.0, segments=20)
            if side > 30:
                label_colour = (1.0, 1.0, 1.0, 0.4 + 0.6 * state.brightness)
                renderer.text(
                    note_name(self.semitone(pad)),
                    rect=(x, y, side, side - 2),
                    align="centre",
                    valign="bottom",
                    fill=label_colour,
                    scale=max(0.5, min(1.0, side / 80)),
                )

        if self.phrase.playing:  # the playhead, under the grid
            left, top, cell = self.grid_rect()
            bar = (0.3, 0.7, 1.0, 0.8)
            renderer.rect((left, top + cell * GRID + 4), (cell * GRID * self.phrase.progress, 3), fill=bar)

    # Panel

    def _build_panel(self) -> None:
        panel = self.add_child(Panel(anchor=Anchor.RIGHT_WIDE, inset=MARGIN, size=(PANEL_WIDTH, 0)))
        panel.bg_colour = (0.08, 0.08, 0.10, 0.92)
        panel.border_colour = (0.2, 0.2, 0.25, 1.0)
        box = panel.add_child(VBoxContainer(anchor=Anchor.FULL_RECT, inset=10, separation=8))

        title = box.add_child(Label("PAD GRID", font_size=18.0, alignment="centre"))
        title.text_colour = (0.8, 0.9, 1.0, 1.0)

        box.add_child(caption("INSTRUMENT"))
        instruments = ButtonGroup()
        self.instrument_buttons = {}
        for instrument in Instrument:
            button = Button(
                instrument[:3], lambda i=instrument: self.select_instrument(i), group=instruments, font_size=10.0
            )
            low, _ = PALETTES[instrument]
            button.bg_colour = (*low, 0.5)
            button.hover_colour = (*low, 0.8)
            button.checked_colour = (*low, 1.0)
            self.instrument_buttons[instrument] = button
        box.add_child(button_row(*self.instrument_buttons.values()))
        self.instrument_buttons[self.instrument].checked = True

        box.add_child(caption("SCALE"))
        scales = box.add_child(DropDown(items=list(Scale), selected_index=list(Scale).index(self.scale), font_size=11))
        scales.item_selected.connect(lambda i: setattr(self, "scale", list(Scale)[i]))

        box.add_child(caption("VOLUME"))
        volume = box.add_child(Slider(-40, 12, value=self.master_volume))
        volume.value_changed.connect(lambda db: setattr(self, "master_volume", db))

        box.add_child(caption("VELOCITY"))
        velocities = ButtonGroup()
        velocity_buttons = []
        for mode in VelocityMode:
            button = Button(mode, lambda m=mode: setattr(self, "velocity_mode", m), group=velocities, font_size=10.0)
            button.checked = mode is self.velocity_mode
            velocity_buttons.append(button)
        box.add_child(button_row(*velocity_buttons))

        box.add_child(caption("MODE"))
        modes = ButtonGroup()
        self.mode_buttons = {m: Button(m, lambda m=m: self.set_mode(m), group=modes, font_size=10.0) for m in Mode}
        buttons = list(self.mode_buttons.values())
        box.add_child(button_row(*buttons[:3]))
        box.add_child(button_row(*buttons[3:]))

        toggles = {"Loop": (self.phrase, "loop"), "Quant": (self.phrase, "quantize"), "Retrig": (self, "retrigger")}
        row = []
        for text, (target, attr) in toggles.items():
            button = Button(text, toggle_mode=True, font_size=10.0)
            button.toggled.connect(lambda on, target=target, attr=attr: setattr(target, attr, on))
            row.append(button)
        box.add_child(button_row(*row))

        tempo = box.add_child(HBoxContainer(separation=5, size=(0, 26)))
        tempo.add_child(caption("BPM"))
        bpm = tempo.add_child(Slider(60, 200, value=self.phrase.bpm, size=(150, 22)))
        bpm.value_changed.connect(lambda value: setattr(self.phrase, "bpm", value))

        self.mode_label = box.add_child(Label("", font_size=14.0, alignment="centre"))
        self.settings_label = box.add_child(Label("", font_size=10.0, alignment="centre"))
        self.progress_label = box.add_child(Label("", font_size=10.0, alignment="centre"))
        for label in (self.settings_label, self.progress_label):
            label.text_colour = DIM
        box.add_child(
            button_row(
                Button("OCT -", lambda: setattr(self, "octave_offset", self.octave_offset - 1), font_size=10.0),
                Button("OCT +", lambda: setattr(self, "octave_offset", self.octave_offset + 1), font_size=10.0),
            )
        )
        self.set_mode(Mode.PERFORM)
        self._show_settings()

        # Example help overlay: not part of the technique shown.
        hint = Label("Z-8 rows: play pads\nPgUp/PgDn: octave\nF1-F6: instrument", font_size=9.0, alignment="centre")
        hint.text_colour = (0.45, 0.45, 0.55, 1.0)
        box.add_child(hint)

    def _show_settings(self) -> None:
        lowest = note_name(36 + self.octave_offset * 12)
        self.settings_label.text = f"{self.instrument} | {self.scale} | from {lowest}"


def caption(text: str) -> Label:
    label = Label(text, font_size=10.0)
    label.text_colour = DIM
    return label


def button_row(*buttons: Button) -> HBoxContainer:
    """A full-width row that shares its width evenly between the buttons."""
    row = HBoxContainer(separation=3, size=(0, 26))
    row.sizing = SizingMode.FILL
    for button in buttons:
        row.add_child(button)
    return row


def rounded_rect(renderer, x: float, y: float, side: float, radius: float, colour) -> None:
    """A square with rounded corners: a cross of two rects and a disc in each corner.

    The 2D renderer's rect() has no corner radius, so the shape is assembled from primitives.
    """
    renderer.rect((x + radius, y), (side - 2 * radius, side), fill=colour)
    renderer.rect((x, y + radius), (side, side - 2 * radius), fill=colour)
    for cx in (x + radius, x + side - radius):
        for cy in (y + radius, y + side - radius):
            renderer.circle((cx, cy), radius, fill=colour, segments=12)


def draw_sparks(renderer, centre, t: float, state: PadState, base: Vec3) -> None:
    """A ring of sparks flying out from a struck pad, more and further for a harder strike."""
    count = int(6 + 8 * state.velocity)
    distance = 8 + 40 * t * (0.5 + 0.5 * state.velocity)
    colour = (*np.minimum(1.0, base + 0.3), max(0.0, 1.0 - t * 1.2))
    size = max(1.0, 3.0 * (1.0 - t) * state.velocity)
    for j in range(count):
        angle = j / count * math.tau + state.pressed_at * 5
        spark = (centre[0] + math.cos(angle) * distance, centre[1] + math.sin(angle) * distance)
        renderer.circle(spark, size, fill=colour, segments=6)


if __name__ == "__main__":
    App(width=1280, height=720, title="SimVX Pad Grid").run(PadGrid())