ztranslator-core — Embeddable Event-Translation Engine

ztranslator-core is the embeddable engine behind ztranslator, the real-time event-translation tool. It owns the Project > Preset > Translator data model, the trigger sources, the rules VM, the BOME .bmtp importer/exporter, and the outgoing action executors — with no GUI and no IPC layer of its own, so the desktop app and every embed share the exact same routing code. The deterministic core (model, rules, BOME import/export) builds on all platforms; OS-control executors (keystroke, mouse, AppleScript) are macOS-only and no-op elsewhere. Created by MenkeTechnologies.

Embeddable

The library crate (ztranslator) links natively into Rust/Tauri hosts. A sibling ztranslator-capi crate builds rlib + staticlib + cdylib and exposes a generic zt_invoke(cmd, args_json) C ABI plus an event callback for non-Tauri hosts (a JUCE host such as zpwr-daw).

Integer rules VM

Per-translator rules run on a signed-32-bit integer VM: arithmetic + bitwise ops, IF/THEN, Goto/Label, SkipNext, exit-execute / exit-ignore, with locals and globals. Rules parse from text and format back to source.

BOME + JSON projects

Imports and exports BOME MIDI Translator Pro .bmtp projects and stores native projects as JSON via Project::load_json / save_json.

What it does

trigger source → match against a translator's Incoming spec → run its rules on the VM → Outcome::Execute fires the Outgoing action, Outcome::Ignore drops it.

Trigger sources implemented in the engine include MIDI input (via midir), OSC, Art-Net & sACN DMX, filesystem watchers, serial, gamepad, generic USB-HID, HTTP / WebSocket / MQTT / raw TCP servers, cron schedules, system-event polling, audio level (macOS), and Ableton Link beats. Outgoing actions include MIDI out, OSC, DMX, keystroke, mouse, AppleScript, clipboard, notify, speak, play-sound, launch-file, HTTP request, timer, preset / project / router control, set-var, and a host-command escape hatch (Custom / Stryke handlers). See the engineering report for the full module map and the exact Incoming / Outgoing variant counts.

Quick start (Rust host)

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

let mut engine = Engine::new(EngineConfig { client_name: "myhost".into() })?;
engine.set_event_sink(|ev| println!("{ev:?}"));

let project = ztranslator::bmtp::import("Tutorial.bmtp")?; // or Project::load_json(...)
engine.load_project(project);

engine.open_input("IAC Bus 1")?;
engine.start()?;        // worker thread now translates live events
// ...
engine.project().save_json("project.json")?;

Quick start (C ABI host)

/* link ztranslator_capi (cdylib / staticlib) and include ztranslator_capi.h */
zt_set_event_callback(on_event);            /* JSON EngineEvent per call */
char* r = zt_init(); zt_string_free(r);     /* create engine + wire the sink */
char* res = zt_invoke('ztr_list_ports', '{}');
/*  -> [{'name':'...','direction':'input','state':'open'}, ...] or {'error':'...'} */
zt_string_free(res);

See the engineering report for the module map, dependency footprint, C-ABI surface, and test status. Source lives at github.com/MenkeTechnologies/ztranslator-core; the umbrella stack is MenkeTechnologiesMeta.

ZTRANSLATOR-CORE // EMBEDDABLE EVENT-TRANSLATION ENGINE