Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
5e71298
Resolve cloned ModelRepo parameters
tony-xmelon Sep 3, 2026
d33bd35
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 5, 2026
8e33647
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 7, 2026
e44bd54
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 8, 2026
0490350
fix: resolve ModelRepo clone layouts defensively
tony-xmelon Sep 8, 2026
ccecf69
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 9, 2026
181f567
fix: address ModelRepo clone review
tony-xmelon Sep 9, 2026
1b5523d
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 12, 2026
831e1d6
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 19, 2026
66c3996
Follow documentation typography rules
tony-xmelon Sep 19, 2026
ff77dac
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 22, 2026
6a2a31e
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 22, 2026
bc9df0d
Regenerate 4.0.1 option usage from captured catalog
tony-xmelon Sep 22, 2026
aa35e7f
Address ModelRepo clone review findings
tony-xmelon Sep 26, 2026
43cfbe4
Address catalog review count and hardware assumptions
tony-xmelon Sep 27, 2026
0d3c3df
Merge remote-tracking branch 'upstream/main' into codex/modelrepo-clo…
tony-xmelon Sep 27, 2026
0d2bbe8
docs: refresh generated option counts
tony-xmelon Sep 27, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,13 @@ sustained stretch without a correction.

## Unreleased

### ModelRepo clone layouts are resolved

Models that declare `clones` now expose the inherited wire layout with numeric
parameter replacements applied before child-only extensions. This fixes both
ordinary and PCOM cab addressing and the cloned reverb families. A malformed
model logs the model and reason, then falls back locally without discarding the
rest of the device catalog.
### Rename the unit, drive undo/redo, and read inhibited modules

`set_device_name()` sends a sparse Version update. `undo()` and `redo()` drive
Expand Down Expand Up @@ -52,7 +59,7 @@ the only enum whose names are known to differ from what the screen shows.

`OPTION_AUDIT` tells you whether anybody has held a list against the unit's
screen. It does not tell you how much rides on the answer, and that is the other
half of the question: `Off,On` decides 222 parameters and `CHO1,CHO2` decides
half of the question: `Off,On` decides 278 parameters and `CHO1,CHO2` decides
two, so 94 unread lists are not 94 equal jobs.

