@libraz/libsonare 1.4.1 → 1.5.0

package/src/realtime_engine.ts

@@ -24,9 +24,12 @@ import type {
   WasmEngineTempoSegment,
   WasmEngineTimeSignatureSegment,
   WasmEngineTransportState,
+  WasmExternalMidiEvent,
   WasmRealtimeEngine,
 } from './sonare.js';
 
+export type ExternalMidiEvent = WasmExternalMidiEvent;
+
 export type EngineClip = WasmEngineClip;
 export type ClipPageRequest = WasmClipPageRequest;
 export type EngineParameterInfo = WasmEngineParameterInfo;
@@ -193,6 +196,15 @@ export class RealtimeEngine {
     this.native.setParameterSmoothed(paramId, value, renderFrame);
   }
 
+  /**
+   * Set the default ramp time (ms) for engine-level smoothed parameters —
+   * fader/pan glides, insert-parameter automation, and MIDI-CC mappings. The
+   * default is 20 ms; pass `0` for instant (un-ramped) changes.
+   */
+  setParamSmoothingMs(smoothingMs: number): void {
+    this.native.setParamSmoothingMs(smoothingMs);
+  }
+
   setSoloMute(laneIndex: number, solo: boolean, mute: boolean, renderFrame = -1): void {
     this.native.setSoloMute(laneIndex, solo, mute, renderFrame);
   }
@@ -308,6 +320,39 @@ export class RealtimeEngine {
     return this.native.midiInputPendingCount();
   }
 
