ba752745b7
- Each meter lane has an 'enable' checkbox right after its number (default on, green-dim row when off); replaces the right-side 'mute'. Renamed mute→enabled throughout (scheduler, snapshot, share '!' flag, 1–9 keys, now-playing). Old saved data still loads (back-compat). - Features area redesigned into highlighting boxes (Gap trainer / Tempo ramp / Timers); trainer & ramp boxes light up + un-dim when enabled. - Set list 'Continue' mode: per-item countdown (saved in each item, 'cd' token), and when a playing item's countdown hits 0 it auto-loads the next — so a list with countdowns plays straight through. - Removed the in-app QR (vendored qrcode.js); 'QR ↗' now opens api.qrserver.com with the link, behind a banner warning it's a third party (verify it decodes). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
137 lines
5.1 KiB
Markdown
137 lines
5.1 KiB
Markdown
# Stackable Metronome
|
||
|
||
A browser **polymetric groove trainer / metronome** — and the design mockup for a
|
||
Raspberry Pi Pico hardware build. Stack as many "meter lanes" as you like; each is
|
||
its own little metronome with a grouping, subdivision, drum voice and per-beat
|
||
pattern. Layering lanes produces polymeter and true ratio polyrhythm.
|
||
|
||
**Live:** https://metronome.varasys.io
|
||
|
||
It's a single page (`index.html`) plus a vendored QR library — no build step,
|
||
no framework. State (presets, set lists, practice log, theme) lives in
|
||
`localStorage`.
|
||
|
||
## Features
|
||
|
||
- **Meter lanes** — grouping (odd meters), subdivision, GM drum voice, per‑beat
|
||
on/off pattern (rests), mute, live measure counter.
|
||
- **Polyrhythm** — a per‑lane *poly* toggle fits a lane's beats evenly into lane 1's
|
||
bar (e.g. 5‑over‑4, 3‑over‑2).
|
||
- **Practice** — gap/mute trainer (play N / mute M bars) and a tempo ramp with a
|
||
start BPM and signed step.
|
||
- **Set lists** — named, ordered lists of saved setups; ▶ loads + starts an item,
|
||
**N** advances; each play is logged for cross‑day comparison.
|
||
- **Sharing** — copy a link (with QR) to your current settings or a whole set list.
|
||
- **Theming** — System / Light / Dark.
|
||
|
||
## The share language
|
||
|
||
A compact, human‑readable text encodes a full configuration (a *patch*). It's what
|
||
goes in a share link, and you can hand‑write or edit it.
|
||
|
||
### Patch grammar
|
||
|
||
```
|
||
v1 ; t<bpm> [; vol<pct>] ; <lane> ; <lane> … [; tr<play>/<mute>] [; rmp<start>/<step>/<every>]
|
||
```
|
||
|
||
| Token | Meaning | Example |
|
||
|-------|---------|---------|
|
||
| `v1` | format version (always first) | `v1` |
|
||
| `t<bpm>` | tempo | `t120` |
|
||
| `vol<pct>` | master volume 0–100 | `vol70` |
|
||
| `tr<play>/<mute>` | gap trainer: play N bars, mute M | `tr2/2` |
|
||
| `rmp<start>/<step>/<every>` | tempo ramp: start BPM, ±step, every N bars | `rmp80/5/4` |
|
||
| `<lane>` | a meter lane (see below) | `kick:4` |
|
||
|
||
Tokens are joined with `;`. `tr` and `rmp` are omitted when off.
|
||
|
||
### Lane grammar
|
||
|
||
```
|
||
<sound> : <grouping> [ / <sub> ] [ = <pattern> ] [ ~ ] [ ! ]
|
||
```
|
||
|
||
- **sound** — one of:
|
||
`beep`, `kick`, `snare`, `rim`, `clap`, `hatClosed`, `hatOpen`, `ride`, `crash`,
|
||
`tomLow`, `tomMid`, `tomHigh`, `tambourine`, `cowbell`, `woodblock`, `claves`,
|
||
`jamblock` (unknown → `beep`).
|
||
- **grouping** — beats per bar, optionally grouped for odd meters: `4`, `3`,
|
||
`2+2+3`. The first beat of each group is accented.
|
||
- **`/sub`** — subdivision (clicks per beat): `1` quarter (default), `2` eighth,
|
||
`3` triplet, `4` sixteenth, `6` sextuplet. Omit for quarter.
|
||
- **`=pattern`** — per‑beat on/off as `x`/`.`, length = beats per bar. Omit = all on.
|
||
e.g. `=.x.x` puts a backbeat on 2 & 4.
|
||
- **`~`** — polyrhythm: fit this lane's beats evenly into **lane 1's** bar.
|
||
- **`!`** — mute the lane.
|
||
|
||
### Examples
|
||
|
||
| Patch / lane | What it is |
|
||
|---|---|
|
||
| `kick:4` | kick on 4 quarter beats |
|
||
| `snare:4=.x.x` | snare backbeat (2 & 4) |
|
||
| `hatClosed:4/2` | eighth‑note hi‑hats |
|
||
| `claves:5~` | 5 evenly across lane 1's bar (5‑over‑4 if lane 1 is `4`) |
|
||
| `kick:2+2+3=x..x..x` | 7/8, kick on each group start |
|
||
| `cowbell:3+2/2` | 5/4 grouped 3+2, eighth subdivision |
|
||
| **Full:** `v1;t120;kick:4;snare:4=.x.x;hatClosed:4/2;tr2/2` | backbeat groove with gap trainer |
|
||
|
||
### In URLs
|
||
|
||
- **Settings:** `…/#p=<patch>` — readable, e.g.
|
||
`…/#p=v1;t120;kick:4;claves:5~`
|
||
- **Set list:** `…/#sl=<base64url>` — a JSON `{title, description, items[]}` where
|
||
each item's config is a patch string. Used because titles/notes are free text.
|
||
|
||
Opening such a link applies the settings (or imports the set list) on load, then
|
||
clears the hash so a refresh won't re‑import.
|
||
|
||
## Sharing
|
||
|
||
In the set‑list panel's **⋯** menu:
|
||
- **Share settings link** / **Share set‑list link** open a dialog with the link to
|
||
**Copy** or **Open**.
|
||
- **QR ↗** opens a third‑party QR service (api.qrserver.com) with the link in its
|
||
URL so you can scan it on a phone. A banner warns you it's external — confirm the
|
||
QR decodes to the shown link before trusting it. (No QR is generated locally.)
|
||
- **Export all / Import file** back up presets + set lists + logs as a JSON file.
|
||
|
||
## Keyboard shortcuts
|
||
|
||
| Key | Action |
|
||
|-----|--------|
|
||
| `Space` | start / stop |
|
||
| `T` | tap tempo |
|
||
| `↑` / `↓` | tempo ±1 (`Shift` = ±10) |
|
||
| `A` | add meter lane |
|
||
| `1`–`9` | mute lane N |
|
||
| `R` | toggle the set‑list panel |
|
||
| `N` | next set‑list item |
|
||
| `?` | shortcuts help |
|
||
| `Esc` | close dialog / panel |
|
||
|
||
## Versioning
|
||
|
||
`VERSION` holds the formal version. `deploy.sh` stamps the served page:
|
||
|
||
- **Formal** — a clean commit tagged `v<VERSION>` → `X.Y.Z`.
|
||
- **Dev** — anything else → `X.Y.Z-dev.<utc-timestamp>.<short-sha>[.dirty]`.
|
||
|
||
Cut a release with `./release.sh [X.Y.Z]` (bumps `VERSION` + tags `v<VERSION>`),
|
||
then push the tag and deploy.
|
||
|
||
## Deploy
|
||
|
||
`./deploy.sh` copies `index.html` (version‑stamped) into the Caddy
|
||
web root and smoke‑tests the live URL. No restart needed (`file_server` picks up
|
||
changes immediately).
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `index.html` | the whole app |
|
||
| `deploy.sh` | publish to the Caddy web root |
|
||
| `release.sh` | tag a formal version |
|
||
| `VERSION` | formal version string |
|