@tsi-forge/core

Deterministic encode/decode of Traktor .tsi controller-mapping files, in pure TypeScript.

The reverse-engineered binary .tsi format (big-endian frames, base64-wrapped in XML) behind a typed, round-trippable API — plus the Allen & Heath Xone:K3 layout and the Traktor action catalog. No I/O beyond reading its bundled template; no LLM dependency.

Part of tsi-forge. v1 scope: Xone:K3 + Traktor Pro 3.

Install

npm install @tsi-forge/core

Example

import {
  generateMappingTemplate,
  validateMapping,
  encodeMappingToTsi,
  tsiToMappingJson,
  getTraktorAction,
} from "@tsi-forge/core";

// 1. Start from the Xone:K3 factory layout (layer 1), one entry per control.
const json = generateMappingTemplate("xone-k3", 1);

// 2. Point a control at a Traktor action (ids from the catalog).
const fader1 = json.mappings.find((m) => m.comment === "Fader 1")!;
fader1.action = 102;          // Volume Adjust  → getTraktorAction(102)
fader1.targetDeck = "A";
fader1.interactionMode = "Direct";

// 3. Validate, then render an importable .tsi.
const report = validateMapping(json);
if (!report.ok) throw new Error(JSON.stringify(report.issues));
const tsi = encodeMappingToTsi(json);   // → full XML .tsi string

// Round-trips: decode is the exact inverse.
const back = tsiToMappingJson(tsi);

API surface

• encodeMappingToTsi(json) / tsiToMappingJson(tsi) — MappingJSON ⇄ importable .tsi.
• generateMappingTemplate(controllerId, layer) — a skeleton with factory bindings, actions left as -1.
• validateMapping(json) — { ok, issues } schema + semantic report.
• MappingJson — the zod schema (and inferred type) for the document.
• Catalogs: xoneK3, getControllerLayout(id), traktorActions, getTraktorAction(id).
• Low level: the typed document tree + frame codecs and the decode/encode binary primitives, for direct .tsi surgery.

Guarantee

decode(encode(x)) is byte-exact for the reference fixtures — verified by the test suite. Runtime is plain-Node compatible (no Bun APIs).

License

MIT.