+  /**
+   * Route a destination's (track lane's) MIDI to the external output queue
+   * instead of the internal instrument rack, so the track plays an external
+   * device. Clearing it restores internal-synth playback.
+   */
+  setMidiDestinationExternal(destinationId: number, external: boolean): void {
+    this.native.setMidiDestinationExternal(destinationId, external);
+  }
+
+  /**
+   * Enable/disable forwarding MIDI clock + transport (start/continue/stop) to
+   * the external output queue so external gear tracks the transport tempo.
+   */
+  setExternalMidiClockEnabled(enabled: boolean): void {
+    this.native.setExternalMidiClockEnabled(enabled);
+  }
+
+  /** Count of external-MIDI events dropped because the output queue was full. */
+  externalMidiDroppedCount(): number {
+    return this.native.externalMidiDroppedCount();
+  }
+
+  /**
+   * Drain queued external-MIDI events, already lowered to MIDI 1.0 byte
+   * messages ready to write to a Web MIDI output port. Call once per audio
+   * block / animation frame. `maxRecords` caps the number of output events
+   * returned — the shared unit across every surface. Events past the cap stay
+   * queued for the next call (lossless); call again to drain the rest.
+   */
+  drainExternalMidi(maxRecords = 1024): WasmExternalMidiEvent[] {
+    return this.native.drainExternalMidi(maxRecords);
+  }
+
   pushMidiInputNoteOn(
     group: number,
     channel: number,
@@ -377,6 +422,16 @@ export class RealtimeEngine {
     this.native.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
   }
 
+  /**
+   * Queue an immediate (live) MIDI SysEx frame to a MIDI destination. `data` is
+   * the full message including the leading 0xF0 and trailing 0xF7 (1..512
+   * bytes). `renderFrame` is the frame to fire at, or -1 for immediate. Mirrors
+   * the Node/Python/C-ABI `pushMidiSysex`.
+   */
+  pushMidiSysex(destinationId: number, data: Uint8Array, renderFrame = -1): void {
+    this.native.pushMidiSysex(destinationId, data, renderFrame);
+  }
+
   /**
    * Queue a MIDI panic (all-notes-off) releasing every sounding note at
    * `renderFrame` (-1 = immediate). Mirrors the C-ABI `pushMidiPanic`.
@@ -662,6 +717,45 @@ export class RealtimeEngine {
     this.native.setMasterStripInsertParamByName(insertIndex, paramName, value);
   }
 
+  /** Bus-strip counterpart of {@link setTrackStripInsertParamByName}. */
+  setBusStripInsertParamByName(
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): void {
+    this.native.setBusStripInsertParamByName(busId, insertIndex, paramName, value);
+  }
+
+  /** Bus-strip counterpart of {@link setTrackStripInsertBypassed}. */
+  setBusStripInsertBypassed(
+    busId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass = false,
+  ): void {
+    this.native.setBusStripInsertBypassed(busId, insertIndex, bypassed, resetOnBypass);
+  }
+
+  /**
+   * Resolves a track-lane insert parameter (by its JSON-key name) to the
+   * reserved automation id usable with `setAutomationLane` / `setParameter`.
+   * Returns `-1` when the track, insert, or name is unknown. (The Python binding
+   * raises a `SonareError` for an unknown id where Node/WASM return the `-1`
+   * sentinel.)
+   */
+  resolveTrackInsertAutomationId(trackId: number, insertIndex: number, paramName: string): number {
+    return this.native.resolveTrackInsertAutomationId(trackId, insertIndex, paramName);
+  }
+
+  resolveMasterInsertAutomationId(insertIndex: number, paramName: string): number {
+    return this.native.resolveMasterInsertAutomationId(insertIndex, paramName);
+  }
+
+  resolveBusInsertAutomationId(busId: number, insertIndex: number, paramName: string): number {
+    return this.native.resolveBusInsertAutomationId(busId, insertIndex, paramName);
+  }
+
   /** Sets a track lane strip's pan position in realtime (glitch-free). */
   setTrackStripPan(trackId: number, pan: number): void {
     this.native.setTrackStripPan(trackId, pan);

package/src/sonare.js.d.ts

@@ -510,6 +510,10 @@ export interface WasmMixMeterSnapshot {
   truePeakDbR: number;
   maxTruePeakDb: number;
   seq: number;
+  channelCount: number;
+  peakDb: number[];
+  rmsDb: number[];
+  truePeakDb: number[];
 }
 
 export interface WasmMixResult {
@@ -783,6 +787,23 @@ export interface WasmEngineTimeSignatureSegment {
   denominator: number;
 }
 
+/**
+ * One external-MIDI event drained from the engine, already lowered to MIDI 1.0
+ * bytes ready to write to a Web MIDI output port.
+ */
+export interface WasmExternalMidiEvent {
+  /**
+   * Originating track lane (Track.midi_destination_id), or the transport
+   * sentinel 0xFFFFFFFF for clock / start / continue / stop bytes meant for
+   * every external port.
+   */
+  destinationId: number;
+  /** Sample position within the producing block at which the event fires. */
+  renderFrame: number;
+  /** MIDI 1.0 status + data bytes (1..3 entries). */
+  bytes: number[];
+}
+
 export interface WasmRealtimeEngine {
   prepare: (
     sampleRate: number,
@@ -792,6 +813,7 @@ export interface WasmRealtimeEngine {
   ) => void;
   setParameter: (paramId: number, value: number, renderFrame: number) => void;
   setParameterSmoothed: (paramId: number, value: number, renderFrame: number) => void;
+  setParamSmoothingMs: (smoothingMs: number) => void;
   setSoloMute: (laneIndex: number, solo: boolean, mute: boolean, renderFrame: number) => void;
   getTransportState: () => WasmEngineTransportState;
   play: (renderFrame: number) => void;
@@ -851,6 +873,25 @@ export interface WasmRealtimeEngine {
     value: number,
   ) => void;
   setMasterStripInsertParamByName: (insertIndex: number, paramName: string, value: number) => void;
+  setBusStripInsertParamByName: (
+    busId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ) => void;
+  setBusStripInsertBypassed: (
+    busId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass: boolean,
+  ) => void;
+  resolveTrackInsertAutomationId: (
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+  ) => number;
+  resolveMasterInsertAutomationId: (insertIndex: number, paramName: string) => number;
+  resolveBusInsertAutomationId: (busId: number, insertIndex: number, paramName: string) => number;
   setTrackStripPan: (trackId: number, pan: number) => void;
   setTrackStripPanLaw: (trackId: number, panLaw: number) => void;
   setTrackStripPanMode: (trackId: number, panMode: number) => void;
@@ -936,7 +977,12 @@ export interface WasmRealtimeEngine {
     value: number,
     renderFrame: number,
   ) => void;
+  pushMidiSysex: (destinationId: number, data: Uint8Array, renderFrame: number) => void;
   pushMidiPanic: (renderFrame: number) => void;
+  setMidiDestinationExternal: (destinationId: number, external: boolean) => void;
+  setExternalMidiClockEnabled: (enabled: boolean) => void;
+  externalMidiDroppedCount: () => number;
+  drainExternalMidi: (maxRecords: number) => WasmExternalMidiEvent[];
   clearParameters: () => void;
   process: (channels: Float32Array[]) => Float32Array[];
   prepareChannels: (numChannels: number, maxFrames: number) => void;
@@ -1337,6 +1383,25 @@ export interface SonareModule {
     voiced?: Float32Array,
     voicedProb?: Float32Array,
   ) => Float32Array;
+  pitchCorrectTimevarying: (
+    samples: Float32Array,
+    sampleRate: number,
+    f0Hz: Float32Array,
+    hopLength: number,
+    options: {
+      mode?: string;
+      targetMidi?: number;
+      scaleRoot?: number;
+      scaleModeMask?: number;
+      referenceMidi?: number;
+      retuneAmount?: number;
+      maxCorrectionSemitones?: number;
+      retuneSpeedMs?: number;
+      vibratoThresholdCents?: number;
+      voiced?: Float32Array;
+      voicedProb?: Float32Array;
+    },
+  ) => Float32Array;
   noteStretch: (
     samples: Float32Array,
     sampleRate: number,
@@ -1567,6 +1632,7 @@ export interface SonareModule {
     fmin: number,
     fmax: number,
     htk: boolean,
+    lifter: number,
   ) => WasmMfccResult;
 
   // Features - Inverse reconstruction
@@ -1792,6 +1858,12 @@ export interface SonareModule {
     hopLength: number,
     nChroma: number,
   ) => WasmChromaResult;
+  chromaCqt: (
+    samples: Float32Array,
+    sampleRate: number,
+    hopLength: number,
+    nChroma: number,
+  ) => WasmChromaResult;
   bassChroma: (
     samples: Float32Array,
     sampleRate: number,

package/src/worklet/engine-automation.ts

@@ -0,0 +1,73 @@
+import type { EngineAutomationPoint, RealtimeEngine } from '../index';
+import { curveCode } from './engine-sync';
+import type { SonareEngineSyncMessage } from './messages';
+
+/**
+ * Collaborator surface the automation-lane helpers need from the owning
+ * {@link SonareEngine}: the lane store they mutate, the offline engine they
+ * mirror into, the sync poster, and the parameter-id resolver.
+ */
+export interface EngineAutomationContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly automationLanes: Map<number, EngineAutomationPoint[]>;
+  postSync(message: SonareEngineSyncMessage): void;
+  resolveParamId(nodeId: string, param: string | number): number;
+}
+
+export function scheduleParam(
+  ctx: EngineAutomationContext,
+  nodeId: string,
+  param: string | number,
+  ppq: number,
+  value: number,
+  curve: number | 'linear' | 'exponential' = 'linear',
+): void {
+  const paramId = ctx.resolveParamId(nodeId, param);
+  const lane = ctx.automationLanes.get(paramId) ?? [];
+  lane.push({ ppq, value, curveToNext: curveCode(curve) });
+  lane.sort((a, b) => a.ppq - b.ppq);
+  ctx.automationLanes.set(paramId, lane);
+  ctx.offlineEngine.setAutomationLane(paramId, lane);
+  // Mirror the lane to the live worklet engine so scheduled automation plays
+  // back in real time, not just in renderOffline(). Lanes can exceed the
+  // fixed-size SAB command record, so they ride an out-of-band 'syncAutomation'
+  // message applied outside process() (like syncClips/syncMarkers).
+  ctx.postSync({ type: 'syncAutomation', paramId, points: lane });
+}
+
+export function addAutomationPoint(
+  ctx: EngineAutomationContext,
+  laneId: string | number,
+  ppq: number,
+  value: number,
+  curve: number | 'linear' | 'exponential' = 'linear',
+): void {
+  scheduleParam(ctx, '', laneId, ppq, value, curve);
+}
+
+/**
+ * Replaces the automation lane for `paramId` with the given breakpoints.
+ *
+ * Unlike scheduleParam (which appends a single point), this sets the whole
+ * lane at once; an empty array clears the lane. The points are defensively
+ * copied and sorted by ppq before being mirrored to the offline engine and
+ * the live worklet engine.
+ *
+ * @param paramId Automation target id (registered parameter or a reserved
+ *   engine mixer target from automationParamId/busAutomationParamId).
+ * @param points Lane breakpoints; order does not matter.
+ */
+export function setAutomationLane(
+  ctx: EngineAutomationContext,
+  paramId: number,
+  points: ReadonlyArray<EngineAutomationPoint>,
+): void {
+  const sorted = points.map((point) => ({ ...point })).sort((a, b) => a.ppq - b.ppq);
+  if (sorted.length === 0) {
+    ctx.automationLanes.delete(paramId);
+  } else {
+    ctx.automationLanes.set(paramId, sorted);
+  }
+  ctx.offlineEngine.setAutomationLane(paramId, sorted);
+  ctx.postSync({ type: 'syncAutomation', paramId, points: sorted });
+}

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

@@ -0,0 +1,80 @@
+import type { EngineCaptureStatus, RealtimeEngine } from '../index';
+import type { SonareRealtimeEngineNode } from './engine-node';
+import { buildCaptureConfig, type CaptureOptions } from './engine-offline';
+import type { SonareEngineSyncCaptureMessage, SonareEngineSyncMessage } from './messages';
+import { SonareEngineCommandType } from './protocol';
+
+type CaptureConfig = Omit<SonareEngineSyncCaptureMessage, 'type'>;
+
+/**
+ * Collaborator surface the capture/record/punch setters need from the owning
+ * {@link SonareEngine}: the offline engine they mirror into, the realtime node
+ * they command and query, the channel count, the out-of-band sync poster, the
+ * capture-config accessor, and the target-id resolver.
+ */
+export interface EngineCaptureContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly realtimeNode: SonareRealtimeEngineNode;
+  readonly offlineChannelCount: number;
+  postSync(message: SonareEngineSyncMessage): void;
+  getCaptureConfig(): CaptureConfig | undefined;
+  setCaptureConfig(config: CaptureConfig): void;
+  resolveTargetId(target: string | number): number;
+}
+
+export function configureCapture(ctx: EngineCaptureContext, options: CaptureOptions): void {
+  const config = buildCaptureConfig(options, ctx.offlineChannelCount);
+  ctx.offlineEngine.setCaptureBuffer(config.channels, config.bufferFrames);
+  ctx.offlineEngine.setCaptureSource(config.source);
+  ctx.offlineEngine.setRecordOffsetSamples(config.recordOffsetSamples);
+  ctx.offlineEngine.setInputMonitor(config.inputMonitor.enabled, config.inputMonitor.gain);
+  ctx.setCaptureConfig(config);
+  ctx.postSync({ type: 'syncCapture', ...config });
+}
+
+export function armRecord(
+  ctx: EngineCaptureContext,
+  trackId: string | number,
+  enabled: boolean,
+): boolean {
+  if (enabled && !ctx.getCaptureConfig()) {
+    throw new Error('Capture buffer is not configured');
+  }
+  ctx.offlineEngine.armCapture(enabled);
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.ArmRecord,
+    targetId: ctx.resolveTargetId(trackId),
+    sampleTime: -1,
+    argInt: enabled ? 1 : 0,
+  });
+}
+
+export function punch(ctx: EngineCaptureContext, inPpq: number, outPpq: number): boolean {
+  const inSample = ctx.offlineEngine.sampleAtPpq(inPpq);
+  const outSample = ctx.offlineEngine.sampleAtPpq(outPpq);
+  ctx.offlineEngine.setCapturePunch(inSample, outSample, true);
+  // Carry BOTH endpoints as already-converted SAMPLES so the realtime engine
+  // agrees with the offline engine. The previous code sent the raw PPQ out
+  // point and let the consumer multiply by sampleRate (treating PPQ as
+  // seconds), which ignored tempo and produced a punch-out ~2x too large at
+  // 120 BPM. argInt = in sample, argFloat = out sample (full-precision double).
+  return ctx.realtimeNode.sendCommand({
+    type: SonareEngineCommandType.Punch,
+    sampleTime: -1,
+    argInt: inSample,
+    argFloat: outSample,
+  });
+}
+
+export function captureStatus(ctx: EngineCaptureContext): Promise<EngineCaptureStatus> {
+  return ctx.realtimeNode.requestCaptureStatus();
+}
+
+export function capturedAudio(ctx: EngineCaptureContext): Promise<Float32Array[]> {
+  return ctx.realtimeNode.requestCapturedAudio();
+}
+
+export async function resetCapture(ctx: EngineCaptureContext): Promise<void> {
+  ctx.offlineEngine.resetCapture();
+  await ctx.realtimeNode.requestCaptureReset();
+}

package/src/worklet/engine-clips.ts

@@ -0,0 +1,71 @@
+import type { EngineClip, EngineMidiClipSchedule, RealtimeEngine } from '../index';
+import type { SonareEngineSyncMessage } from './messages';
+
+/**
+ * Collaborator surface the audio/MIDI clip scheduling helpers need from the
+ * owning {@link SonareEngine}: the clip stores they mutate, the offline engine
+ * they mirror into, the sync poster, and the clip-id allocator / lane resolvers.
+ */
+export interface EngineClipContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly clips: Map<number, EngineClip>;
+  readonly midiClips: Map<number, EngineMidiClipSchedule>;
+  allocateClipId(): number;
+  postSync(message: SonareEngineSyncMessage): void;
+  resolveTargetId(target: string | number): number;
+  ensureTrackLane(target: string | number): number;
+}
+
+export function addClip(
+  ctx: EngineClipContext,
+  trackId: string | number,
+  buffer: Float32Array[],
+  startPpq: number,
+  opts: Partial<Omit<EngineClip, 'channels' | 'startPpq'>> = {},
+): number {
+  const id = opts.id ?? ctx.allocateClipId();
+  const clip: EngineClip = {
+    ...opts,
+    id,
+    channels: buffer,
+    startPpq,
+    trackId: ctx.resolveTargetId(trackId),
+  };
+  ctx.ensureTrackLane(trackId);
+  ctx.clips.set(id, clip);
+  syncClipsDelta(ctx, [clip], []);
+  return id;
+}
+
+export function removeClip(ctx: EngineClipContext, clipId: number): void {
+  ctx.clips.delete(clipId);
+  syncClipsDelta(ctx, [], [clipId]);
+}
+
+export function setMidiClips(
+  ctx: EngineClipContext,
+  clips: readonly EngineMidiClipSchedule[],
+): void {
+  ctx.midiClips.clear();
+  for (const clip of clips) {
+    const id = clip.id ?? ctx.allocateClipId();
+    ctx.midiClips.set(id, { ...clip, id, events: clip.events.map((event) => ({ ...event })) });
+  }
+  syncMidiClips(ctx);
+}
+
+function syncClipsDelta(ctx: EngineClipContext, upserts: EngineClip[], removeIds: number[]): void {
+  const clips = Array.from(ctx.clips.values());
+  ctx.offlineEngine.setClips(clips);
+  ctx.postSync({
+    type: 'syncClipsDelta',
+    upserts,
+    removeIds,
+  });
+}
+
+function syncMidiClips(ctx: EngineClipContext): void {
+  const clips = Array.from(ctx.midiClips.values());
+  ctx.offlineEngine.setMidiClips(clips);
+  ctx.postSync({ type: 'syncMidiClips', clips });
+}

package/src/worklet/engine-markers.ts

@@ -0,0 +1,93 @@
+import type { EngineMarker, RealtimeEngine } from '../index';
+import { resolveMarkerSet } from './engine-offline';
+import type { SonareEngineSyncMessage } from './messages';
+import { type SonareEngineCommandRecord, SonareEngineCommandType } from './protocol';
+
+/**
+ * Collaborator surface the marker helpers need from the owning
+ * {@link SonareEngine}: the marker store and id counter, the offline engine they
+ * mirror into, the sync poster, the realtime command sender, and the loop setter.
+ */
+export interface EngineMarkerContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly markers: Map<number, EngineMarker>;
+  getNextMarkerId(): number;
+  setNextMarkerId(value: number): void;
+  postSync(message: SonareEngineSyncMessage): void;
+  sendCommand(command: SonareEngineCommandRecord): boolean;
+  setLoop(startPpq: number, endPpq: number, enabled: boolean): boolean;
+}
+
+export function addMarker(ctx: EngineMarkerContext, ppq: number, name = ''): number {
+  const id = ctx.getNextMarkerId();
+  ctx.setNextMarkerId(id + 1);
+  ctx.markers.set(id, { id, ppq, name });
+  syncMarkers(ctx);
+  return id;
+}
+
+/**
+ * Replaces the whole marker set in one call.
+ *
+ * Entries without an `id` are assigned fresh ids; entries carrying an `id`
+ * keep it (ids must be positive and unique within the list). Returns the
+ * resolved markers in the order given, so a caller can map its own marker
+ * identities to the engine ids used by `seekMarker`/`setLoopFromMarkers`.
+ *
+ * @param markers The full marker list (an empty list clears all markers).
+ * @returns The markers with their resolved engine ids.
+ */
+export function setMarkers(
+  ctx: EngineMarkerContext,
+  markers: ReadonlyArray<{ ppq: number; name?: string; id?: number }>,
+): EngineMarker[] {
+  const { resolved, nextMarkerId } = resolveMarkerSet(markers, ctx.getNextMarkerId());
+  ctx.setNextMarkerId(nextMarkerId);
+  ctx.markers.clear();
+  for (const marker of resolved) {
+    ctx.markers.set(marker.id, marker);
+  }
+  syncMarkers(ctx);
+  return resolved.map((marker) => ({ ...marker }));
+}
+
+export function markerCount(ctx: EngineMarkerContext): number {
+  return ctx.offlineEngine.markerCount();
+}
+
+export function markerByIndex(ctx: EngineMarkerContext, index: number): EngineMarker {
+  return ctx.offlineEngine.markerByIndex(index);
+}
+
+export function marker(ctx: EngineMarkerContext, markerId: number): EngineMarker {
+  return ctx.offlineEngine.marker(markerId);
+}
+
+export function seekMarker(ctx: EngineMarkerContext, markerId: number): boolean {
+  ctx.offlineEngine.seekMarker(markerId);
+  // Forward to the live worklet engine. Its marker set is kept in sync via the
+  // 'syncMarkers' message (see syncMarkers), so a queued kSeekMarker resolves
+  // the marker id to its frame on the audio thread.
+  return ctx.sendCommand({
+    type: SonareEngineCommandType.SeekMarker,
+    targetId: markerId,
+    sampleTime: -1,
+  });
+}
+
+export function setLoopFromMarkers(
+  ctx: EngineMarkerContext,
+  startMarkerId: number,
+  endMarkerId: number,
+): boolean {
+  ctx.offlineEngine.setLoopFromMarkers(startMarkerId, endMarkerId);
+  const start = ctx.offlineEngine.marker(startMarkerId);
+  const end = ctx.offlineEngine.marker(endMarkerId);
+  return ctx.setLoop(start.ppq, end.ppq, true);
+}
+
+function syncMarkers(ctx: EngineMarkerContext): void {
+  const markers = Array.from(ctx.markers.values()).sort((a, b) => a.ppq - b.ppq);
+  ctx.offlineEngine.setMarkers(markers);
+  ctx.postSync({ type: 'syncMarkers', markers });
+}