// ZTRANSLATOR — REAL-TIME MIDI ROUTING ENGINE

Pipeline

An incoming MIDI message flows through four stages on a dedicated worker thread:

MIDI in ──▶ matcher ──▶ rules VM ──▶ outgoing action
 (midir)    (per-entry)  (integer)   (MIDI / keys / mouse / AppleScript / timer / custom)

The engine owns the open input ports (midir) and emits EngineEvents back to the host through a sink callback. Actions the host wants to handle itself route through Outgoing::Custom { command } plus a host-installed handler — so the engine maps MIDI to host commands without being modified.

Embedding

The crate is a library (ztranslator). A host wires the engine's events to its own UI and IPC:

use ztranslator::{Engine, EngineConfig, EngineEvent};

let mut engine = Engine::new(EngineConfig::default())?;
engine.set_event_sink(|ev: EngineEvent| { /* forward to UI */ });
engine.set_custom_handler(|cmd: String| { /* host-defined actions */ });

let project = ztranslator::bmtp::import("Ableton.bmtp")?;
engine.load_project(project);
engine.start()?;
engine.open_input("nanoKONTROL2 SLIDER/KNOB")?;

Data model

Project → Preset → Translator, where each Translator carries:

The model is serde-serializable; native projects are stored as JSON via Project::load_json / Project::save_json. Presets group translators and can be switched at runtime.

Rules language

A faithful implementation of BOME's rules language, compiled and run on a small signed-32-bit integer VM:

Values wrap on overflow; division / modulo by zero yields 0 — matching BOME's documented semantics exactly. These behaviors are pinned by tests/rules_vm.rs.

.bmtp import + export

bmtp::import(path) parses BOME MIDI Translator Pro project files: the INI container, MID3 / KAM3 XML payloads, timer / EnDi payloads, and the Options rules blob. Export re-serializes a Project back to an unsigned .bmtp that round-trips through import. The RSA signature section is not produced, so a signed export for BomeBox / MT Player is out of scope — the native store is JSON.

Import is lossless: encodings whose binary layout is not yet decoded (older MID1 MIDI, KAM1 keystrokes, mouse, serial, launch) are preserved verbatim, so a project round-trips even when individual entries are not yet natively understood.

Music & MIDI 2.0 layer

Twenty pure, side-effect-free modules sit on top of the raw MIDI byte. They hold no state and open no ports, so each is unit-tested in isolation and callable from a rule, from the host, or from the editor. Nothing in this layer has a BOME counterpart — BOME treats a note as a bare 0–127 integer.

Outgoing actions & platforms

The Outgoing enum has 41 variants:

MIDI I/O and the rules / import core build on all platforms. OS-control actions are macOS-only and require the host application to hold Accessibility permission (System Settings → Privacy & Security → Accessibility). actions::accessibility_trusted() reports the grant; executors return Error::NeedsAccessibility when it is missing.

Architecture

The crate is 40 Rust files — 37 under src/ plus 3 integration modules under tests/ — totalling 13,062 source lines (10,556 code). See the engineering report for the full subsystem and per-file breakdown.