<div align="center">
# X32/M32 OSC Expert Skill
**A source-grounded Agent Skill for Midas M32 and Behringer X32 digital consoles**
Exact OSC lookup · Console workflows · Effects · MIDI · Diagnostics · Offline packet tooling · Risk-gated planning
[](https://github.com/DXBMARK/x32-m32-osc-skill/actions/workflows/validate.yml)
[](CHANGELOG.md)
[](LICENSE)
[](https://www.python.org/)
[](skill/x32-m32-osc-expert/SKILL.md)
[](SCOPE_BOUNDARY.md)
[](skill/x32-m32-osc-expert/data/osc-address-catalog.csv)
[](skill/x32-m32-osc-expert/references/address-catalog.md)
</div>
<div align="center">
<img src="docs/assets/social-preview.jpg" alt="X32/M32 OSC Skill preview">
[Overview](#overview) · [Capabilities](#capabilities) · [Install](#installation) · [Examples](#example-requests) · [Architecture](#skill-architecture) · [Validation](#validation) · [Security](#security-model)
</div>
---
## Overview
`x32-m32-osc-expert` is a standalone, progressively loaded Agent Skill for technical work involving Midas M32 and Behringer X32 digital mixing consoles.
It combines console-operation knowledge with an exact, source-traceable OSC reference layer. The Skill can explain hardware and control-surface workflows, resolve documented OSC addresses and parameter types, inspect effects and MIDI mappings, encode or decode OSC packets offline, diagnose communication faults, and prepare risk-classified dry-run change plans.
The repository contains **the Skill and its offline validation assets only**. It does not contain an MCP server, a live console transport, a hosted API, a schema registry, or an autonomous execution service.
> **Core rule:** Never invent undocumented commands. Never derive OSC addresses from UI labels, screenshots, menu paths, MIDI mappings, signal-flow labels, or common conventions.
## Why this project exists
X32/M32 integrations fail most often when three different concerns are mixed together:
1. **Console operation**: what the hardware and UI actually do.
2. **Protocol knowledge**: the exact OSC address, type, range, direction, and firmware context.
3. **Execution authority**: whether a state-changing action is permitted, verified, and reversible.
This Skill separates those concerns. It gives an agent a dependable knowledge and validation layer without granting it network access to a console.
## Capabilities
| Area | What the Skill provides |
|---|---|
| Console hardware | Control surface, channel strips, banks, layers, faders, encoders, rear-panel I/O, monitoring, talkback, USB, AES50, Ultranet, MIDI and power references |
| Main display and UI | Screen navigation, editable fields, meters, routing pages, setup, libraries, effects, utility functions and contextual behaviour |
| Signal flow | Inputs, buses, matrices, mains, inserts, effects, tap points, routing, monitoring and documented performance limits |
| OSC protocol | Exact address and node lookup, parameter types, argument order, ranges, units, read/write direction, replies and subscriptions |
| OSC codec | Offline encoding and decoding for documented `int32`, `float32`, string and blob forms |
| Effects | Effect inventory, slot restrictions, parameter tables, enums and documented control ranges |
| MIDI | MIDI operation, assignments, DAW-control notes and OSC-over-MIDI SysEx references |
| Diagnostics | Layered troubleshooting for identity, firmware, UDP behaviour, padding, type tags, subscriptions, client contention and state divergence |
| Safety policy | Read-before-write discipline, four-tier risk classification, dry-run planning and fail-closed handling |
| Traceability | Source file, page, section, classification, confidence, conflict and parse notes where available |
## Source authority
The Skill is grounded in two source families:
- The M32 manufacturer user manual for console hardware, UI, routing, effects, MIDI, specifications and block-diagram information.
- The **unofficial** X32/M32 OSC Remote Protocol reference for firmware 4.0 and later.
The OSC reference is operationally useful, but it is not vendor-authored and explicitly acknowledges possible inaccuracies. The Skill therefore preserves `EXPLICIT`, `DERIVED`, `UNCERTAIN`, `CONFLICT`, `NOT FOUND` and `UNREADABLE` classifications rather than silently repairing or completing the source.
See [Data provenance](docs/data-provenance.md) and [Licence scope](LICENSE_SCOPE.md).
## Coverage snapshot
| Dataset | Included |
|---|---:|
| OSC catalogue rows | 753 |
| Explicit OSC rows | 724 |
| Quarantined uncertain rows | 29 |
| X32node paths | 337 |
| Effect inventory rows | 95 |
| Unique effect codes | 61 |
| Effect parameter rows | 705 |
| Unified data-dictionary rows | 1,906 |
| MIDI rows | 16 |
| Console signal-flow edges | 24 |
| Engineering risk entries | 10 |
| Documentation gaps | 12 |
Machine-readable catalogues are under [`skill/x32-m32-osc-expert/data/`](skill/x32-m32-osc-expert/data/).
## Supported console families
The protocol reference describes the X32/M32 family across Standard, Compact, Rack, Producer and Core variants. Coverage is not identical for every model.
| Family or model | Coverage position |
|---|---|
| Midas M32 Standard | Strongest hardware, UI and operating coverage from the manufacturer manual |
| Midas M32 Compact / M32C | Protocol-family coverage; verify model-specific surface and I/O differences |
| Midas M32 Rack / M32R | Protocol-family coverage; no full physical-surface equivalence implied |
| Behringer X32 Standard | Protocol-family and surface-control reference coverage |
| Behringer X32 Compact / X32C | Protocol-family coverage with model-specific verification required |
| Behringer X32 Producer / X32P | Protocol-family coverage with model-specific verification required |
| Behringer X32 Rack / X32RACK | Protocol-family coverage with model-specific verification required |
| Behringer X32 Core / X32CORE | Historical protocol coverage; the source notes that the model was discontinued |
Always establish the console model and firmware before preparing a state-changing plan.
## Skill architecture
```mermaid
flowchart LR
U[User request] --> A[AI agent]
A --> S[SKILL.md control plane]
S --> R1[Hardware and UI references]
S --> R2[OSC and node catalogues]
S --> R3[Effects, MIDI and scaling references]
S --> P[Risk and safety policy]
R1 --> O[Source-grounded answer]
R2 --> O
R3 --> O
P --> O
S --> T[Offline deterministic scripts]
T --> L[Lookup]
T --> C[Encode or decode]
T --> V[Validate dry-run plan]
L --> O
C --> O
V --> O
O --> D[Explanation, diagnosis or dry-run plan]
D -. no live transport included .-> X[External authorised executor]
```
The dotted boundary is deliberate. This repository does not send UDP packets, alter console state, or claim that a transmitted packet was applied.
## Repository layout
```text
.
├── README.md
├── LICENSE
├── LICENSE_SCOPE.md
├── SECURITY.md
├── SCOPE_BOUNDARY.md
├── NOTICE.md
├── BUILD_REPORT.md
├── CHANGELOG.md
├── docs/
│ ├── installation.md
│ ├── usage.md
│ ├── publishing.md
│ ├── data-provenance.md
│ └── scope-and-integration.md
├── scripts/
│ ├── verify_repository.py
│ ├── build_release.py
│ ├── publish_github.sh
│ └── publish_github.ps1
├── skill/
│ └── x32-m32-osc-expert/
│ ├── SKILL.md
│ ├── agents/
│ ├── references/
│ ├── data/
│ ├── scripts/
│ ├── tests/
│ ├── evals/
│ └── adapters/
└── dist/
├── skill.zip
└── SHA256SUMS
```
## Installation
### ChatGPT
Download [`dist/skill.zip`](dist/skill.zip), then upload it through the Skills interface.
### Claude or Claude Code
Copy the canonical Skill directory:
```bash
mkdir -p .claude/skills
cp -R skill/x32-m32-osc-expert .claude/skills/
```
### GitHub Copilot or VS Code
Copy the Skill to a supported project-level skills directory:
```bash
mkdir -p .github/skills
cp -R skill/x32-m32-osc-expert .github/skills/
```
### Codex and Antigravity
Use the platform-specific instructions under:
```text
skill/x32-m32-osc-expert/adapters/
```
See the complete [Installation guide](docs/installation.md).
## Example requests
### Exact OSC lookup
```text
Find the documented OSC schema for channel 1 fader.
Return the address as printed, type tag, range, unit, direction,
firmware scope, source status and evidence. Do not infer missing fields.
```
### Console workflow
```text
Explain how Sends on Fader changes the M32 control surface.
Separate fixed controls, context-sensitive behaviour and display feedback.
```
### Diagnosis
```text
Diagnose why /xremote updates stop after several seconds.
Begin with read-only checks and distinguish timeout, client-limit,
packet-loss and state-reconciliation causes.
```
### Packet review
```text
Decode this OSC packet and compare it with the documented X32/M32 type rules.
Flag alignment, null-padding, endianness and type-tag problems.
```
### Safe change planning
```text
Prepare a dry-run plan to change a documented parameter.
Read the current state first, classify risk, show exact bytes,
define expected verification and provide rollback steps.
Do not send anything.
```
## Deterministic tools
Run tools from the canonical Skill directory:
```bash
cd skill/x32-m32-osc-expert
```
### Search OSC addresses
```bash
python scripts/lookup_osc.py --query "/ch/01/mix/fader" --json
```
### Search X32node paths
```bash
python scripts/lookup_node.py --query "/ch/01" --json
```
### Search effects
```bash
python scripts/lookup_effect.py --query "Hall Reverb" --json
```
### Encode an OSC message offline
```bash
python scripts/encode_osc.py \
--address "/ch/01/mix/fader" \
--types f \
--args 0.5
```
### Decode a packet offline
```bash
python scripts/decode_osc.py --hex "2f696e666f0000002c000000"
```
### Validate a proposed write
```bash
python scripts/validate_write.py \
--address "/ch/01/mix/fader" \
--value 0.5
```
These scripts do not open a socket or transmit to a console.
## Validation
Run the complete repository validation:
```bash
python scripts/verify_repository.py
```
Expected result:
```json
{
"status": "PASS",
"errors": []
}
```
Build a fresh distributable:
```bash
python scripts/build_release.py
```
Verify its checksum:
```bash
shasum -a 256 dist/skill.zip
cat dist/SHA256SUMS
```
The validation workflow covers:
- external-reference audit
- dataset coverage
- Skill structure and frontmatter
- deterministic unit tests
- clean-extraction validation
- scope-boundary enforcement
- absence of public schema identifiers
- absence of bundled MCP or live-transport implementation
Detailed results are recorded in [BUILD_REPORT.md](BUILD_REPORT.md).
## Security model
This repository is intentionally offline-first.
It does **not** include:
- a live UDP or OSC sender
- an MCP server
- a cloud API or hosted endpoint
- authentication or secret management
- firmware-update tooling
- autonomous scene recall
- phantom-power execution
- media-format or destructive operations
- a public JSON Schema registry
Any external execution system must independently provide console identity checks, firmware compatibility, current-state reads, operator approval, rate limits, post-write verification, rollback, audit and a physical override.
Read [SECURITY.md](SECURITY.md) and [SCOPE_BOUNDARY.md](SCOPE_BOUNDARY.md) before integrating the Skill into a control system.
## Four-tier risk policy
| Tier | Meaning | Default policy |
|---|---|---|
| Tier 0 | Observe and read-only operations | No write approval required |
| Tier 1 | Bounded, reversible, allow-listed changes | Dry run, current-state read, limits and verification |
| Tier 2 | High operational impact | Explicit human approval and recovery plan |
| Tier 3 | Critical, destructive or uncertain | Fail closed; no autonomous execution |
Unknown, undocumented, `UNCERTAIN`, `CONFLICT` or unreadable write operations never qualify as Tier 0 or Tier 1.
## Contributing
Contributions are welcome when they preserve source traceability and the no-invention rule.
Before opening a pull request:
```bash
python scripts/verify_repository.py
```
A contribution that adds or changes a technical fact should include:
- the source document and edition
- PDF and printed page where applicable
- the exact source form
- status and confidence
- a conflict or parse note when needed
- updated tests and coverage data
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Publishing
Publishing scripts require an explicit owner, repository name and visibility. They perform a safe validation pass before any Git mutation.
Dry run:
```bash
./scripts/publish_github.sh \
--owner DXBMARK \
--repo x32-m32-osc-skill \
--visibility private \
--dry-run
```
Real publishing requires an exact typed confirmation and verifies the existing `origin` before creating a commit or pushing.
See [Publishing guide](docs/publishing.md).
## Licence and attribution
The original scripts, tests, repository automation and authored Skill framework are licensed under the [MIT License](LICENSE).
Third-party manuals, trademarks, product names, protocol facts and supplied source documents remain under their original rights. Midas and Behringer are trademarks of their respective owners. This project is independent and is not endorsed by, affiliated with or supported by the equipment manufacturers.
See [LICENSE_SCOPE.md](LICENSE_SCOPE.md), [NOTICE.md](NOTICE.md) and [CITATION.cff](CITATION.cff).
## Support
- Report reproducible problems through [GitHub Issues](https://github.com/DXBMARK/x32-m32-osc-skill/issues).
- Review known limitations in [BUILD_REPORT.md](BUILD_REPORT.md).
- Read [SECURITY.md](SECURITY.md) before reporting a security concern.
- General project information: [dxbmark.com](https://www.dxbmark.com).
---
<div align="center">
<img src="docs/assets/ascii-signature.png" alt="DXBMARK ASCII signature" width="520">
<br><br>
**Engineered by DXBMARK LLC**
Copyright © 2026 DXBMARK LLC. All rights reserved.
</div>
<!-- Validation signature:
# ______ ______ __ __ _ ____ _ __
# | _ \ \/ / __ )| \/ | / \ | _ \| |/ / LLC
# | | | \ /| _ \| |\/| | / _ \ | |_) | ' /
# | |_| / \| |_) | | | |/ ___ \| _ <| . \
# |____/_/\_\____/|_| |_/_/ \_\_| \_\_|\_\ dxbmark.com
-->