// ZTRANSLATOR — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

ztranslator is a self-contained, real-time MIDI translation engine written in pure Rust, meant to be embedded inside a host GUI/CLI application. It listens on MIDI input ports (via midir), matches each incoming message against per-translator triggers, runs a rules script on a small signed-32-bit integer VM, and fires an outgoing action — one of 39 Outgoing variants spanning MIDI out (incl. 14-bit / NRPN), keystroke / mouse / AppleScript synthesis (macOS), MIDI route / port / project control, MIDI clock + MTC generators, MMC transport, OSC, Art-Net + sACN DMX, HTTP / WebSocket / MQTT / raw TCP, RTP-MIDI, Ableton Link, CV / gate, gamepad rumble, serial, file write, notify / speak / clipboard, timer, preset control, a host-defined custom command, and a stryke-script hook. Beyond MIDI it accepts 26 incoming trigger types (OSC, DMX, sACN, serial, gamepad, HID, MIDI clock, MTC, MMC, Ableton Link, audio amplitude/onset/pitch, CV/gate, cron schedule, system events, HTTP, TCP, WebSocket, MQTT, RTP-MIDI). It imports BOME MIDI Translator Pro .bmtp projects (INI container + MID3/KAM3 XML payloads + Options rules blob) and exports native projects back to unsigned .bmtp (round-tripping through import), with serde JSON as the native store. The crate carries no UI of its own: the host wires the engine's EngineEvent stream to its interface and routes Outgoing::Custom back through a handler. Layered on top of the raw byte is a pure music / MIDI 2.0 layer that no remapper ships: note-name and chord/scale theory, enharmonic spelling, voicing and inversion, tuning (12-TET, cents, Scala .scl, MTS), MPE zones, GM program and percussion maps, CC naming and 14-bit pairing, a channel routing matrix, SysEx builders, Standard MIDI File primitives, running-status stream framing, MIDI 2.0 UMP codecs, value transforms and smoothing, LFO / ADSR generators, groove and strum, and arpeggiator / step-sequencer models. 13,062 source lines (10,556 code) across 40 Rust files, a worker-thread engine, a faithful BOME rules VM, lossless .bmtp import + export, a broad protocol I/O layer, and a music-theory layer — the routing core behind a MIDI-controlled desktop application.

#SUBSYSTEM BREAKDOWN

Source partitioned by role. The music / MIDI 2.0 layer is now the largest slice at 31.8% — twenty pure, unit-tested modules (theory, spelling, voicing, tuning, MPE, GM program + drum maps, CC map, channel matrix, SysEx, SMF, stream framing, MIDI 2.0 UMP, transform, smooth, timing, clock, generators, groove, arp) that have no BOME counterpart. The engine (worker thread + dispatch + protocol sources + generators + timers) is second at 27.8%; .bmtp import + export is 10.7% because BOME's binary container format needs dedicated INI / XML / options parsers on the way in and an unsigned re-serializer on the way out. The data model is 9.1%, carrying 28 Incoming and 41 Outgoing variants (26 trigger types and 39 actions, plus Raw and None in each). The rules VM is a self-contained 644-line interpreter.

$FILES BY SIZE

All 40 Rust files (37 under src/, 3 under tests/), largest first. The engine dominates a single file; the four bmtp/ files together (1,396 lines) are the cost of natively reading and re-writing BOME's binary project container; the twenty music / MIDI 2.0 modules (4,154 lines) are pure and independently testable.

@EXECUTION PIPELINE

An incoming MIDI message flows through four stages on the engine's worker thread. The matcher selects translators whose Incoming trigger fits the message; each match runs its rules on the integer VM; the resulting Outgoing action is dispatched to MIDI out, the OS action layer, the timer scheduler, or the host's custom handler.

  MIDI in (midir input port)
       │
       ▼
  ┌─────────────┐     ┌─────────────┐     ┌──────────────┐
  │  midi.rs    │────▶│  matcher.rs │────▶│   rules.rs   │
  │   (127)     │     │   (117)     │     │   (644)      │
  │  message    │     │  per-entry  │     │  integer VM  │
  │  types      │     │  trigger    │     │  10 locals   │
  │  midir port │     │  match +    │     │  globals     │
  │             │     │  capture    │     │  IF/Goto     │
  └─────────────┘     └─────────────┘     └──────┬───────┘
                                                  │
                              ┌────────────────────┤
                              │                    │
                              ▼                    ▼
                     ┌──────────────┐     ┌──────────────┐
                     │ engine/mod   │     │  actions/    │
                     │  (3,536)     │     │   (441)      │
                     │  dispatch    │────▶│  CGEvent     │
                     │  event sink  │     │  keystroke   │
                     │  custom      │     │  mouse/wheel │
                     │  handler     │     │  AppleScript │
                     └──────┬───────┘     └──────────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
       ┌──────▼──────┐ ┌────▼──────┐ ┌────▼────────┐
       │ midir out   │ │ timers.rs │ │ host custom │
       │ + route/    │ │   (90)    │ │ + stryke    │
       │ port/proj   │ │ scheduler │ │ hook        │
       └─────────────┘ └───────────┘ └─────────────┘

&RULES VM — BOME SEMANTICS

The rules language is a faithful reimplementation of BOME MIDI Translator Pro's rules, run on a small signed-32-bit integer VM. The behaviors below are pinned by tests/rules_vm.rs so refactors can't silently diverge from BOME.

+DEPENDENCIES

23 direct dependencies — 19 cross-platform, 4 macOS-only. No async runtime: the engine runs on a single dedicated worker thread and talks to the host over crossbeam-channel.

Line counts measured with tokei 14.0.0 + wc -l across src/ + tests/; test-function count is #[test] attributes in the same trees. Numbers refresh as the crate adds commits.