Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 7 additions & 0 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

### Conditional editor metadata is exposed

Catalog parameters now expose `toggle_on`, `toggle_off`, and `toggle_steps` as
integer tuples: the catalog's own conditional-editor references, published
without a claim about how a host editor should act on them. Read from the CorOS
4.0.1 catalog, where 132, 83 and 13 parameters carry them.

### Rename the unit, drive undo/redo, and read inhibited modules

`set_device_name()` sends a sparse Version update. `undo()` and `redo()` drive
Expand Down
3 changes: 2 additions & 1 deletion docs/STEERING.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,8 @@ ADR-0012.
- `examples/` - runnable scripts
- `docs/` - the documents listed in [`writing.md`](writing.md)
- `scripts/` - `compile_protos.sh`, `check_artifacts.py`, the three generators
and `_snapshots.py`, `extract_scale_fixture.py`
and `_snapshots.py`, `extract_scale_fixture.py`,
`extract_editor_metadata_fixture.py`
- `.github/workflows/` - CI

## 5. Patterns in Use
Expand Down
18 changes: 15 additions & 3 deletions docs/domain-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -1193,18 +1193,26 @@ hardware, host concerns or reference text with nothing for a host API to model.

## Catalog attributes

The unit puts 24 distinct attributes on its `<Parameter>` elements. Seventeen are
The unit puts 24 distinct attributes on its `<Parameter>` elements. Twenty are
parsed. What follows is what is known about the ones that matter to a caller, and
the seven that are not yet explained. Counts are from the CorOS 4.0.1 catalog,
the four that are not yet explained. Counts are from the CorOS 4.0.1 catalog,
3,809 parameters. Nothing here is guessed at: a control we do not understand is
omitted with the reason written down.

### Conditional editor metadata

`toggleOn`, `toggleOff`, and `toggleStep` occur on 132 / 83 / 13 fields,
212 parameters between them. They are exposed as `toggle_on`, `toggle_off`,
and `toggle_steps` without assigning host behaviour. The catalog shape indicates
that the first two name a conditional-visibility driver and the last names its
option: Splitter's controls partition cleanly by `TYPE`. Three Mono Synth
parameters self-reference, so those cases remain unexplained.

### Unexplained

| 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 |
Expand Down Expand Up @@ -1358,6 +1366,10 @@ On `<Model>`, `blob` is unexplained: a same-length string that changes between
reads, on 338 models and no others across the three lab captures. A per-read
token, not content.

`linkedSceneMode` appears 44 times in the contributed CorOS 4.1.0 catalog and
zero times in 4.0.1. Its meaning and relationship, if any, to preset
`scene_mode` are unknown, so it is recorded here and not exposed as shared API.

On `<Option>` labels, the character `¤` (U+00A4) appears as a separator inside a
label (`Triads¤Closed Triad (3-R-5)`) in 27 labels of the CorOS 4.1.0 catalog a
contributor regenerated (PR #44), and in none of the 4.0.1 catalog. It reads like
Expand Down
6 changes: 5 additions & 1 deletion docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -2211,7 +2211,11 @@ wire, with no independent read-back.
touchscreen's own assignment menu is the candidate and has not been checked.
Whether the unit acts on an assignment stored against such a parameter needs
audio, not a wire read.
- **What `toggleOn`, `toggleOff` and `toggleStep` mean**, on 212 parameters.
- **Three self-referencing conditional metadata entries** remain unexplained:
Mono Synth indexes 15 and 24 point `toggleOn` to themselves, and index 48
points `toggleOff` to itself. Elsewhere, CorOS 4.0.1 catalog shape indicates
`toggleOn` / `toggleOff` name a conditional-visibility driver and
`toggleStep` its option: Splitter's controls partition cleanly by `TYPE`.
- **Whether a capture id denotes different content on a different unit** needs a
second unit.
- **Whether host writes are honoured during standby.**
Expand Down
20 changes: 19 additions & 1 deletion pyquadcortex/protocol/catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,17 @@ class Parameter:
#: Addressing a parameter keeps using the index. This says where a control
#: is drawn, not what selects it.
display_pos: int | None = None
#: Parameter indexes named by the catalog's conditional-editor metadata,
#: on 132 and 83 parameters. Inferred from the catalog's shape, not measured
#: on a unit: the Splitter is the clearest case, where the three options of
#: its ``TYPE`` switch partition the block - ``BALANCE`` on step 0, the two
#: ``LEVEL TO`` knobs on step 1, ``FREQUENCY`` and ``MODE`` on step 2.
#: Three Mono Synth parameters name their own index and are unexplained.
toggle_on: tuple[int, ...] = ()
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
#: The counterpart of :attr:`toggle_on`.
toggle_off: tuple[int, ...] = ()
#: Option indexes named by ``toggleStep``.
toggle_steps: tuple[int, ...] = ()
#: Whether the unit keeps this parameter OFF the screen, from the XML's
#: ``hidden``. It matters to anything that compares the catalog against what
#: a person can see: a hidden parameter's option names are never drawn, so
Expand Down Expand Up @@ -878,6 +889,9 @@ def _parameter(index: int, p, model_name: str) -> Parameter:
exp_assignable=p.get("expAssignable") != "false",
show_as_integer=show_as_integer,
display_pos=_as_int(p.get("displayPos")),
toggle_on=_parse_replaces(p.get("toggleOn")),
toggle_off=_parse_replaces(p.get("toggleOff")),
toggle_steps=_parse_replaces(p.get("toggleStep")),
hidden=p.get("hidden") == "true",
)

