From 048403e92bd410a1e9cd840073a6624e9dbe78bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=27=C3=A9lectron=20rare?= <108685187+electron-rare@users.noreply.github.com> Date: Sun, 28 Jun 2026 12:49:13 +0200 Subject: [PATCH] docs: capture touchosc v3 tosc schema ground truth --- .../specs/2026-06-28-tosc-schema-reference.md | 126 ++++++++++++++++++ touchosc/reference/probe-roundtrip.pretty.xml | 69 ++++++++++ touchosc/reference/probe-roundtrip.tosc | Bin 0 -> 499 bytes touchosc/reference/probe-roundtrip.xml | 2 + 4 files changed, 197 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-28-tosc-schema-reference.md create mode 100644 touchosc/reference/probe-roundtrip.pretty.xml create mode 100644 touchosc/reference/probe-roundtrip.tosc create mode 100644 touchosc/reference/probe-roundtrip.xml diff --git a/docs/superpowers/specs/2026-06-28-tosc-schema-reference.md b/docs/superpowers/specs/2026-06-28-tosc-schema-reference.md new file mode 100644 index 0000000..fdcb86f --- /dev/null +++ b/docs/superpowers/specs/2026-06-28-tosc-schema-reference.md @@ -0,0 +1,126 @@ +# TouchOSC `.tosc` v3 Schema Reference (ground truth) + +**Date:** 2026-06-28 +**Status:** Format pinned from generator output; **visual fidelity gate +(render in TouchOSC editor) pending human confirmation** — see §6. +**Consumes/feeds:** `touchosc/gen/schema.py` (the single format choke point). + +## 1. Provenance + +The plan's Task 1 step 1 (hand-author a reference layout in the TouchOSC +editor) was replaced by a **generate-and-iterate** path (no pre-existing +`.tosc` was found on disk at planning time). The authoritative bytes here come +from `touchosc/gen/schema.py` emitting a minimal GROUP > FADER probe, captured +in `touchosc/reference/probe-roundtrip.{tosc,xml,pretty.xml}`. + +A byte-identical copy of this probe was found in TouchOSC's iCloud document +cache (`~/Library/Application Support/CloudDocs/session/i/`, md5 +`aaa466e27c16ab9b25e18c84a98a71a1`), indicating TouchOSC ingested the file into +its library — weak-positive evidence the format is accepted. The XML structure +matches the documented Hexler v3 `lexml` schema in every element. **Final +proof — the layout rendering correctly in the TouchOSC editor — is a human +at-screen check (§6).** + +## 2. Container + +- A `.tosc` is **gzip-compressed UTF-8 XML** (Python `gzip` default level 9). +- Root element: `` containing exactly **one** root ``. +- XML declaration present: ``. + +## 3. Node + +``` + + property* + + osc* + node* + +``` + +- `ID` — a UUID4 string (`tosc_id()`). +- `type` — control type: `GROUP BOX BUTTON LABEL TEXT FADER XY RADIAL ENCODER + RADAR RADIO PAGER GRID` (per v3). The probe confirms `GROUP` and `FADER`. +- All four sub-blocks (`properties`, `values`, `messages`, `children`) are + emitted, empty as `<.../>` self-closing when they have no entries. + +## 4. Property + +``` + + name + ... + +``` + +Type codes (the `` child shape depends on the code): + +| code | meaning | `` shape | +|------|---------|-----------------| +| `s` | string | plain text (`vol`); also used for the `script` Lua property | +| `b` | bool | plain text `0`/`1` | +| `i` | int | plain text | +| `f` | float | plain text | +| `r` | frame/rect | `` | +| `c` | color | `` | + +The `frame` property (`type="r"`) is confirmed verbatim in the probe: +`102060200`. + +## 5. OSC message + +``` + + + xANY + + + ... + + + ... * + + +``` + +- **Attributes:** `enabled send receive feedback connections`, all present. +- **`connections`** = a fixed-width bit-string, **one flag per OSC connection, + left-to-right = connection 1..N**. TouchOSC writes **5 flags**; a fresh + message targeting connection 1 only is **`"00001"`** (rightmost = connection + 1). This is `schema.CONN_DEFAULT`. (NB: the plan text guessed `"00000001"`; + the pinned value is `"00001"`.) + +### 5.1 Partial (path segment OR argument) + +Fields are **child elements** (NOT attributes — this is the single biggest +deviation from the inactive `tosclib` reference, which used attributes): + +``` + + CONSTANT|VALUE + STRING|FLOAT|INTEGER|BOOLEAN + ... + 0 + 1 + +``` + +- `CONSTANT`/`STRING` with `/launch/vol` → a literal address (or + a literal string argument like `kick`). +- `VALUE`/`FLOAT` with `x` → bound to the control's `x` value. +- `scaleMin`/`scaleMax` present on every partial (default `0`/`1`). + +## 6. Visual fidelity gate (OPEN — human step) + +The generated bytes are structurally correct v3. The remaining check is purely +visual and must be done by a human at the GrosMac screen: + +1. In TouchOSC: **File > Open** → `touchosc/dist/_probe.tosc` (or the full + `av-live-control.tosc` once built). +2. Confirm the control(s) render with no parse error dialog. + +`open -a TouchOSC ` launches the app but was observed to show an +"Untitled" window rather than reliably loading the doc — prefer **File > Open** +inside TouchOSC for the gate. If a layout fails to load, fix +`touchosc/gen/schema.py` against this reference and regenerate; no other file +needs to change. diff --git a/touchosc/reference/probe-roundtrip.pretty.xml b/touchosc/reference/probe-roundtrip.pretty.xml new file mode 100644 index 0000000..9d6bb04 --- /dev/null +++ b/touchosc/reference/probe-roundtrip.pretty.xml @@ -0,0 +1,69 @@ + + + + + + name + root + + + + + + + + + name + vol + + + frame + + 10 + 20 + 60 + 200 + + + + + + + + + x + ANY + + + + + CONSTANT + STRING + /launch/vol + 0 + 1 + + + + + CONSTANT + STRING + kick + 0 + 1 + + + VALUE + FLOAT + x + 0 + 1 + + + + + + + + + diff --git a/touchosc/reference/probe-roundtrip.tosc b/touchosc/reference/probe-roundtrip.tosc new file mode 100644 index 0000000000000000000000000000000000000000..259ccd37dc8999f2904ce2604c8a67918b2cb0ba GIT binary patch literal 499 zcmVKG0Iif!kD@RT$KUT$5MF%Z3WA_X>Biiy zn@#rg;^HOuSlU5}SWJtqe)}5`#M}6^dpy8@rk&xJKU3(#X;)ZB&?YZcJn+7|0}GTW zWvwyC-6t$OhV~n7;!I4BRPp8 z+p5lci0$X)V)YA)_qyDJu5vI}eQviHT;9T&DZT?rYDJH{H~`aSSy6J)lyp_SY??L8 z#v+XFz!<*1XtBu)sX^UP57UV|4o9wol-vm>DLCARkt4G#3_>yVf^67P&!&%0%TH1t z%i62I}1^~GrGYHstx;uEsT~%;J4;!0W!8d+cKao zLW6+(h*Yj^WdJheV%r3wR0>3eBVaJb%R}r+=j$~N##PmC)9h3;p~f1S*ClK^|3gV1 zQgYo-`W|~;ZR$I6^8#C@8Wo%%7XKU8?ns6#SsXhTQsZ z1TWxct{9qj)oqre&s`QZ+Sf6V3lrDt!wyts{tMnV7uzp#{Y&wC`nr0$gD`ttOp|*A pr?1*_V+g@n!h1hk-GQqoj?`xkAN?WhGR +namerootnamevolframe102060200xANYCONSTANTSTRING/launch/vol01CONSTANTSTRINGkick01VALUEFLOATx01 \ No newline at end of file