@libraz/libsonare 1.4.1 → 1.5.0

package/src/worklet/engine-register.ts

@@ -0,0 +1,136 @@
+import { init as initSonareModule, isInitialized } from '../index';
+import type { SonareModule } from '../sonare.js';
+import type { WorkletInput, WorkletOutput } from './audio_types';
+import { SonareRealtimeEngineWorkletProcessor } from './engine-processor';
+import {
+  isEngineCaptureRequestMessage,
+  isEngineCommandRecord,
+  isEngineSyncMessage,
+  isEngineTransportRequestMessage,
+} from './guards';
+import type { SonareRealtimeEngineWorkletProcessorOptions, WorkletPort } from './messages';
+
+export function registerSonareRealtimeEngineWorkletProcessor(
+  name = 'sonare-realtime-engine-processor',
+): void {
+  const scope = globalThis as unknown as {
+    AudioWorkletProcessor?: new () => object;
+    registerProcessor?: (processorName: string, processorCtor: unknown) => void;
+  };
+  if (!scope.AudioWorkletProcessor || !scope.registerProcessor) {
+    throw new Error('AudioWorkletProcessor is not available in this context.');
+  }
+  const Base = scope.AudioWorkletProcessor;
+  class RegisteredSonareRealtimeEngineWorkletProcessor extends Base {
+    private bridge?: SonareRealtimeEngineWorkletProcessor;
+    private readonly pendingMessages: unknown[] = [];
+    readonly port?: WorkletPort;
+
+    constructor(options?: { processorOptions?: SonareRealtimeEngineWorkletProcessorOptions }) {
+      super();
+      const port = this.port;
+      const processorOptions = options?.processorOptions ?? {};
+      void this.initializeEmbind(processorOptions, port);
+      const onMessage = (event: { data: unknown }) => {
+        if (!this.bridge) {
+          if (this.pendingMessages.length < 1024) {
+            this.pendingMessages.push(event.data);
+          }
+          return;
+        }
+        if (isEngineCommandRecord(event.data)) {
+          this.bridge.receiveCommand(event.data);
+        } else if (isEngineSyncMessage(event.data)) {
+          this.bridge.receiveSync(event.data);
+        } else if (isEngineCaptureRequestMessage(event.data)) {
+          this.bridge.receiveCaptureRequest(event.data);
+        } else if (isEngineTransportRequestMessage(event.data)) {
+          this.bridge.receiveTransportRequest(event.data);
+        }
+      };
+      if (port?.addEventListener) {
+        port.addEventListener('message', onMessage);
+        port.start?.();
+      } else if (port) {
+        port.onmessage = onMessage;
+      }
+    }
+
+    process(inputs: WorkletInput, outputs: WorkletOutput): boolean {
+      if (this.bridge) {
+        return this.bridge.process(inputs, outputs);
+      }
+      const output = outputs[0];
+      for (const channel of output ?? []) {
+        channel.fill(0);
+      }
+      return true;
+    }
+
+    private replayPendingMessages(): void {
+      const messages = this.pendingMessages.splice(0);
+      for (const data of messages) {
+        if (isEngineCommandRecord(data)) {
+          this.bridge?.receiveCommand(data);
+        } else if (isEngineSyncMessage(data)) {
+          this.bridge?.receiveSync(data);
+        } else if (isEngineCaptureRequestMessage(data)) {
+          this.bridge?.receiveCaptureRequest(data);
+        } else if (isEngineTransportRequestMessage(data)) {
+          this.bridge?.receiveTransportRequest(data);
+        }
+      }
+    }
+
+    private async initializeEmbind(
+      options: SonareRealtimeEngineWorkletProcessorOptions,
+      port?: WorkletPort,
+    ): Promise<void> {
+      try {
+        const initPromise = (
+          globalThis as typeof globalThis & { SonareEmbindInitPromise?: Promise<void> }
+        ).SonareEmbindInitPromise;
+        if (initPromise) {
+          await initPromise;
+        }
+        if (!isInitialized()) {
+          type EmbindModuleFactory = (options?: {
+            locateFile?: (path: string, prefix: string) => string;
+            wasmBinary?: ArrayBuffer | Uint8Array;
+          }) => Promise<SonareModule>;
+          const moduleFactory = (
+            globalThis as typeof globalThis & {
+              SonareEmbindModuleFactory?: EmbindModuleFactory;
+            }
+          ).SonareEmbindModuleFactory;
+          if (!moduleFactory) {
+            throw new Error('embind realtime engine module is not initialized.');
+          }
+          await initSonareModule({
+            locateFile: (path) => path,
+            wasmBinary: options.wasmBinary,
+            moduleFactory,
+          });
+        }
+        this.bridge = new SonareRealtimeEngineWorkletProcessor(options, {
+          postMessage: (message) => port?.postMessage?.(message),
+          onMeter: (meter) => port?.postMessage?.(meter),
+        });
+        for (const message of options.initialSyncMessages ?? []) {
+          this.bridge.receiveSync(message);
+        }
+        for (const command of options.initialCommands ?? []) {
+          this.bridge.receiveCommand(command);
+        }
+        this.replayPendingMessages();
+        port?.postMessage?.({ type: 'ready', runtimeTarget: 'embind' });
+      } catch (error) {
+        port?.postMessage?.({
+          type: 'error',
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+  scope.registerProcessor(name, RegisteredSonareRealtimeEngineWorkletProcessor);
+}

package/src/worklet/engine-strips.ts

@@ -0,0 +1,315 @@
+import { panLawCode, panModeCode } from '../codes';
+import type { EqBand, PanLaw, PanMode, RealtimeEngine } from '../index';
+import type { SonareEngineInstrumentSyncMessage, SonareEngineSyncMessage } from './messages';
+
+/**
+ * Collaborator surface the strip/pan/EQ/insert/instrument/MIDI setters need from
+ * the owning {@link SonareEngine}: the offline engine they mirror writes into,
+ * the out-of-band sync posters, and the lane-resolution helpers.
+ */
+export interface EngineStripContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly trackLaneIds: number[];
+  postSync(message: SonareEngineSyncMessage): void;
+  postInstrumentSync(message: SonareEngineInstrumentSyncMessage): void;
+  ensureTrackLane(target: string | number): number;
+  resolveTargetId(target: string | number): number;
+}
+
+function trackIdFor(ctx: EngineStripContext, target: string | number): number {
+  return ctx.trackLaneIds[ctx.ensureTrackLane(target)];
+}
+
+export function setTrackStripJson(
+  ctx: EngineStripContext,
+  trackId: number,
+  sceneJson: string,
+  trackStripJson: Map<number, string>,
+): void {
+  ctx.offlineEngine.setTrackStripJson(trackId, sceneJson);
+  trackStripJson.set(trackId, sceneJson);
+}
+
+export function setTrackStripEqBand(
+  ctx: EngineStripContext,
+  target: string | number,
+  bandIndex: number,
+  band: EqBand | string,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  const bandJson = typeof band === 'string' ? band : JSON.stringify(band);
+  ctx.offlineEngine.setTrackStripEqBandJson(trackId, bandIndex, bandJson);
+  ctx.postSync({ type: 'syncTrackStripEqBand', trackId, bandIndex, bandJson });
+}
+
+export function setTrackStripInsertBypassed(
+  ctx: EngineStripContext,
+  target: string | number,
+  insertIndex: number,
+  bypassed: boolean,
+  resetOnBypass: boolean,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripInsertBypassed(trackId, insertIndex, bypassed, resetOnBypass);
+  ctx.postSync({
+    type: 'syncTrackStripInsertBypassed',
+    trackId,
+    insertIndex,
+    bypassed,
+    resetOnBypass,
+  });
+}
+
+export function setTrackStripInsertParamByName(
+  ctx: EngineStripContext,
+  target: string | number,
+  insertIndex: number,
+  paramName: string,
+  value: number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripInsertParamByName(trackId, insertIndex, paramName, value);
+  ctx.postSync({ type: 'syncTrackStripInsertParamByName', trackId, insertIndex, paramName, value });
+}
+
+export function setTrackStripPan(
+  ctx: EngineStripContext,
+  target: string | number,
+  pan: number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripPan(trackId, pan);
+  ctx.postSync({ type: 'syncTrackStripPan', trackId, pan });
+}
+
+export function setTrackStripPanLaw(
+  ctx: EngineStripContext,
+  target: string | number,
+  panLaw: PanLaw | number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  const code = panLawCode(panLaw);
+  ctx.offlineEngine.setTrackStripPanLaw(trackId, code);
+  ctx.postSync({ type: 'syncTrackStripPanLaw', trackId, panLaw: code });
+}
+
+export function setTrackStripPanMode(
+  ctx: EngineStripContext,
+  target: string | number,
+  panMode: PanMode | number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  const code = panModeCode(panMode);
+  ctx.offlineEngine.setTrackStripPanMode(trackId, code);
+  ctx.postSync({ type: 'syncTrackStripPanMode', trackId, panMode: code });
+}
+
+export function setTrackStripDualPan(
+  ctx: EngineStripContext,
+  target: string | number,
+  leftPan: number,
+  rightPan: number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripDualPan(trackId, leftPan, rightPan);
+  ctx.postSync({ type: 'syncTrackStripDualPan', trackId, leftPan, rightPan });
+}
+
+export function setTrackStripChannelDelaySamples(
+  ctx: EngineStripContext,
+  target: string | number,
+  delaySamples: number,
+): void {
+  const trackId = trackIdFor(ctx, target);
+  ctx.offlineEngine.setTrackStripChannelDelaySamples(trackId, delaySamples);
+  ctx.postSync({ type: 'syncTrackStripChannelDelaySamples', trackId, delaySamples });
+}
+
+export function setMasterStripEqBand(
+  ctx: EngineStripContext,
+  bandIndex: number,
+  band: EqBand | string,
+): void {
+  const bandJson = typeof band === 'string' ? band : JSON.stringify(band);
+  ctx.offlineEngine.setMasterStripEqBandJson(bandIndex, bandJson);
+  ctx.postSync({ type: 'syncMasterStripEqBand', bandIndex, bandJson });
+}
+
+export function setMasterStripInsertBypassed(
+  ctx: EngineStripContext,
+  insertIndex: number,
+  bypassed: boolean,
+  resetOnBypass: boolean,
+): void {
+  ctx.offlineEngine.setMasterStripInsertBypassed(insertIndex, bypassed, resetOnBypass);
+  ctx.postSync({ type: 'syncMasterStripInsertBypassed', insertIndex, bypassed, resetOnBypass });
+}
+
+export function setMasterStripInsertParamByName(
+  ctx: EngineStripContext,
+  insertIndex: number,
+  paramName: string,
+  value: number,
+): void {
+  ctx.offlineEngine.setMasterStripInsertParamByName(insertIndex, paramName, value);
+  ctx.postSync({ type: 'syncMasterStripInsertParamByName', insertIndex, paramName, value });
+}
+
+export function setBusStripInsertParamByName(
+  ctx: EngineStripContext,
+  busId: number,
+  insertIndex: number,
+  paramName: string,
+  value: number,
+): void {
+  ctx.offlineEngine.setBusStripInsertParamByName(busId, insertIndex, paramName, value);
+  ctx.postSync({ type: 'syncBusStripInsertParamByName', busId, insertIndex, paramName, value });
+}
+
+export function pushMidiNoteOn(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  group: number,
+  channel: number,
+  note: number,
+  velocity: number,
+  renderFrame: number,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.pushMidiNoteOn(destinationId, group, channel, note, velocity, renderFrame);
+  ctx.postSync({
+    type: 'syncMidiNoteOn',
+    destinationId,
+    group,
+    channel,
+    note,
+    velocity,
+    renderFrame,
+  });
+}
+
+export function pushMidiNoteOff(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  group: number,
+  channel: number,
+  note: number,
+  velocity: number,
+  renderFrame: number,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.pushMidiNoteOff(destinationId, group, channel, note, velocity, renderFrame);
+  ctx.postSync({
+    type: 'syncMidiNoteOff',
+    destinationId,
+    group,
+    channel,
+    note,
+    velocity,
+    renderFrame,
+  });
+}
+
+export function pushMidiCc(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  group: number,
+  channel: number,
+  controller: number,
+  value: number,
+  renderFrame: number,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
+  ctx.postSync({
+    type: 'syncMidiCc',
+    destinationId,
+    group,
+    channel,
+    controller,
+    value,
+    renderFrame,
+  });
+}
+
+export function setBuiltinInstrument(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  config: { destinationId?: number } & Record<string, unknown>,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.setBuiltinInstrument(config, destinationId);
+  ctx.postInstrumentSync({ type: 'syncBuiltinInstrument', destinationId, config });
+}
+
+export function setSynthInstrument(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  patch: Record<string, unknown> | string,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.setSynthInstrument(patch, destinationId);
+  ctx.postInstrumentSync({ type: 'syncSynthInstrument', destinationId, patch });
+}
+
+export function loadSoundFont(ctx: EngineStripContext, data: Uint8Array): void {
+  ctx.offlineEngine.loadSoundFont(data);
+  ctx.postInstrumentSync({ type: 'syncLoadSoundFont', data });
+}
+
+export function setSf2Instrument(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  config: { destinationId?: number; gain?: number; polyphony?: number },
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.setSf2Instrument(config, destinationId);
+  ctx.postInstrumentSync({ type: 'syncSf2Instrument', destinationId, config });
+}
+
+export function setMidiDestinationExternal(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  external: boolean,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.setMidiDestinationExternal(destinationId, external);
+  ctx.postSync({ type: 'syncMidiDestinationExternal', destinationId, external });
+}
+
+export function setExternalMidiClockEnabled(ctx: EngineStripContext, enabled: boolean): void {
+  ctx.offlineEngine.setExternalMidiClockEnabled(enabled);
+  ctx.postSync({ type: 'syncExternalMidiClock', enabled });
+}
+
+export function setMidiFx(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  configJson: string,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.setMidiFx(destinationId, configJson);
+  ctx.postInstrumentSync({ type: 'syncMidiFx', destinationId, configJson });
+}
+
+export function clearMidiFx(ctx: EngineStripContext, trackId: string | number): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.clearMidiFx(destinationId);
+  ctx.postInstrumentSync({ type: 'syncClearMidiFx', destinationId });
+}
+
+export function pushMidiSysex(
+  ctx: EngineStripContext,
+  trackId: string | number,
+  data: Uint8Array,
+  renderFrame: number,
+): void {
+  const destinationId = ctx.resolveTargetId(trackId);
+  ctx.offlineEngine.pushMidiSysex(destinationId, data, renderFrame);
+  ctx.postSync({ type: 'syncMidiSysex', destinationId, data, renderFrame });
+}
+
+export function pushMidiPanic(ctx: EngineStripContext, renderFrame: number): void {
+  ctx.offlineEngine.pushMidiPanic(renderFrame);
+  ctx.postSync({ type: 'syncMidiPanic', renderFrame });
+}

package/src/worklet/engine-sync.ts

@@ -0,0 +1,94 @@
+import type {
+  EngineParameterInfo,
+  EngineTempoSegment,
+  EngineTimeSignatureSegment,
+  EngineTrackLane,
+  EngineTrackSend,
+} from '../index';
+import type { SonareEngineSyncTempoMessage } from './messages';
+
+/**
+ * Builds the ordered mixer-lane descriptors for a sync message.
+ *
+ * Each declared track id is paired with its current send list and output bus
+ * (both omitted when absent), defensively copying the send entries.
+ *
+ * @param trackLaneIds Lane order (track ids) declared on the engine.
+ * @param trackSends Per-track send lists.
+ * @param trackOutputBus Per-track output bus routing.
+ * @returns Lane descriptors in lane order.
+ */
+export function buildMixerLanes(
+  trackLaneIds: readonly number[],
+  trackSends: ReadonlyMap<number, EngineTrackSend[]>,
+  trackOutputBus: ReadonlyMap<number, number>,
+): EngineTrackLane[] {
+  return trackLaneIds.map((trackId) => {
+    const sends = trackSends.get(trackId);
+    const outputBusId = trackOutputBus.get(trackId);
+    return {
+      trackId,
+      ...(sends && sends.length > 0 ? { sends: sends.map((send) => ({ ...send })) } : {}),
+      ...(outputBusId !== undefined ? { outputBusId } : {}),
+    };
+  });
+}
+
+/**
+ * Builds the out-of-band tempo/time-signature sync message, deep-copying the
+ * tempo and time-signature segments so the consumer cannot alias engine state.
+ */
+export function buildTempoSync(
+  tempoBpm: number,
+  timeSignature: { numerator: number; denominator: number },
+  tempoSegments: readonly EngineTempoSegment[],
+  timeSignatureSegments: readonly EngineTimeSignatureSegment[],
+): SonareEngineSyncTempoMessage {
+  return {
+    type: 'syncTempo',
+    bpm: tempoBpm,
+    timeSignature: { ...timeSignature },
+    tempoSegments: tempoSegments.map((segment) => ({ ...segment })),
+    timeSignatureSegments: timeSignatureSegments.map((segment) => ({ ...segment })),
+  };
+}
+
+/**
+ * Resolves a target id from a string or number; non-numeric strings resolve to
+ * 0, mirroring the engine's integer-id namespace.
+ */
+export function resolveTargetId(target: string | number): number {
+  if (typeof target === 'number') {
+    return target;
+  }
+  const parsed = Number.parseInt(target, 10);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * Resolves a parameter id from a name or numeric id. Numeric params pass
+ * through; named params are matched against the parameter list, then fall back
+ * to a target-id resolution of the name (or the node id).
+ */
+export function resolveParamId(
+  parameters: readonly EngineParameterInfo[],
+  nodeId: string,
+  param: string | number,
+): number {
+  if (typeof param === 'number') {
+    return param;
+  }
+  const byName = parameters.find((info) => info.name === param);
+  if (byName) {
+    return byName.id;
+  }
+  return resolveTargetId(param || nodeId);
+}
+
+/** Encodes an automation curve descriptor to the engine's numeric curve code. */
+export function curveCode(curve: number | 'linear' | 'exponential'): number {
+  if (typeof curve === 'number') {
+    return curve;
+  }
+  return curve === 'exponential' ? 1 : 0;
+}

package/src/worklet/engine-tempo-facade.ts

@@ -0,0 +1,141 @@
+import type {
+  EngineTempoSegment,
+  EngineTimeSignatureSegment,
+  EngineTransportState,
+  RealtimeEngine,
+} from '../index';
+import type { SonareRealtimeEngineNode } from './engine-node';
+import { buildTempoSync } from './engine-sync';
+import type { SonareEngineSyncMessage } from './messages';
+import { SonareEngineCommandType } from './protocol';
+
+interface TimeSignature {
+  numerator: number;
+  denominator: number;
+}
+
+/**
+ * Collaborator surface the tempo / time-signature / loop / transport helpers
+ * need from the owning {@link SonareEngine}: the offline engine they mirror
+ * into, the realtime node they command and query, the out-of-band sync poster,
+ * and getters/setters for the tempo-map and cached-transport state the engine
+ * holds (so the helpers mutate it by reference).
+ */
+export interface EngineTempoContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly realtimeNode: SonareRealtimeEngineNode;
+  postSync(message: SonareEngineSyncMessage): void;
+  getTempoBpm(): number;
+  setTempoBpm(bpm: number): void;
+  getTimeSignature(): TimeSignature;
+  setTimeSignature(signature: TimeSignature): void;
+  getTempoSegments(): EngineTempoSegment[];
+  setTempoSegments(segments: EngineTempoSegment[]): void;
+  getTimeSignatureSegments(): EngineTimeSignatureSegment[];
+  setTimeSignatureSegments(segments: EngineTimeSignatureSegment[]): void;
+  setLatestTransportState(state: EngineTransportState): void;
+  getLatestTransportState(): EngineTransportState | undefined;
+}
+
+// Posts the full tempo/time-signature map to the worklet engine processor.
+export function postTempoSync(ctx: EngineTempoContext): void {
+  ctx.postSync(
+    buildTempoSync(
+      ctx.getTempoBpm(),
+      ctx.getTimeSignature(),
+      ctx.getTempoSegments(),
+      ctx.getTimeSignatureSegments(),
+    ),
+  );
+}
+
+export function setTempo(ctx: EngineTempoContext, bpm: number): void {
+  ctx.setTempoBpm(bpm);
+  ctx.setTempoSegments([{ startPpq: 0, bpm }]);
+  ctx.offlineEngine.setTempo(bpm);
+  postTempoSync(ctx);
+  ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.SetTempoMap,
+    sampleTime: -1,
+    argFloat: bpm,
+  });
+}
+
+export function setTempoSegments(
+  ctx: EngineTempoContext,
+  segments: readonly EngineTempoSegment[],
+): void {
+  const copied = segments.map((segment) => ({ ...segment }));
+  ctx.setTempoSegments(copied);
+  ctx.setTempoBpm(copied[0]?.bpm ?? ctx.getTempoBpm());
+  ctx.offlineEngine.setTempoSegments(copied);
+  postTempoSync(ctx);
+}
+
+export function setTimeSignature(
+  ctx: EngineTempoContext,
+  numerator: number,
+  denominator: number,
+): void {
+  ctx.setTimeSignature({ numerator, denominator });
+  ctx.setTimeSignatureSegments([{ startPpq: 0, numerator, denominator }]);
+  ctx.offlineEngine.setTimeSignature(numerator, denominator);
+  postTempoSync(ctx);
+}
+
+export function setTimeSignatureSegments(
+  ctx: EngineTempoContext,
+  segments: readonly EngineTimeSignatureSegment[],
+): void {
+  const copied = segments.map((segment) => ({ ...segment }));
+  ctx.setTimeSignatureSegments(copied);
+  const first = copied[0];
+  if (first) {
+    ctx.setTimeSignature({ numerator: first.numerator, denominator: first.denominator });
+  }
+  ctx.offlineEngine.setTimeSignatureSegments(copied);
+  postTempoSync(ctx);
+}
+
+export function setLoop(
+  ctx: EngineTempoContext,
+  startPpq: number,
+  endPpq: number,
+  enabled = true,
+): boolean {
+  ctx.offlineEngine.setLoop(startPpq, endPpq, enabled);
+  // Transport precision contract: the SAB command record carries exactly one
+  // Float64 lane (argFloat) and one Int64 lane (argInt). startPpq travels in
+  // argFloat with full double precision, matching the offline engine; endPpq
+  // is carried as micro-PPQ (round(endPpq * 1e6)) in the integer lane and
+  // divided back by 1e6 on the consumer. Loop ENDS are therefore snapped to
+  // the nearest 1e-6 PPQ over the realtime transport (max 5e-7 PPQ drift),
+  // while loop STARTS and the offline path stay exact. This is intentional:
+  // the record has no second free Float64 lane, and a micro-PPQ grid on the
+  // loop end is well below audible/sample-accurate resolution at any tempo.
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.SetLoop,
+    targetId: enabled ? 1 : 0,
+    sampleTime: -1,
+    argFloat: startPpq,
+    argInt: Math.round(endPpq * 1_000_000),
+  });
+}
+
+export function countInEndSample(
+  ctx: EngineTempoContext,
+  startSample: number,
+  bars: number,
+): number {
+  return ctx.offlineEngine.countInEndSample(startSample, bars);
+}
+
+export async function getTransportState(ctx: EngineTempoContext): Promise<EngineTransportState> {
+  const state = await ctx.realtimeNode.requestTransportState();
+  ctx.setLatestTransportState(state);
+  return state;
+}
+
+export function cachedTransportState(ctx: EngineTempoContext): EngineTransportState | undefined {
+  return ctx.getLatestTransportState();
+}