// 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. 9,925 source lines (8,484 code) across 20 Rust files, a worker-thread engine, a faithful BOME rules VM, lossless .bmtp import + export, and a broad protocol I/O layer — the routing core behind a MIDI-controlled desktop application.

#SUBSYSTEM BREAKDOWN

Source partitioned by role. The engine (worker thread + dispatch + protocol sources + generators + timers) is the largest slice at 42.1%; .bmtp import + export is second at 15.5% 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 13.3% as the trigger/action set expanded to 26 incoming + 39 outgoing variants. The rules VM is a self-contained 723-line interpreter.

$FILES BY SIZE

All 20 Rust source files, largest first. The engine dominates; the four bmtp/ files together (1,540 lines) are the cost of natively reading and re-writing BOME's binary project container.

@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   │
  │   (88)      │     │   (97)      │     │   (600)      │
  │  message    │     │  per-entry  │     │  integer VM  │
  │  types      │     │  trigger    │     │  10 locals   │
  │  midir port │     │  match +    │     │  globals     │
  │             │     │  capture    │     │  IF/Goto     │
  └─────────────┘     └─────────────┘     └──────┬───────┘
                                                  │
                              ┌────────────────────┤
                              │                    │
                              ▼                    ▼
                     ┌──────────────┐     ┌──────────────┐
                     │ engine/mod   │     │  actions/    │
                     │   (996)      │     │   (423)      │
                     │  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/. Numbers refresh as the crate adds commits.