feat(backends): add VcvBackend driving + training the VCV module over the OSC-WS bridge
This commit is contained in:
monkey-w1n5t0n
parent
19b7f7eee8
commit
f05669969f
1 changed files with 270 additions and 0 deletions
270
manifold/src/backends/vcv-backend.ts
Normal file
270
manifold/src/backends/vcv-backend.ts
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
/**
|
||||
* VcvBackend — drives + trains the VCV Rack NISPS module over the OSC↔WS bridge
|
||||
* (backends-spec §2.6; vcv/SPEC.md OSC verbs). In "bridged" mode the BROWSER is
|
||||
* authoritative: it streams the current input vector to the module and forwards
|
||||
* the verdict loop (thumbs up/down, explore-and-place) so the module's embedded
|
||||
* net trains in lock-step with the browser session.
|
||||
*
|
||||
* Transport (reuses {@link NispsOscClient} → the Deno bridge in
|
||||
* manifold/osc-bridge, default ws://localhost:8765, default module UDP 7001):
|
||||
*
|
||||
* browser → module
|
||||
* /nisps/input <f…f> the current 2-D input vector (drives the module)
|
||||
* /nisps/output <f…f> per-output values (CV) — sent as params batch so
|
||||
* the bridge maps each to /nisps/<name>; the module
|
||||
* also derives its own outputs, but the browser
|
||||
* value is authoritative in bridged mode
|
||||
* /nisps/feedback {op,…} verdict op (up | down | rand | clear) as JSON
|
||||
* state — { op, spread, input[], output[] }
|
||||
*
|
||||
* module → browser
|
||||
* /nisps/output <f…f> module's live outputs (status / visualisation)
|
||||
* /nisps/input <f…f> module's live inputs (echo / status)
|
||||
* /nisps/state <json> module status snapshot (surfaced as a message)
|
||||
*
|
||||
* The bridge process AND the VCV module must both be running — until the WS
|
||||
* connects we surface "bridge not running"; until the module replies we stay
|
||||
* "connected, waiting for module".
|
||||
*
|
||||
* British spelling in product copy; the synth is the "Built-in Synth", never
|
||||
* "C15".
|
||||
*/
|
||||
import type { BackendContext, BackendStatus, OutputBackend } from './backend';
|
||||
import { isSilent, mapOutput } from './mapping';
|
||||
import { NispsOscClient } from './osc-client';
|
||||
import type { VcvSpec } from '../dock/output-state';
|
||||
|
||||
const SEND_INTERVAL_MS = 50;
|
||||
const DEAD_ZONE = 0.002; // on the normalised value, pre physical-scale
|
||||
|
||||
/** A verdict op forwarded to the module's embedded learner. */
|
||||
export interface VcvFeedbackOp {
|
||||
op: 'up' | 'down' | 'rand' | 'clear';
|
||||
/** Master spread (0..1) — mirrors the engine spread knob. */
|
||||
spread: number;
|
||||
/** The control input the verdict was given at (2-D). */
|
||||
input: number[];
|
||||
/** The heard output vector at that input (≤126 dims). */
|
||||
output: number[];
|
||||
}
|
||||
|
||||
export interface VcvBackendConfig {
|
||||
/** Bridge WebSocket URL (the bridge then relays to the module over UDP). */
|
||||
url: string;
|
||||
/** Send raw normalised 0..1 instead of the per-output bipolar/unipolar range. */
|
||||
sendRaw: boolean;
|
||||
}
|
||||
|
||||
export class VcvBackend implements OutputBackend {
|
||||
readonly id = 'vcv' as const;
|
||||
|
||||
private client = new NispsOscClient();
|
||||
private ctx: BackendContext | null = null;
|
||||
private specs: VcvSpec[] = [];
|
||||
private sendRaw = false;
|
||||
|
||||
/** Latest input vector the browser is driving the module with (2-D). */
|
||||
private inputVec: number[] = [0.5, 0.5];
|
||||
|
||||
private lastSent: Float32Array = new Float32Array(0); // last normalised output
|
||||
private batch: Array<[string, number]> = []; // reused outer; entries reused
|
||||
private lastSendMs = 0;
|
||||
private lastInputSent: [number, number] = [-1, -1];
|
||||
|
||||
/** Latest module-reported outputs (for visualisation), null until first echo. */
|
||||
private moduleOutputs: number[] | null = null;
|
||||
private gotModuleReply = false;
|
||||
|
||||
private statusState: BackendStatus = { state: 'idle', message: 'VCV idle' };
|
||||
private statusListeners = new Set<(s: BackendStatus) => void>();
|
||||
private outputListeners = new Set<(v: number[]) => void>();
|
||||
private offConn: (() => void) | null = null;
|
||||
private offInfo: (() => void) | null = null;
|
||||
private offOutputs: (() => void) | null = null;
|
||||
private offInputs: (() => void) | null = null;
|
||||
|
||||
isAvailable(): boolean {
|
||||
return typeof WebSocket !== 'undefined';
|
||||
}
|
||||
|
||||
async start(ctx: BackendContext): Promise<void> {
|
||||
this.ctx = ctx;
|
||||
this.lastSent = new Float32Array(ctx.outputCount).fill(-1);
|
||||
if (!this.isAvailable()) {
|
||||
this.setStatus({ state: 'unavailable', message: 'WebSocket not available' });
|
||||
return;
|
||||
}
|
||||
this.offConn = this.client.onConnectionChange((connected) => {
|
||||
if (!connected) {
|
||||
this.gotModuleReply = false;
|
||||
this.setStatus({ state: 'error', message: `VCV bridge not running — start it (${this.client.url})` });
|
||||
return;
|
||||
}
|
||||
this.setStatus({
|
||||
state: this.gotModuleReply ? 'ready' : 'connecting',
|
||||
message: this.gotModuleReply
|
||||
? `VCV module connected (${this.client.url})`
|
||||
: `Bridge connected (${this.client.url}) — waiting for module…`,
|
||||
});
|
||||
});
|
||||
this.offInfo = this.client.onInfo((m) => {
|
||||
if (this.client.connected && !this.gotModuleReply) {
|
||||
this.setStatus({ state: 'connecting', message: m });
|
||||
}
|
||||
});
|
||||
// Module → browser: a reply on either channel proves the module is alive.
|
||||
this.offOutputs = this.client.onOutputsReceived((v) => this.onModuleReply(v, true));
|
||||
this.offInputs = this.client.onInputsReceived((v) => this.onModuleReply(v, false));
|
||||
|
||||
this.setStatus({ state: 'connecting', message: `Connecting to VCV bridge (${this.client.url})…` });
|
||||
this.client.connect({ reconnect: true }).catch(() => {
|
||||
this.setStatus({ state: 'error', message: `VCV bridge not running — start it (${this.client.url})` });
|
||||
});
|
||||
}
|
||||
|
||||
setContext(ctx: BackendContext): void {
|
||||
this.ctx = ctx;
|
||||
if (this.lastSent.length !== ctx.outputCount) {
|
||||
this.lastSent = new Float32Array(ctx.outputCount).fill(-1);
|
||||
}
|
||||
}
|
||||
|
||||
/** Update per-output VCV specs (polarity) + bridge URL/raw toggle. */
|
||||
setVcvConfig(specs: VcvSpec[], cfg: VcvBackendConfig): void {
|
||||
this.specs = specs;
|
||||
this.sendRaw = cfg.sendRaw;
|
||||
if (cfg.url !== this.client.url) {
|
||||
this.client.setUrl(cfg.url);
|
||||
this.gotModuleReply = false;
|
||||
if (this.isAvailable()) {
|
||||
this.setStatus({ state: 'connecting', message: `Connecting to VCV bridge (${cfg.url})…` });
|
||||
this.client.connect({ reconnect: true }).catch(() => {
|
||||
this.setStatus({ state: 'error', message: `VCV bridge not running — start it (${cfg.url})` });
|
||||
});
|
||||
}
|
||||
}
|
||||
this.lastSent.fill(-1);
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the input vector the browser drives the module with (bridged mode). The
|
||||
* next `send()` streams it to /nisps/input. Copied — caller may mutate.
|
||||
*/
|
||||
setInputVector(vec: ReadonlyArray<number>): void {
|
||||
if (this.inputVec.length !== vec.length) this.inputVec = new Array(vec.length);
|
||||
for (let i = 0; i < vec.length; i++) this.inputVec[i] = vec[i];
|
||||
}
|
||||
|
||||
/**
|
||||
* Forward a verdict op to the module's embedded learner over /nisps/feedback.
|
||||
* Hooked from the BackendManager when the verdict loop fires in VCV mode, so
|
||||
* thumbs-up/down + explore-and-place train the module across the bridge.
|
||||
*/
|
||||
sendFeedback(op: VcvFeedbackOp): void {
|
||||
if (!this.client.connected) return;
|
||||
// The bridge ships `{ type:'state', payload }` as an OSC string to
|
||||
// /nisps/state. We reuse that string channel for /nisps/feedback by tagging
|
||||
// the payload with a `feedback` envelope the module routes accordingly.
|
||||
this.client.sendState({ feedback: op });
|
||||
}
|
||||
|
||||
send(routed: Float32Array): void {
|
||||
const ctx = this.ctx;
|
||||
if (!ctx || !this.client.connected) return;
|
||||
|
||||
const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
|
||||
if (now - this.lastSendMs < SEND_INTERVAL_MS) return;
|
||||
this.lastSendMs = now;
|
||||
|
||||
// 1) Stream the current input vector so the browser drives the module.
|
||||
const ix = this.inputVec[0] ?? 0.5;
|
||||
const iy = this.inputVec[1] ?? 0.5;
|
||||
if (Math.abs(ix - this.lastInputSent[0]) >= DEAD_ZONE || Math.abs(iy - this.lastInputSent[1]) >= DEAD_ZONE) {
|
||||
this.lastInputSent[0] = ix;
|
||||
this.lastInputSent[1] = iy;
|
||||
// The bridge maps `input` → /nisps/input <f…f> (its `inputs` relay path).
|
||||
this.client.sendParams([
|
||||
['input', ix],
|
||||
['input', iy],
|
||||
]);
|
||||
}
|
||||
|
||||
// 2) Stream the routed per-output values (authoritative CV in bridged mode).
|
||||
const n = Math.min(routed.length, ctx.mappings.length);
|
||||
this.batch.length = 0;
|
||||
for (let i = 0; i < n; i++) {
|
||||
const m = ctx.mappings[i];
|
||||
if (isSilent(m)) continue;
|
||||
const mapped = mapOutput(routed[i], m); // 0..1 in [min,max]
|
||||
const prev = this.lastSent[i];
|
||||
if (prev >= 0 && Math.abs(mapped - prev) < DEAD_ZONE) continue;
|
||||
this.lastSent[i] = mapped;
|
||||
const spec = this.specs[i];
|
||||
const value = this.sendRaw ? mapped : this.toVoltage(mapped, spec);
|
||||
const name = ctx.names[i] ? sanitise(ctx.names[i]) : `out${i}`;
|
||||
this.batch.push([name, value]);
|
||||
}
|
||||
if (this.batch.length) this.client.sendParams(this.batch);
|
||||
}
|
||||
|
||||
/** Map a 0..1 value into the per-output VCV voltage range (uni/bipolar). */
|
||||
private toVoltage(v: number, spec: VcvSpec | undefined): number {
|
||||
// Unipolar 0..10 V; bipolar ±5 V (dock-spec §4.3 polarity).
|
||||
return spec?.bipolar ? v * 10 - 5 : v * 10;
|
||||
}
|
||||
|
||||
/** Latest module-reported output vector for visualisation (may be null). */
|
||||
moduleStatusOutputs(): number[] | null {
|
||||
return this.moduleOutputs;
|
||||
}
|
||||
|
||||
/** Subscribe to module-reported outputs (visualisation feed). */
|
||||
onModuleOutputs(cb: (v: number[]) => void): () => void {
|
||||
this.outputListeners.add(cb);
|
||||
return () => this.outputListeners.delete(cb);
|
||||
}
|
||||
|
||||
private onModuleReply(v: number[], isOutput: boolean): void {
|
||||
if (!this.gotModuleReply) {
|
||||
this.gotModuleReply = true;
|
||||
this.setStatus({ state: 'ready', message: `VCV module connected (${this.client.url})` });
|
||||
}
|
||||
if (isOutput) {
|
||||
this.moduleOutputs = v;
|
||||
for (const cb of this.outputListeners) cb(v);
|
||||
}
|
||||
}
|
||||
|
||||
async teardown(): Promise<void> {
|
||||
this.offConn?.();
|
||||
this.offInfo?.();
|
||||
this.offOutputs?.();
|
||||
this.offInputs?.();
|
||||
this.offConn = null;
|
||||
this.offInfo = null;
|
||||
this.offOutputs = null;
|
||||
this.offInputs = null;
|
||||
this.client.disconnect();
|
||||
this.gotModuleReply = false;
|
||||
this.setStatus({ state: 'idle', message: 'VCV idle' });
|
||||
}
|
||||
|
||||
status(): BackendStatus {
|
||||
return this.statusState;
|
||||
}
|
||||
|
||||
onStatusChange(cb: (s: BackendStatus) => void): () => void {
|
||||
this.statusListeners.add(cb);
|
||||
return () => this.statusListeners.delete(cb);
|
||||
}
|
||||
|
||||
private setStatus(s: BackendStatus): void {
|
||||
this.statusState = s;
|
||||
for (const cb of this.statusListeners) cb(s);
|
||||
}
|
||||
}
|
||||
|
||||
/** Sanitise an output name into an OSC-path-safe token (the bridge prefixes it). */
|
||||
function sanitise(name: string): string {
|
||||
return name.toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '') || 'out';
|
||||
}
|
||||
Loading…
Reference in a new issue