@libraz/libsonare 1.4.1 → 1.5.0

package/src/worklet/engine-offline.ts

@@ -0,0 +1,162 @@
+import type { EngineCaptureStatus, EngineMarker, EngineTrackLane, RealtimeEngine } from '../index';
+import type { SonareEngineSyncCaptureMessage, SonareEngineTransportFacade } from './messages';
+
+/** Capture configuration options accepted by the engine's `configureCapture`. */
+export interface CaptureOptions {
+  bufferFrames: number;
+  channels?: number;
+  source?: EngineCaptureStatus['source'];
+  recordOffsetSamples?: number;
+  inputMonitor?: { enabled: boolean; gain?: number };
+}
+
+/**
+ * Normalizes capture options into the resolved config carried by the
+ * `syncCapture` message, applying integer truncation and defaults.
+ *
+ * @param options Raw capture options.
+ * @param defaultChannels Channel count to use when `options.channels` is unset.
+ */
+export function buildCaptureConfig(
+  options: CaptureOptions,
+  defaultChannels: number,
+): Omit<SonareEngineSyncCaptureMessage, 'type'> {
+  return {
+    bufferFrames: Math.trunc(options.bufferFrames),
+    channels: Math.trunc(options.channels ?? defaultChannels),
+    source: options.source ?? 'output',
+    recordOffsetSamples: Math.trunc(options.recordOffsetSamples ?? 0),
+    inputMonitor: {
+      enabled: Boolean(options.inputMonitor?.enabled),
+      gain: options.inputMonitor?.gain ?? 1,
+    },
+  };
+}
+
+/**
+ * Collaborator surface the transport facade needs from the owning engine: the
+ * realtime node (sample-accurate command transport), the offline engine it
+ * mirrors, and the tempo/loop setters plus playing-state bookkeeping.
+ */
+export interface EngineTransportContext {
+  readonly sampleRate: number;
+  realtimeNode: {
+    play(sampleTime?: number): boolean;
+    stop(sampleTime?: number): boolean;
+    seekPpq(ppq: number, sampleTime?: number): boolean;
+    seekSample(timelineSample: number, sampleTime?: number): boolean;
+  };
+  offlineEngine: RealtimeEngine;
+  setTransportPlaying(playing: boolean): void;
+  flushPendingInstrumentSync(): void;
+  setTempo(bpm: number): void;
+  setTempoSegments(segments: readonly { startPpq: number; bpm: number }[]): void;
+  setLoop(startPpq: number, endPpq: number, enabled?: boolean): boolean;
+}
+
+/** Builds the public transport facade that fans control to both engines. */
+export function buildTransportFacade(ctx: EngineTransportContext): SonareEngineTransportFacade {
+  return {
+    play: (sampleTime = -1) => {
+      const ok = ctx.realtimeNode.play(sampleTime);
+      if (ok) {
+        ctx.setTransportPlaying(true);
+      }
+      return ok;
+    },
+    stop: (sampleTime = -1) => {
+      const ok = ctx.realtimeNode.stop(sampleTime);
+      if (ok) {
+        ctx.setTransportPlaying(false);
+        ctx.flushPendingInstrumentSync();
+      }
+      return ok;
+    },
+    seekPpq: (ppq, sampleTime = -1) => {
+      ctx.offlineEngine.seekPpq(ppq, sampleTime);
+      return ctx.realtimeNode.seekPpq(ppq, sampleTime);
+    },
+    seekSeconds: (seconds, sampleTime = -1) => {
+      const timelineSample = Math.max(0, Math.round(seconds * ctx.sampleRate));
+      ctx.offlineEngine.seekSample(timelineSample, sampleTime);
+      return ctx.realtimeNode.seekSample(timelineSample, sampleTime);
+    },
+    setTempo: (bpm) => ctx.setTempo(bpm),
+    setTempoSegments: (segments) => ctx.setTempoSegments(segments),
+    setLoop: (startPpq, endPpq, enabled = true) => ctx.setLoop(startPpq, endPpq, enabled),
+  };
+}
+
+/**
+ * Validates and normalizes an append-only mixer-lane declaration.
+ *
+ * Lane indices are append-only: the new list must start with the already
+ * declared lane ids in their current order and may only append new track ids.
+ * Returns the normalized lane entries (numbers coerced to descriptors) and the
+ * resulting ordered id list.
+ *
+ * @throws if any track id is invalid, ids are duplicated, or the existing lane
+ *   order is not preserved.
+ */
+export function normalizeTrackLanes(
+  existing: readonly number[],
+  lanes: ReadonlyArray<number | EngineTrackLane>,
+): { entries: EngineTrackLane[]; ids: number[] } {
+  const entries = lanes.map((lane) => (typeof lane === 'number' ? { trackId: lane } : lane));
+  const ids: number[] = [];
+  for (const entry of entries) {
+    if (!Number.isInteger(entry.trackId) || entry.trackId <= 0) {
+      throw new Error(`Invalid track id for mixer lane: ${String(entry.trackId)}`);
+    }
+    ids.push(entry.trackId);
+  }
+  if (new Set(ids).size !== ids.length) {
+    throw new Error('Duplicate track id in mixer lane list');
+  }
+  for (let index = 0; index < existing.length; index++) {
+    if (ids[index] !== existing[index]) {
+      throw new Error(
+        'Mixer lanes are append-only: keep existing lanes in order and only append new track ids',
+      );
+    }
+  }
+  return { entries, ids };
+}
+
+/**
+ * Resolves a marker set, assigning fresh ids to entries without one and
+ * validating explicit ids (positive, unique).
+ *
+ * @param markers The marker list to resolve.
+ * @param nextMarkerId The id counter to draw fresh ids from.
+ * @returns The resolved markers and the advanced id counter.
+ * @throws on a non-finite ppq, an invalid id, or a duplicate id.
+ */
+export function resolveMarkerSet(
+  markers: ReadonlyArray<{ ppq: number; name?: string; id?: number }>,
+  nextMarkerId: number,
+): { resolved: EngineMarker[]; nextMarkerId: number } {
+  const resolved: EngineMarker[] = [];
+  const seen = new Set<number>();
+  let counter = nextMarkerId;
+  for (const marker of markers) {
+    if (!Number.isFinite(marker.ppq)) {
+      throw new Error(`Invalid marker ppq: ${String(marker.ppq)}`);
+    }
+    if (marker.id !== undefined) {
+      if (!Number.isInteger(marker.id) || marker.id <= 0) {
+        throw new Error(`Invalid marker id: ${String(marker.id)}`);
+      }
+      if (seen.has(marker.id)) {
+        throw new Error(`Duplicate marker id: ${marker.id}`);
+      }
+    }
+    const id = marker.id ?? counter++;
+    seen.add(id);
+    if (id >= counter) {
+      counter = id + 1;
+    }
+    resolved.push({ id, ppq: marker.ppq, name: marker.name ?? '' });
+  }
+  return { resolved, nextMarkerId: counter };
+}

