Dave

Dave is an experimental, schema-first framework for safely controlling music hardware from software agents. It translates semantic intent such as “make oscillator two an octave lower” into the MIDI, SysEx, USB, or OSC messages understood by a particular device.

The project is not affiliated with or endorsed by any hardware manufacturer.

Why Go

Go is the primary implementation language because the runtime needs to be a small, dependable system process rather than part of a browser or agent prompt. It is a good fit for:

• portable single-binary distribution;
• concurrent MIDI, USB, OSC, and network sessions;
• explicit state machines, timeouts, pacing, and reconnect behavior;
• deterministic digital twins and trace replay;
• safety gates around persistent writes, motors, calibration, and firmware;
• MCP over stdio or HTTP without requiring a JavaScript runtime.

Device capability catalogs and UI semantics are deliberately kept out of Go in portable JSON profiles governed by JSON Schema. Small, security-sensitive wire codecs remain compiled and fixture-tested. A TypeScript SDK and generated web interfaces can consume the same profiles later without redefining device semantics.

Architecture

natural-language agent / generated UI / CLI
                    |
              semantic API
                    |
       capability + safety runtime (Go)
                    |
      device profile + protocol adapter
                    |
       MIDI | SysEx | USB | OSC | network
                    |
              physical hardware

The core abstraction is not a universal getState/setState pair. Each state scope declares the operations it actually supports, its authority, and its constraints. A device may expose an observable runtime value, a queryable edit buffer, a writable stored program, or only host-owned output state; those are not interchangeable guarantees.

See docs/architecture.md for the design, ADR 0001 for the Go/Rust/Zig decision, and docs/target-hardware.md for the researched starting portfolio.

The phased delivery plan and safety gates are in docs/implementation-plan.md.

Repository status

M0 through M2 and the first CoreMIDI read-only M3 slice are implemented:

• a bounded, versioned device-profile schema and fail-closed Go validator;
• a deterministic semantic planner with scope, safety, acknowledgement, and target-specific verification checks;
• pure MIDI CC, 14-bit NRPN, Circuit Tracks patch SysEx, and read-only Yamaha M identity, parameter, checksum-aware bulk, and transaction codecs;
• strict Sequential Take 5 identity, CC/NRPN, and program/edit-buffer codecs;
• a wire compiler with ordered frames, pacing, and compiled Circuit Tracks readback matching, without opening a MIDI or USB device;
• bounded NDJSON traces plus deterministic Circuit Tracks, Take 5, Yamaha M, and X-Touch twins with reconnect/replay tests;
• a native macOS CoreMIDI backend that exposes only endpoint discovery, listening, and adapter-registered read queries;
• identity-pinned compound reads with per-step causal receipts and bounded multi-frame collectors;
• a read-only community capture format whose exact profile, every compiled query step, endpoint correlation, collector replay, terminal report, case claims, sizes, and digests are verified offline.

Every current plan says "dryRun": true and "executable": false. Request acknowledgements help inspect dangerous plans, but are not execution authority. The physical transport cannot send arbitrary caller bytes and is not a plan executor: it accepts only fixed queries compiled into a trusted adapter. No volatile or persistent hardware writes, motors, calibration, or firmware operations are exposed. The contracts are v0alpha1 and will change as real hardware traces expose firmware behavior.

Try it

Validate the example profile:

go run ./cmd/dave profile validate examples/devices/novation.circuit-tracks.json

Compile a semantic request into an inspectable dry-run plan:

go run ./cmd/dave plan \
  --profile examples/devices/novation.circuit-tracks.json \
  --request examples/requests/circuit-tracks-filter.json

Compile a read-only current-workstation query:

go run ./cmd/dave plan \
  --profile examples/devices/yamaha.montage-m.json \
  --request examples/requests/montage-m-performance-name.json

Compile the full read-only Performance bulk request:

go run ./cmd/dave plan \
  --profile examples/devices/yamaha.montage-m.json \
  --request examples/requests/montage-m-performance-bulk.json

Run the tests:

go test ./...

Community members can validate a redacted read-only evidence directory without opening hardware:

go run ./cmd/dave conformance verify ./evidence-bundle

On macOS, list unambiguous duplex CoreMIDI endpoint pairs without sending data:

go run ./cmd/dave midi list

Hardware owners can then run one registered read-only query and create a new, private evidence directory. For example:

go run ./cmd/dave conformance capture \
  --endpoint 'coremidi:entity:…:source:…:destination:…' \
  --profile examples/devices/sequential.take-5.json \
  --query take5.identity \
  --firmware unknown \
  --output ./take5-evidence \
  --license CC0-1.0 \
  --consent-to-share

Device responses can contain the current patch. Inspect the private bundle before publishing it.

See docs/community-verification.md and the hardware validation gates.

Initial implementation order

1. Stabilize the profile and session contracts against the X-Touch digital twin. (Implemented.)
2. Implement Circuit Tracks as the first packed-format adapter and bounded synth twin. (Implemented.)
3. Implement Sequential Take 5 as the first spec-first synthesizer adapter, leaving ambiguous packed-byte semantics disabled. (Implemented.)
4. Implement current Yamaha MONTAGE M and MODX M workstation identity, identity-pinned Performance name, and bounded device-0 multi-frame Performance capture. (Implemented to the specification-validation boundary; physical traces are the next gate.)
5. After Yamaha hardware validation, evaluate read-only Roland FANTOM EX and Korg KRONOS slices under their documentation-license constraints.
6. Implement monome grid and Launch Control XL 3, then add Push 2 and Electra One to exercise OSC, conventional MIDI surfaces, a raw USB framebuffer, generated UI, and transactions.

Confidence vocabulary

• spec-validated: derived from authoritative documentation and tested against golden messages or a simulator;
• trace-validated: compared with captures from a real device or official editor;
• hardware-validated: exercised end-to-end on declared hardware and firmware.

Adapters must publish their confidence per state scope. Supporting one complete patch format must never be presented as supporting the complete device.