Expand Down Expand Up @@ -932,7 +946,11 @@ def parse_model_repo(payload: bytes) -> ModelCatalog:


def _parse_replaces(value: str | None) -> tuple[int, ...]:
"""Parse a ``replaces`` attribute: one id, or several comma-separated."""
"""Parse an optional comma-separated list of catalog integer indexes.

Invalid parts are deliberately ignored: device catalogs are extensible,
and one unfamiliar token must not discard otherwise usable metadata.
"""
if not value:
return ()
ids = []
Expand Down
172 changes: 172 additions & 0 deletions scripts/extract_editor_metadata_fixture.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
#!/usr/bin/env python3
"""Distil editor-layout evidence from a device ModelRepo.

python scripts/extract_editor_metadata_fixture.py --payload model_repo.bin

The full vendor catalog is not redistributed. The fixture contains only the
raw attributes needed to reproduce the midpoint, display-position, and
conditional-editor facts asserted by the offline suite.
"""

import argparse
import collections
import json
import pathlib
import sys
import xml.etree.ElementTree as ET

sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))

from pyquadcortex.protocol import catalog # noqa: E402


EDITOR_ATTRIBUTES = {
"name", "min_string", "mid_string", "max_string", "skew", "displayPos",
"isplayPos", "toggleOn", "toggleOff", "toggleStep",
}


def _row(model, index, parameter):
return {
"model_id": int(model.get("id")),
"model": model.get("name"),
"index": index,
"raw": {
key: value for key, value in parameter.attrib.items()
if key in EDITOR_ATTRIBUTES
},
}


def extract(payload: bytes) -> dict:
"""Build the committed evidence shape from one raw ModelRepo payload."""
root = ET.fromstring(catalog._extract_xml(payload))
models = list(root.iter("Model"))
all_parameters = [
(model, index, parameter)
for model in models
for index, parameter in enumerate(model.findall("Parameter"))
]

midpoint_rows = [
_row(model, index, parameter)
for model, index, parameter in all_parameters
if parameter.get("mid_string") is not None
]

collision_rows = []
gap_models = []
display_carriers = 0
for model in models:
positions = collections.defaultdict(list)
for index, parameter in enumerate(model.findall("Parameter")):
raw = parameter.get("displayPos")
if raw is None:
continue
display_carriers += 1
try:
positions[int(raw)].append(_row(model, index, parameter))
except ValueError:
continue
duplicates = {
str(position): rows for position, rows in positions.items()
if len(rows) > 1
}
if duplicates:
collision_rows.append({
"model_id": int(model.get("id")),
"model": model.get("name"),
"positions": duplicates,
})
# Use the explicit all-parameter basis: every missing integer in
# 0..max(displayPos) is a gap. This counts all 533 CorOS 4.0.1 models,
# including the two hidden models PCOM Tape Delay (ST) and Chief DC2W
# PCOM; excluding them gives 19 rather than 21 gap models.
if positions:
missing = sorted(set(range(max(positions) + 1)) - set(positions))
if missing:
gap_models.append({
"model_id": int(model.get("id")),
"model": model.get("name"),
"missing": missing,
})

toggle_rows = {
attribute: [
_row(model, index, parameter)
for model, index, parameter in all_parameters
if parameter.get(attribute) is not None
]
for attribute in ("toggleOn", "toggleOff", "toggleStep")
}
self_references = []
for attribute in ("toggleOn", "toggleOff"):
for row in toggle_rows[attribute]:
indexes = {
int(part.strip()) for part in row["raw"][attribute].split(",")
if part.strip().lstrip("-").isdigit()
}
if row["index"] in indexes:
self_references.append({
**row, "attribute": attribute,
})

typo = next(
_row(model, index, parameter)
for model, index, parameter in all_parameters
if parameter.get("isplayPos") is not None
)

fixture = {
"source": "Quad Cortex CorOS 4.0.1 ModelRepo payload",
"firmware": "CorOS 4.0.1",
"parameters": len(all_parameters),
"mid_string": {
"rows": midpoint_rows,
},
"displayPos": {
"carriers": display_carriers,
"collision_models": collision_rows,
"gap_models": gap_models,
"device_typo": typo,
},
"toggle": {
"counts": {
attribute: len(rows)
for attribute, rows in toggle_rows.items()
},
"step_rows": toggle_rows["toggleStep"],
"all_step_carriers_have_on_or_off": all(
"toggleOn" in row["raw"] or "toggleOff" in row["raw"]
for row in toggle_rows["toggleStep"]
),
"self_references": self_references,
},
}

return fixture


def main():
parser = argparse.ArgumentParser()
parser.add_argument("--payload", required=True)
parser.add_argument(
"--out", default="tests/fixtures/catalog/editor_metadata.json")
args = parser.parse_args()

payload = pathlib.Path(args.payload).read_bytes()
fixture = extract(payload)
out = pathlib.Path(args.out)
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(json.dumps(fixture, indent=2) + "\n", encoding="utf-8")
midpoint_rows = fixture["mid_string"]["rows"]
collision_rows = fixture["displayPos"]["collision_models"]
self_references = fixture["toggle"]["self_references"]
print(
f"wrote {len(midpoint_rows)} midpoint rows, "
f"{len(collision_rows)} collision models, and "
f"{len(self_references)} self-references to {out}")


if __name__ == "__main__":
main()
Loading
Loading