package/src/worklet/engine-options.ts

@@ -0,0 +1,13 @@
+import type { RealtimeEngine } from '../index';
+import type { SonareRealtimeEngineNodeOptions } from './messages';
+
+export interface SonareEngineOptions extends SonareRealtimeEngineNodeOptions {
+  offlineEngine?: RealtimeEngine;
+  offlineBlockSize?: number;
+  offlineChannelCount?: number;
+}
+
+export type SuspendableAudioContext = BaseAudioContext & {
+  suspend?: () => Promise<void>;
+  resume?: () => Promise<void>;
+};

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

@@ -0,0 +1,172 @@
+import type { EngineParameterInfo, RealtimeEngine } from '../index';
+import type { SonareRealtimeEngineNode } from './engine-node';
+import {
+  ENGINE_MIXER_PARAM_FADER_DB,
+  ENGINE_MIXER_PARAM_PAN,
+  engineMixerBusTarget,
+  engineMixerLaneTarget,
+  engineMixerMasterTarget,
+  SonareEngineCommandType,
+} from './protocol';
+
+/**
+ * Collaborator surface the parameter / automation-id resolution helpers need
+ * from the owning {@link SonareEngine}: the offline engine they mirror into and
+ * query, the realtime node they command, the lane/bus declaration helpers, and
+ * the declared track-lane id store used to resolve insert-automation ids.
+ */
+export interface EngineParameterContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly realtimeNode: SonareRealtimeEngineNode;
+  readonly trackLaneIds: number[];
+  resolveParamId(nodeId: string, param: string | number): number;
+  ensureTrackLane(target: string | number): number;
+  ensureBus(busId: number): number;
+}
+
+export function setParam(
+  ctx: EngineParameterContext,
+  nodeId: string,
+  param: string | number,
+  value: number,
+): boolean {
+  const paramId = ctx.resolveParamId(nodeId, param);
+  // Mirror the change into the offline engine so a subsequent offline render
+  // reflects the live value, then push a sample-accurate command to the
+  // realtime runtime (mirrors setTempo/setLoop above).
+  ctx.offlineEngine.setParameter(paramId, value);
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.SetParam,
+    targetId: paramId,
+    sampleTime: -1,
+    argFloat: value,
+  });
+}
+
+export function setSoloMute(
+  ctx: EngineParameterContext,
+  target: string | number,
+  solo: boolean,
+  mute: boolean,
+): boolean {
+  const laneIndex = ctx.ensureTrackLane(target);
+  ctx.offlineEngine.setSoloMute(laneIndex, solo, mute);
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.SetSoloMute,
+    targetId: laneIndex,
+    sampleTime: -1,
+    argInt: (mute ? 0x1 : 0) | (solo ? 0x2 : 0),
+  });
+}
+
+/**
+ * Returns the automation target id for a mixer strip parameter.
+ *
+ * The id addresses the engine's reserved mixer namespace, so it can be fed
+ * straight to setAutomationLane to automate a fader or pan without
+ * registering a parameter.
+ *
+ * @param target Track id (declares a mixer lane on first use) or 'master'.
+ * @param kind Strip parameter to address.
+ * @returns Reserved engine parameter id for the strip parameter.
+ */
+export function automationParamId(
+  ctx: EngineParameterContext,
+  target: string | number,
+  kind: 'faderDb' | 'pan',
+): number {
+  const paramKind = kind === 'pan' ? ENGINE_MIXER_PARAM_PAN : ENGINE_MIXER_PARAM_FADER_DB;
+  if (target === 'master') {
+    return engineMixerMasterTarget(paramKind);
+  }
+  return engineMixerLaneTarget(ctx.ensureTrackLane(target), paramKind);
+}
+
+/**
+ * Returns the automation target id for a bus fader.
+ *
+ * @param busId Bus id (declares the mixer bus on first use).
+ * @returns Reserved engine parameter id for the bus fader gain (dB).
+ */
+export function busAutomationParamId(ctx: EngineParameterContext, busId: number): number {
+  return engineMixerBusTarget(ctx.ensureBus(busId), ENGINE_MIXER_PARAM_FADER_DB);
+}
+
+/**
+ * Resolves a track-lane insert parameter (JSON-key name) to the reserved
+ * insert-automation id fed straight to setAutomationLane. Declares the track's
+ * mixer lane first (like automationParamId) so the offline engine resolves the
+ * same strip selector the realtime engine uses.
+ *
+ * @param target Track id (declares a mixer lane on first use).
+ * @param insertIndex Index into the strip's combined insert sequence.
+ * @param paramName Processor JSON-key parameter name.
+ * @returns Reserved insert-automation id, or -1 when strip/insert/key unknown.
+ */
+export function resolveTrackInsertAutomationId(
+  ctx: EngineParameterContext,
+  target: string | number,
+  insertIndex: number,
+  paramName: string,
+): number {
+  const laneIndex = ctx.ensureTrackLane(target);
+  return ctx.offlineEngine.resolveTrackInsertAutomationId(
+    ctx.trackLaneIds[laneIndex],
+    insertIndex,
+    paramName,
+  );
+}
+
+/**
+ * Resolves a master-strip insert parameter to its reserved insert-automation
+ * id.
+ *
+ * @param insertIndex Index into the master strip's insert sequence.
+ * @param paramName Processor JSON-key parameter name.
+ * @returns Reserved insert-automation id, or -1 when insert/key unknown.
+ */
+export function resolveMasterInsertAutomationId(
+  ctx: EngineParameterContext,
+  insertIndex: number,
+  paramName: string,
+): number {
+  return ctx.offlineEngine.resolveMasterInsertAutomationId(insertIndex, paramName);
+}
+
+/**
+ * Resolves a bus-strip insert parameter to its reserved insert-automation id.
+ * Declares the mixer bus first so the offline engine resolves the same bus
+ * selector.
+ *
+ * @param busId Bus id (declares the mixer bus on first use).
+ * @param insertIndex Index into the bus strip's insert sequence.
+ * @param paramName Processor JSON-key parameter name.
+ * @returns Reserved insert-automation id, or -1 when bus/insert/key unknown.
+ */
+export function resolveBusInsertAutomationId(
+  ctx: EngineParameterContext,
+  busId: number,
+  insertIndex: number,
+  paramName: string,
+): number {
+  ctx.ensureBus(busId);
+  return ctx.offlineEngine.resolveBusInsertAutomationId(busId, insertIndex, paramName);
+}
+
+/**
+ * Returns the number of automation lanes installed on the engine, including
+ * lanes whose breakpoint list is currently empty.
+ *
+ * @returns Engine-side automation lane count.
+ */
+export function automationLaneCount(ctx: EngineParameterContext): number {
+  return ctx.offlineEngine.automationLaneCount();
+}
+
+export function listParameters(ctx: EngineParameterContext): EngineParameterInfo[] {
+  const parameters: EngineParameterInfo[] = [];
+  for (let index = 0; index < ctx.offlineEngine.parameterCount(); index++) {
+    parameters.push(ctx.offlineEngine.parameterInfoByIndex(index));
+  }
+  return parameters;
+}