From 5fc962f0c4dfc8462d4424ad861d0b14b7a52318 Mon Sep 17 00:00:00 2001 From: Me Here Date: Thu, 28 May 2026 21:01:40 -0500 Subject: [PATCH] Phase 0: refresh README to current state; add 'kit' embed variant README was stale (pre-dating several shipped changes). Rewrite it to match reality: - voices are all synthesized now (KIT_ALIAS -> 808/909); drop the VCSL samples narrative, the @BUILD:samples wording, and the sample credits. - document the lean-widget + separate info-.html page model (was 'Open=Info'). - add kit.html + all info-*.html to the Pages table; add the new src/ partials (header/footer/chrome/progbox/infoembed), pico/ firmware, and pico-main.py to Files/Build. - document the share-grammar additions: GM note numbers, Euclidean (k,n[,rot]), per-lane @ gain. - add a 'Build it (hardware)' section for the PM_K-1 Kit + MicroPython firmware. embed.js: add the 'kit' form factor to the variant map (it previously fell back to micro), so data-varasys-metronome="kit" embeds kit.html as the README now documents. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 228 +++++++++++++++++++++++++++++------------------------- embed.js | 4 +- 2 files changed, 124 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 1bafbe7..17950d1 100644 --- a/README.md +++ b/README.md @@ -5,64 +5,76 @@ A landing page is the front door; the main app is the **PM_E‑1 PolyMeter Edito web app where you stack as many "meter lanes" as you like, each its own little metronome with a grouping, subdivision, drum voice and a per‑step pattern with accents. Layering lanes produces polymeter and true ratio polyrhythm. The same engine drives an ever‑expanding library -of **form‑factor concepts** (idealized and buildable hardware mockups) and ships as an -**embeddable widget** anyone can drop into their own page. +of **form‑factor concepts** (idealized and buildable hardware mockups), ships as an +**embeddable widget** anyone can drop into their own page, and even runs as **firmware** on a +real Raspberry Pi Pico build (the **PM_K‑1 Kit**). **Live:** https://metronome.varasys.io · **Source:** https://codeberg.org/VARASYS/metronome Every **deployed page is a single, self‑contained `.html` file** — **zero dependencies**: no framework, no CDN libraries, nothing fetched at runtime. They're assembled by a small build step (`build.sh`) that inlines a shared engine, the seed set lists, base styling and -the audio samples + brand assets (kept in `assets/`) into each page, so the sources stay lean. -State (set lists, the practice log, theme and UI preferences) lives in `localStorage`. +the brand assets (kept in `assets/`) into each page, so the sources stay lean. Every voice is +**synthesized** in Web Audio — there are no audio samples to load. State (set lists, the +practice log, theme and UI preferences) lives in `localStorage`. ## Pages +The site is **one editor + a gallery of form factors**, and each form factor is split into a +**lean widget page** and a **separate info page**: + +- **`.html`** — just the live widget (front view, controls, program box). This is what + `?embed=1` serves and what the landing embeds; it never ships the BOM/narrative. +- **`info-.html`** — the spec page: it embeds the live widget at the top, then the + description, dimensioned drawings and a priced **Bill of Materials** (for the buildable hardware). + | URL | What | |-----|------| -| [`/`](https://metronome.varasys.io/) `index.html` | **Concepts** — the landing / form‑factor gallery; each box embeds the live widget | -| `/editor.html` | **PM_E‑1 — PolyMeter Editor** (the main app) | -| `/player.html` | **PM_C‑1 Concept** — idealized concept device (full display + set‑list nav, theme, fullscreen "stage" view) | -| `/teacher.html` | **PM_T‑1 Teacher** — studio / lesson console (colour TFT, arcade buttons, 1/4″ instrument pass‑through with analog click injection) | -| `/stage.html` | **PM_S‑1 Stage** — foot‑pedal stompbox (two footswitches, expression‑pedal in, RGB beat light, instrument pass‑through) | -| `/micro.html` | **PM_P‑1 Practice** — inline practice bar (instrument in / out pass‑through, clickable thumb‑roller, 14‑segment display) | -| `/showcase.html` | **PM_D‑1 Display** — pyramid display piece; the pendulum is an RGB light bar combining every lane's subdivisions/accents | +| [`/`](https://metronome.varasys.io/) `index.html` | **Concepts** — the landing / form‑factor gallery; each box embeds the live widget (Open ↗ / Specs & info ⓘ) | +| `/editor.html` · `/info-editor.html` | **PM_E‑1 — PolyMeter Editor** (the main app) + its overview | +| `/kit.html` · `/info-kit.html` | **PM_K‑1 Kit** — buildable Raspberry Pi Pico touchscreen unit (52Pi EP‑0172); info page has the wiring, parts and firmware | +| `/player.html` · `/info-player.html` | **PM_C‑1 Concept** — idealized concept device (full display + set‑list nav, theme, fullscreen "stage" view) | +| `/teacher.html` · `/info-teacher.html` | **PM_T‑1 Teacher** — studio / lesson console (colour TFT, arcade buttons, 1/4″ instrument pass‑through with analog click injection) | +| `/stage.html` · `/info-stage.html` | **PM_S‑1 Stage** — foot‑pedal stompbox (two footswitches, expression‑pedal in, RGB beat light, instrument pass‑through) | +| `/micro.html` · `/info-micro.html` | **PM_P‑1 Practice** — inline practice bar (instrument in / out pass‑through, clickable thumb‑roller, 14‑segment display) | +| `/showcase.html` · `/info-showcase.html` | **PM_D‑1 Display** — pyramid display piece; the pendulum is an RGB light bar combining every lane's subdivisions/accents | | `/embed.html` · `/embed.js` | embed docs and the drop‑in loader | +| `/pico-main.py` | the PM_K‑1 MicroPython firmware (download) | -Each form‑factor page is self‑contained ("Open" = "Info"): a more‑detailed description, -the live device with front + top/side dimensioned views and loading instructions, and an -expandable **Spec & BOM** (priced, for the buildable hardware). The buildable units are the -Teacher, Stage, Micro and Showcase; the Editor (web app) and Initial (concept) have no BOM. +The buildable units (Teacher, Stage, Practice, Display, Kit) carry a priced BOM on their info +page; the Editor (web app) and Concept have none. Every page shares the same VARASYS header +(official logo with baked‑in tagline, nav, theme toggle). The editor also shows a subtle live +**program string** of what's loaded — editable, with copy/paste — under the app (press `Enter` +or paste to apply; see [the share language](#the-share-language)). -Each page carries the same VARASYS header (logo + tagline, nav, theme toggle). The editor -also shows a subtle live **program string** of what's loaded — editable, with copy/paste — -under the app (press `Enter` or paste to apply; see [the share language](#the-share-language)). - -Because nothing loads from the network, you can save the page (`Ctrl`/`⌘`+`S`) and -open it straight from disk to run fully offline. One catch from a local `file://`: -the browser may not persist `localStorage` between sessions, so use **Export all** -(set‑list **⋯** menu) to back up your work. +Because nothing loads from the network, you can save a page (`Ctrl`/`⌘`+`S`) and open it +straight from disk to run fully offline. One catch from a local `file://`: the browser may not +persist `localStorage` between sessions, so use **Export all** (set‑list **⋯** menu) to back up. ## Features - **Meter lanes** — grouping (odd meters), subdivision (incl. swing), a drum/percussion voice, per‑**step dynamics** (accent / normal / ghost / mute), mute, live measure counter. -- **Sounds** — a sampled acoustic kit plus synthesized **808 / 909** and electronic voices; - click each pad to set its dynamics; pick a *swing* subdivision for a triplet feel. +- **Sounds** — every voice is **synthesized** in Web Audio: a friendly drum kit + (`kick`, `snare`, `hatClosed`, …) rendered with the **808 / 909** voices, the 808/909 voices + by name, and electronic/percussion tones. No samples are loaded. +- **Per‑lane gain** — a dB trim knob per lane (`@` in the share language), applied at + schedule time so changing it never stutters playback. - **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). +- **Euclidean rhythms** — spread *k* hits evenly across *n* steps with `(k,n[,rot])`. - **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; **cue** across lists and commit - on a bar/beat boundary with no audible gap (see **Live performance**); each play is - logged for cross‑day comparison. + on a bar/beat boundary with no audible gap (see **Live performance**); each play is logged. - **Sharing** — copy a link 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. +goes in a share link, the editor's program box, and a device's program list. You can +hand‑write or edit it. ### Patch grammar @@ -86,29 +98,26 @@ Tokens are joined with `;`. `tr` and `rmp` are omitted when off. ### Lane grammar ``` - : [ / ] [ = ] [ ~ ] [ ! ] + : [ / ] [ (,[,]) ] [ = ] [ @ ] [ ~ ] [ ! ] ``` -- **sound** — the acoustic kit: `beep`, `kick`, `snare`, `rim`, `clap`, `hatClosed`, - `hatOpen`, `ride`, `crash`, `tomLow`, `tomMid`, `tomHigh`, `tambourine`, `cowbell`, - `woodblock`, `claves`, `jamblock` (kick, snare, closed‑hat, crash, toms, tambourine, - cowbell, woodblock and claves play embedded CC0 samples; `beep`, `clap`, `rim`, - `hatOpen` and `ride` stay synthesized — VCSL has no clean source for those); plus - synthesized drum machines — - `kick808 snare808 clap808 hat808 openHat808 cowbell808 tom808` and - `kick909 snare909 clap909 hat909 ride909 crash909`. Unknown → `beep`. -- **grouping** — beats per bar, optionally grouped for odd meters: `4`, `3`, - `2+2+3`. Groups get a visual divider; accents are per‑step (see `=pattern`). -- **`/sub`** — subdivision: `1` quarter (default), `2` eighth, `3` triplet, - `4` sixteenth, `6` sextuplet. This also sets how many **pads** each beat splits - into. Append **`s`** for **swing** on even subdivisions — `2s` (swung eighths) or - `4s` (swung sixteenths) delay the off‑beats to a triplet (2:1) feel. Omit for quarter. -- **`=pattern`** — per‑**step dynamics**, one char per pad: **`X`** accent, **`x`** - normal, **`g`** ghost (soft), **`.`** mute (rest). Length = beats per bar × `sub`. Omit to get the - default — the first step of **each beat** accented, the rest normal (click a pad in - the UI to cycle accent → normal → ghost → mute). e.g. `4=.X.X` accents the backbeat (2 & 4); - `4/2s` is swung eighths with the default accents. (Legacy `x`/`.` on/off patterns and - short beat‑count patterns still parse.) +- **sound** — a synthesized voice. Friendly kit names (rendered with 808/909): + `beep`, `kick`, `snare`, `rim`, `clap`, `hatClosed`, `hatOpen`, `ride`, `crash`, `tomLow`, + `tomMid`, `tomHigh`, `tambourine`, `cowbell`, `woodblock`, `claves`; the drum‑machine voices + by name — `kick808 snare808 clap808 hat808 openHat808 cowbell808 tom808` and + `kick909 snare909 clap909 hat909 ride909 crash909`; or a **General‑MIDI note number** + (`36`→kick, `38`→snare, `42`→closed hat, …). Unknown → `beep`. +- **grouping** — beats per bar, optionally grouped for odd meters: `4`, `3`, `2+2+3`. + Groups get a visual divider; accents are per‑step (see `=pattern`). +- **`/sub`** — subdivision: `1` quarter (default), `2` eighth, `3` triplet, `4` sixteenth, + `6` sextuplet — also sets how many **pads** each beat splits into. Append **`s`** for **swing** + on even subdivisions (`2s`, `4s`) to delay the off‑beats to a 2:1 triplet feel. +- **`(k,n[,rot])`** — **Euclidean** fill: place `k` hits as evenly as possible across `n` + steps, optionally rotated by `rot`. e.g. `kick:4(3,8)`. +- **`=pattern`** — per‑**step dynamics**, one char per pad: **`X`** accent, **`x`** normal, + **`g`** ghost (soft), **`.`** `-` `_` mute (rest). Length = beats × `sub`. Omit to get the + default — first step of each beat accented, the rest normal. e.g. `4=.X.X` accents 2 & 4. +- **`@`** — per‑lane gain trim in decibels, e.g. `@-3` or `@+2`. - **`~`** — polyrhythm: fit this lane's beats evenly into **lane 1's** bar. - **`!`** — mute the lane. @@ -120,28 +129,27 @@ Tokens are joined with `;`. `tr` and `rmp` are omitted when off. | `snare:4=.X.X` | accented snare backbeat (2 & 4) | | `hatClosed:4/2` | eighth‑note hi‑hats (downbeat of each beat accented) | | `ride:4/2s` | **swung** eighth‑note ride | +| `kick:4(3,8)` | a 3‑over‑8 Euclidean kick | | `claves:5~` | 5 evenly across lane 1's bar (5‑over‑4 if lane 1 is `4`) | +| `hat909:4/2@-4` | eighth 909 hats, trimmed −4 dB | | `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=` — readable, e.g. - `…/#p=v1;t120;kick:4;claves:5~` -- **Set list:** `…/#sl=` — a JSON `{title, description, items[]}` where - each item's config is a patch string. Used because titles/notes are free text. +- **Settings:** `…/#p=` — readable, e.g. `…/#p=v1;t120;kick:4;claves:5~` +- **Set list:** `…/#sl=` — a JSON `{title, description, items[]}` where each + item's config is a patch string. -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. +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**. The link encodes everything in the URL — nothing is uploaded. -- **Export all / Import file** back up your set lists and practice log as a JSON - file (a legacy `presets` field is included for backward compatibility). +- **Share settings link** / **Share set‑list link** open a dialog with the link to **Copy** + or **Open**. The link encodes everything in the URL — nothing is uploaded. +- **Export all / Import file** back up your set lists and practice log as a JSON file. ## Embedding @@ -155,16 +163,30 @@ container and the loader script — it builds an `