@libraz/libsonare 1.4.1 → 1.5.1

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 });
+}

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

@@ -0,0 +1,186 @@
+import type { EngineBus, EngineTrackLane, EngineTrackSend, RealtimeEngine } from '../index';
+import { normalizeTrackLanes } from './engine-offline';
+import { buildMixerLanes } from './engine-sync';
+import type { SonareEngineSyncMessage } from './messages';
+import { ENGINE_MIXER_PARAM_FADER_DB, engineMixerBusTarget } from './protocol';
+
+/**
+ * Collaborator surface the mixer/routing setters need from the owning
+ * {@link SonareEngine}: the offline engine they mirror writes into, the mutable
+ * routing stores (held by reference), the out-of-band sync poster, and the
+ * lane/bus declaration and mixer-sync helpers.
+ */
+export interface EngineMixerContext {
+  readonly offlineEngine: RealtimeEngine;
+  readonly trackLaneIds: number[];
+  readonly trackSends: Map<number, EngineTrackSend[]>;
+  readonly trackOutputBus: Map<number, number>;
+  readonly laneSidechains: Map<
+    string,
+    { trackId: number; insertIndex: number; sourceTrackId: number }
+  >;
+  readonly buses: EngineBus[];
+  readonly trackStripJson: Map<number, string>;
+  readonly busStripJson: Map<number, string>;
+  postSync(message: SonareEngineSyncMessage): void;
+  ensureTrackLane(target: string | number): number;
+  ensureBus(busId: number): number;
+  mixerLanes(): EngineTrackLane[];
+  syncMixer(): void;
+  sendSmoothedParam(paramId: number, value: number): boolean;
+  getMasterStripJson(): string | undefined;
+}
+
+/** Builds the engine's track-lane descriptors from the current routing stores. */
+export function mixerLanes(ctx: EngineMixerContext): EngineTrackLane[] {
+  return buildMixerLanes(ctx.trackLaneIds, ctx.trackSends, ctx.trackOutputBus);
+}
+
+/**
+ * Mirrors the current mixer routing into the offline engine and posts the full
+ * mixer-sync message (lanes, buses, strip JSON, sidechains) to the worklet.
+ */
+export function syncMixer(ctx: EngineMixerContext): void {
+  const lanes = mixerLanes(ctx);
+  const buses = ctx.buses.map((bus) => ({ ...bus }));
+  ctx.offlineEngine.setTrackBuses(buses);
+  if (lanes.length > 0) {
+    ctx.offlineEngine.setTrackLanes(lanes);
+  }
+  const trackStrips = Array.from(ctx.trackStripJson, ([trackId, sceneJson]) => ({
+    trackId,
+    sceneJson,
+  }));
+  const busStrips = Array.from(ctx.busStripJson, ([busId, sceneJson]) => ({
+    busId,
+    sceneJson,
+  }));
+  ctx.postSync({
+    type: 'syncMixer',
+    lanes,
+    buses,
+    trackStrips,
+    laneSidechains: Array.from(ctx.laneSidechains.values()),
+    busStrips,
+    masterStripJson: ctx.getMasterStripJson(),
+  });
+}
+
+/**
+ * Declares the mixer track lanes in an explicit order.
+ *
+ * Lane indices are append-only: once a track id occupies a lane, its index
+ * stays fixed for the engine's lifetime. The given list must therefore start
+ * with the already-declared lane ids in their current order and may only
+ * append new track ids after them. Entries carrying `sends` replace that
+ * track's send list; entries without `sends` leave existing sends untouched.
+ *
+ * @param lanes Track ids or lane descriptors in the desired lane order.
+ */
+export function setTrackLanes(
+  ctx: EngineMixerContext,
+  lanes: ReadonlyArray<number | EngineTrackLane>,
+): void {
+  const { entries, ids } = normalizeTrackLanes(ctx.trackLaneIds, lanes);
+  for (const entry of entries) {
+    if (entry.sends) {
+      ctx.trackSends.set(
+        entry.trackId,
+        entry.sends.map((send) => ({ ...send })),
+      );
+    }
+    if (entry.outputBusId !== undefined) {
+      if (entry.outputBusId === 0) {
+        ctx.trackOutputBus.delete(entry.trackId);
+      } else {
+        ctx.trackOutputBus.set(entry.trackId, entry.outputBusId);
+      }
+    }
+  }
+  ctx.trackLaneIds.splice(0, ctx.trackLaneIds.length, ...ids);
+  ctx.syncMixer();
+}
+
+/**
+ * Routes a track lane's post-fader output into a declared bus instead of
+ * the master mix (group/folder routing); busId 0 restores the master mix.
+ */
+export function setTrackOutputBus(
+  ctx: EngineMixerContext,
+  target: string | number,
+  busId: number,
+): void {
+  const laneIndex = ctx.ensureTrackLane(target);
+  const trackId = ctx.trackLaneIds[laneIndex];
+  if (busId === 0) {
+    ctx.trackOutputBus.delete(trackId);
+  } else {
+    ctx.trackOutputBus.set(trackId, busId);
+  }
+  ctx.syncMixer();
+}
+
+/**
+ * Keys one insert of a lane strip from another lane's post-strip pre-fader
+ * audio (ducking/sidechainRouter inserts). sourceTarget null removes the
+ * binding.
+ */
+export function setLaneSidechain(
+  ctx: EngineMixerContext,
+  target: string | number,
+  insertIndex: number,
+  sourceTarget: string | number | null,
+): void {
+  const laneIndex = ctx.ensureTrackLane(target);
+  const trackId = ctx.trackLaneIds[laneIndex];
+  const key = `${trackId}:${insertIndex}`;
+  let sourceTrackId = 0;
+  if (sourceTarget !== null) {
+    const sourceIndex = ctx.ensureTrackLane(sourceTarget);
+    sourceTrackId = ctx.trackLaneIds[sourceIndex];
+  }
+  if (sourceTrackId === 0) {
+    ctx.laneSidechains.delete(key);
+  } else {
+    ctx.laneSidechains.set(key, { trackId, insertIndex, sourceTrackId });
+  }
+  ctx.offlineEngine.setLaneSidechain(trackId, insertIndex, sourceTrackId);
+  ctx.postSync({
+    type: 'syncMixer',
+    lanes: ctx.mixerLanes(),
+    laneSidechains: [{ trackId, insertIndex, sourceTrackId }],
+  });
+}
+
+export function setSends(
+  ctx: EngineMixerContext,
+  target: string | number,
+  sends: EngineTrackSend[],
+): void {
+  const laneIndex = ctx.ensureTrackLane(target);
+  const trackId = ctx.trackLaneIds[laneIndex];
+  ctx.trackSends.set(
+    trackId,
+    sends.map((send) => ({ ...send })),
+  );
+  ctx.syncMixer();
+}
+
+export function setTrackBuses(ctx: EngineMixerContext, buses: EngineBus[]): void {
+  ctx.buses.splice(0, ctx.buses.length, ...buses.map((bus) => ({ ...bus })));
+  ctx.syncMixer();
+}
+
+export function setBusGain(ctx: EngineMixerContext, busId: number, db: number): boolean {
+  const busIndex = ctx.ensureBus(busId);
+  ctx.buses[busIndex] = { ...ctx.buses[busIndex], busId, gainDb: db };
+  ctx.offlineEngine.setTrackBuses(ctx.buses);
+  return ctx.sendSmoothedParam(engineMixerBusTarget(busIndex, ENGINE_MIXER_PARAM_FADER_DB), db);
+}
+
+export function setBusStripJson(ctx: EngineMixerContext, busId: number, sceneJson: string): void {
+  ctx.ensureBus(busId);
+  ctx.offlineEngine.setBusStripJson(busId, sceneJson);
+  ctx.busStripJson.set(busId, sceneJson);
+  ctx.syncMixer();
+}