`OPTION_USAGE` publishes the count for every fixed list, keyed by the labels
Expand All @@ -64,11 +71,11 @@ from pyquadcortex.protocol import options
unread = [labels for labels, status in options.OPTION_AUDIT.items()
if status is None]
unread.sort(key=lambda labels: (-options.OPTION_USAGE[labels], len(labels), labels))
options.OPTION_USAGE[unread[0]] # 14 parameters - the biggest unread list
options.OPTION_USAGE[unread[0]] # 40 parameters - the biggest unread list
```

On the CorOS 4.0.1 snapshot that is 527 parameters across 113 lists, of which
190 across 94 lists are unread. `tests/test_option_audit.py` holds
On the CorOS 4.0.1 snapshot that is 611 parameters across 113 lists, of which
218 across 94 lists are unread. `tests/test_option_audit.py` holds
`docs/domain-model.md` to those numbers, so they cannot be carried in prose from
a count taken once.

Expand Down Expand Up @@ -261,9 +268,9 @@ covering all 533 models, and the readings that built it are now tests
units needs a catalog, which comes from the unit; `protocol.bpm_to_tempo` and the
other standalone helpers still work without one.

**Option names were in the catalog all along.** 527 parameters use 113 distinct
**Option names were in the catalog all along.** 611 parameters use 113 distinct
lists, so `pyquadcortex.protocol.options` publishes them as enums
(`options.DynMode3.GATE`, `options.HpfSlope.MINUS_12`); 247 parameters are plain
(`options.DynMode3.GATE`, `options.HpfSlope.MINUS_12`); 303 parameters are plain
Off/On and take a `bool`. `set_param_option` needs `source=` only for the twelve
dynamic lists. The unit's own spelling stays on the wire (`Noral`).

Expand Down
22 changes: 14 additions & 8 deletions docs/domain-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -1203,12 +1203,17 @@ omitted with the reason written down.

| attribute | on | what it looks like, and what is unknown |
|---|---|---|
| `replaces` | 462 | Distinct from the `<Model>` attribute of the same name. On a parameter it presumably names a superseded index, which would matter for reading an old preset. Untested |
| `toggleOn`, `toggleOff`, `toggleStep` | 132 / 83 / 13, 212 parameters between them | `toggleOn` carries a number on `float` parameters such as a tremolo's `LEVEL`, and `toggleStep` sometimes carries a pair (`"0,1"`). The obvious reading is the two values a footswitch toggle alternates between. Untested |
| `tooltip` | 126 | The help text the unit shows. Real prose, sometimes with content: a Vibrato's `MODE` warns that changing it causes a brief mute. The values contain HTML |
| `selfTestValue` | 66 | A value the unit uses during its self test. Sometimes an IR name, sometimes a token |
| `isplayPos` | 1 | `displayPos` with the `d` missing. The catalog's own typo, recorded rather than silently accepted as an alias |

Numeric parameter `replaces` values are inherited wire indexes on a model that
declares `clones`; the parser resolves them before publishing the model.
`Model/@clones` names the parent layout. The nonnumeric `replaces="INTENSITY"`
on `MX Vibe` remains unexplained and makes only that model fall back to its local
parameter order.

### `type` names the widget, and two of its values are readouts

Across the catalog `type` takes twelve values: `float` 2618, `switch` 461,
Expand Down Expand Up @@ -1375,23 +1380,24 @@ against `Return 1/2`, `USB 5` against `USB input 5`).
So every list's names are a hypothesis until a person reads them off the unit.
`options.OPTION_AUDIT` publishes which have been, keyed by the labels rather than
by the enum so the two Off/On lists and the metronome list, which get no enum
and are 260 parameters between them, can be recorded too. The readings are in
and are 316 parameters between them, can be recorded too. The readings are in
`tests/fixtures/catalog/option_readings.json`, one row per position, and
`scripts/generate_options.py` stamps each enum's docstring from them.

**Where it stands (2026-09-16, CorOS 4.0.1): 13 audited, 1 drawn, 5 not drawn,
94 unread**, of 113 fixed lists. The fourteen read lists cover 301 of the 527
parameters that carry a fixed list. The 94 unread cover 190.
**Where it stands (2026-09-16, CorOS 4.0.1): 13 audited, 1 drawn, 5 absent,
94 unread**, of 113 fixed lists. The 14 assessed lists cover 357
parameters; 5 lists looked for and not drawn account for 36, and the 94
unread lists account for 218 of the 611 parameters that carry a fixed list.

What is left is not 94 equal jobs. Ranked by how many parameters each list
decides, the tail falls away fast: the biggest five cover 54 of the 190.
decides, the tail falls away fast: the biggest five cover 82 of the 218.
`options.OPTION_USAGE` publishes the count for every list, so a session at the
unit can be planned from the library rather than from a count taken once.

| parameters | positions | list | somewhere it appears |
|---|---|---|---|
| 40 | 3 | `Small,Med,Large` | Ambience / `SIZE` |
| 14 | 17 | a 17-entry `SYNC NOTE` | Vibrato / `SYNC NOTE` |
| 12 | 3 | `Small,Med,Large` | Ambience / `SIZE` |
| 11 | 3 | `Off,Duck,Gate` | Digital Delay (ST) / `DYN MODE` |
| 9 | 14 | a 14-entry `SYNC NOTE` | Dual Chorus / `SYNC NOTE` |
| 8 | 3 | `Normal,Thick,Thicker` | CA 1Star Clean 50W Normal / `EQ` |
Expand All @@ -1411,7 +1417,7 @@ defines.

| list | parameters | how it was read |
|---|---|---|
| `Off,On` | 222 | a Circular Delay's `SYNC` and `TRAILS`, each position driven |
| `Off,On` | 278 | a Circular Delay's `SYNC` and `TRAILS`, each position driven |
| `SYNC NOTE` (21 entries) | 28 | the dial in order, anchored at 0 and 13 |
| `OFF,ON` | 25 | the same block's `VINTAGE MODE`, each position driven |
| `OFF,MUTE,DOWN,ON` | 13 | the metronome cells, re-driven as the control |
Expand Down
11 changes: 8 additions & 3 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -1984,10 +1984,14 @@ The XML is `<Models><Category id name><Model id name .../></Category></Models>`.

- **`Model/@id` is the wire hash.** Ids are globally unique: category 4
(Equalizer) holds 4000 to 4007, category 21 (Cabsim Bass) holds 21001 to 21009.
- **`<Parameter>` children are in wire-index order**, each with `min`, `max`,
- **Resolved `<Parameter>` children are in wire-index order**, each with `min`, `max`,
`defaultValue`, `units`, `skew`, `steps`, `stepNames`, `type` and more. This is
what gives a parameter index meaning: writing index 0 of a cab moves no visible
knob because a cab's own entry lists internal `ir selector` parameters.
what gives a parameter index meaning. A model may declare `clones`; numeric
parameter `replaces` values place child metadata at inherited indexes and
child-only parameters extend the layout. Read-only CorOS 4.1.0 checks by
Antoni Ivanov on 2026-09-08 confirmed the 21/31-parameter cab parent layouts
and the cloned `Gojira REV` ordering; Jonathan Stokes independently confirmed
the same shapes on CorOS 4.0.1 on 2026-09-09.
- **Parameter values on the wire are normalized 0..1.** Sending `1.0` to a
`THRESHOLD` whose catalog range is -60..+12 dB made the unit display +12.0 dB.

Expand All @@ -1998,6 +2002,7 @@ Attributes that classify a model:
| `sku`, `plugin_id` | purchasable plugin content; a given unit may not have it |
| `hidden`, `internal` | not user-facing; `hidden` also appears on whole categories. Read the value, not the presence: two ordinary amps ship `hidden="false"` (Bogna Uber Clean 1130, Bogna Uber Lead 1131) |
| `replaces` | this model supersedes the listed id(s). Both stay in the catalog and can share a display name (two "Graphic-9" equalizers, 4005 replacing 4002) |
| `clones` | this model inherits another model's parameter layout; numeric parameter-level `replaces` values override inherited wire indexes |

Because the catalog comes from the unit it also covers Neural Captures
(categories 14 and 20), which are user content. The library ships generated
Expand Down
107 changes: 104 additions & 3 deletions pyquadcortex/protocol/catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,16 @@

from __future__ import annotations

from dataclasses import dataclass, field, replace
import gzip
import io
import logging
import math
import tarfile
import xml.etree.ElementTree as ET
from dataclasses import dataclass, field, replace


logger = logging.getLogger(__name__)

# The numbers behind the catalog's symbolic bounds. `units` imports nothing from
# this module, so this direction is the only one and there is no cycle.
Expand Down Expand Up @@ -882,10 +886,93 @@ def _parameter(index: int, p, model_name: str) -> Parameter:
)


def _effective_parameter_elements(
model,
models: dict[int, ET.Element],
resolving: tuple[int, ...] = (),
) -> tuple[tuple[int, ET.Element], ...]:
"""Return a model's parameters at their effective wire indexes.

ModelRepo models may ``clone`` another model and publish only the
parameters they replace. Each child's numeric ``replaces`` attribute is the
inherited wire index; child parameters without one extend the resolved
list. On the contributed CorOS 4.1.0 catalog (2026-09-08, Antoni Ivanov),
cabs clone four different 21- or 31-parameter layouts and a reverb family
clones model 8015. Jonathan Stokes confirmed the same 4.0.1 layout sizes
on 2026-09-09.

A missing clone target is diagnosed and treated like an ordinary model. A
malformed clone (including a cycle) raises here so :func:`parse_model_repo`
can fall that model back to its local parameters without discarding the
catalog.
"""
model_id = _as_int(model.get("id"))
assert model_id is not None
if model_id in resolving:
chain = " -> ".join(str(ident) for ident in (*resolving, model_id))
raise ValueError(f"ModelRepo clone cycle: {chain}")

clone_id = _as_int(model.get("clones"))
base = models.get(clone_id) if clone_id is not None else None
if clone_id is not None and base is None:
model_name = model.get("name", "")
raise ValueError(
f"ModelRepo model {model_id} ({model_name!r}) declares missing "
f"clone parent {clone_id}"
)
if base is None:
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
effective = list(enumerate(model.findall("Parameter")))
else:
inherited = _effective_parameter_elements(base, models, (*resolving, model_id))
by_index = dict(inherited)
replacements = []
extensions = []
for parameter in model.findall("Parameter"):
raw = parameter.get("replaces")
if raw is None:
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
extensions.append(parameter)
continue
replaced = _as_int(raw)
if replaced is None:
raise ValueError(
f"ModelRepo model {model_id} has non-numeric parameter "
f"replaces={raw!r}"
)
replacements.append((replaced, parameter))

seen = set()
for index, parameter in replacements:
if index in seen:
raise ValueError(
f"ModelRepo model {model_id} replaces parameter index "
f"{index} more than once"
)
seen.add(index)
by_index[index] = parameter
next_index = max(by_index, default=-1) + 1
for parameter in extensions:
by_index[next_index] = parameter
next_index += 1
effective = sorted(by_index.items())

indexes = [index for index, _ in effective]
if indexes != list(range(len(indexes))):
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
raise ValueError(
f"ModelRepo model {model_id} resolves to non-contiguous parameter "
f"indexes {indexes}"
)
return tuple(effective)


def parse_model_repo(payload: bytes) -> ModelCatalog:
"""Parse a device ModelRepo payload into a :class:`ModelCatalog`."""
root = ET.fromstring(_extract_xml(payload))
catalog = ModelCatalog()
elements = {
model_id: element
for element in root.iter("Model")
if (model_id := _as_int(element.get("id"))) is not None
}
for category in root.findall("Category"):
category_id = _as_int(category.get("id"))
category_name = category.get("name", "")
Expand All @@ -901,9 +988,23 @@ def parse_model_repo(payload: bytes) -> ModelCatalog:
model_id = _as_int(element.get("id"))
if model_id is None:
continue
try:
effective = _effective_parameter_elements(element, elements)
except ValueError as exc:
# A catalog can include purchased content and player-created
# models this build has never seen. One malformed clone must
# not discard every other model; preserve its local parameters
# in published order, as the parser did before clone support.
logger.warning(
"ModelRepo model %s clone resolution failed; using its local "
"parameter order: %s",
model_id,
exc,
)
effective = tuple(enumerate(element.findall("Parameter")))
parameters = tuple(
_parameter(i, p, element.get("name", ""))
for i, p in enumerate(element.findall("Parameter"))
_parameter(index, parameter, element.get("name", ""))
for index, parameter in effective
)
catalog.models[model_id] = Model(
id=model_id,
Expand Down
18 changes: 9 additions & 9 deletions pyquadcortex/protocol/catalogs/coros_4_0_1/options.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@

qc.set_param_option(block, 'DYN MODE', options.DynMode.GATE)

110 enums cover 267 parameters, because the same list means
110 enums cover 295 parameters, because the same list means
the same thing wherever it appears - the note-length list is shared by
``SYNC NOTE``, ``SYNC NOTE L``, ``SYNC NOTE R`` and two more.

**A two-option Off/On parameter gets no enum.** 247 parameters
**A two-option Off/On parameter gets no enum.** 303 parameters
offer exactly those, and ``True`` says everything ``OffOn.ON`` would::

qc.set_param(block, 'SYNC', True)
Expand Down Expand Up @@ -1361,9 +1361,9 @@ class Scale(IntEnum):


class Size(IntEnum):
"""12 parameters use this list: SIZE
"""40 parameters use this list: SIZE

On 12 models, among them Ambience, Dual (M), Dual (M) Lite.
On 40 models, among them Ambience, Cory Wong Cab 1 (M), Cory Wong Cab 1 (ST).

NOT audited against the screen. These names are the
catalog's ``stepNames``, which is not known to be the
Expand Down Expand Up @@ -2203,14 +2203,14 @@ class VoiceMode(IntEnum):
#: LABELS, like the audit, so the three lists with no enum are in
#: it too.
#:
#: Totals on this snapshot: 527
#: parameters across 113 lists, of which 190 across
#: Totals on this snapshot: 611
#: parameters across 113 lists, of which 218 across
#: 94 lists nobody has read. The work is long-tailed - the
#: five biggest unread lists cover 54 of those 190.
#: five biggest unread lists cover 82 of those 218.
OPTION_USAGE = {
('OFF', 'MUTE', 'DOWN', 'ON'): 13, # no enum
('OFF', 'ON'): 25, # no enum
('Off', 'On'): 222, # no enum
('Off', 'On'): 278, # no enum
('Bypass', '90°', '180°'): 2, # Adjust
('1/16', '1/8T', '1/16D', '1/8', '1/4T', '1/8D', '1/4', '1/2T', '1/4D', '1/2', '1/1T', '1/2D', '1/1'): 2, # AnalogDelayMSyncNote
('Up', 'Down', 'Up & Down', 'Down & Up', 'Random'): 1, # ArpPattern
Expand Down Expand Up @@ -2291,7 +2291,7 @@ class VoiceMode(IntEnum):
('MULTI', 'HP', 'OUT 1/2', 'OUT 3/4', 'SEND 1/2'): 1, # Routing
('Grid', 'In 1', 'In 2', 'Ret 1', 'Ret 2', 'In 1/2', 'Ret 1/2', 'Out1', 'Out2', 'Out3', 'Out4', 'Out1/2', 'Out3/4', 'Multi'): 1, # RoutingMode
('Major', 'Minor'): 1, # Scale
('Small', 'Med', 'Large'): 12, # Size
('Small', 'Med', 'Large'): 40, # Size
('1/64T', '1/64', '1/32T', '1/64D', '1/32', '1/16T', '1/32D', '1/16', '1/8T', '1/16D', '1/8'): 2, # SlapbackDelayMSyncNote
('6dB/Oct', '12dB/Oct', '18dB/Oct', '24dB/Oct'): 1, # Slope
('Clean', 'Crunch', 'Lead'): 1, # SoldanoSlo100Channel
Expand Down
28 changes: 16 additions & 12 deletions pyquadcortex/protocol/catalogs/coros_4_0_1/params.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@
(ADR-0018). The runtime check is unchanged and still covers every other
caller - a string, a bare index, or anyone not running a checker.

**Cabs share one layout.** The catalog lists two parameters for a cab -
its two mic selectors - while the wire carries 22. So a cab is CHOSEN by
its `models.*` id and DRIVEN through :class:`Cabsim`::
**Cabs use multiple layouts.** :class:`Cabsim` names the ordinary
21-parameter layout; PCOM cabs have 31 catalog parameters and should be
resolved through the connected device's catalog. A cab is chosen by its
`models.*` id::

cab = Block(0, 5, models.CabsimGuitarM.N412_CA_STAND_OS_S_V30_90S_M)
qc.set_block(cab)
Expand Down Expand Up @@ -157,27 +158,30 @@ class TempoParam(ParamSet):
STEPSTATE12: Param[NoUnit] = Param(22, 'STEPSTATE12') # empty


# -- cabs: one layout, shared by every cab model ------------------------------
# -- ordinary 21-parameter cab layout ---------------------------------------


class Cabsim(ParamSet):
"""Every cab model's parameters. The catalog under-describes these.
"""The ordinary 12000-family cab layout (21 catalog parameters).

Measured on four cabs across all four categories: the wire carries
22 parameters in the `Default Cabsim` layout regardless of which cab
is loaded, or whether it is mono or stereo. `MIC_1_PAN` is labelled
BALANCE on a stereo cab and PAN on a mono one - one wire index, two
screen names.
The wire carries one additional undocumented value at index 21. PCOM
cabs instead clone a 31-parameter layout (and carry 32 wire values),
so resolve their extra controls through the live catalog.

The catalog declares index 3 as PAN over 0..10 on mono layouts and
BALANCE over -1..1 on stereo layouts. Neither span matches the
screen: on CorOS 4.0.1 both layouts displayed wire values 0, 0.5,
0.75 and 1 as 50 L, C, 25 R and 50 R. See issue #55.

The mic-to-index mapping was confirmed against the unit's own
editor. Index 21 exists on the wire, is absent from the catalog and
editor on mono cabs. Index 21 exists on the wire, is absent from the catalog and
reads 0.0 everywhere, so it is omitted rather than guessed at.
"""

MIC_1_BYPASS: Param[NoUnit] = Param(0, 'MIC_1_BYPASS') # switch
MIC_1_IR_SELECTOR: Param[NoUnit] = Param(1, 'MIC_1_IR_SELECTOR') # string
MIC_1_LEVEL: Param[DbUnit] = Param(2, 'MIC_1_LEVEL') # float dB
MIC_1_PAN: Param[NoUnit] = Param(3, 'MIC_1_PAN') # float
MIC_1_PAN: Param[NoUnit] = Param(3, 'MIC_1_PAN') # float; mono PAN 0..10, stereo BALANCE -1..1
MIC_1_DISTANCE: Param[NoUnit] = Param(4, 'MIC_1_DISTANCE') # float
MIC_1_POSITION: Param[NoUnit] = Param(5, 'MIC_1_POSITION') # float
MIC_1_PHI: Param[NoUnit] = Param(6, 'MIC_1_PHI') # switch
Expand Down
Loading
Loading