fix: apply max plugin delay compensation

Author: ChuxiJ

src/engine/PluginEngine.ts

@@ -230,19 +230,54 @@ export class PluginEngine {
 
   /**
    * Get total latency of plugin chain for a track (in samples).
-   * Sums latencySamples from all plugins in the chain.
+   * Sums latencySamples from all active plugins in the chain.
    * WAP plugins without latencySamples are assumed to have 0 latency.
    */
   getChainLatency(trackId: string): number {
     const chain = this.chains.get(trackId);
     if (!chain) return 0;
     let total = 0;
     for (const node of chain) {
-      total += node.plugin.latencySamples ?? 0;
+      if (node.bypassed) continue;
+      const latencySamples = node.plugin.latencySamples ?? 0;
+      total += Number.isFinite(latencySamples) ? Math.max(0, Math.floor(latencySamples)) : 0;
     }
     return total;
   }
 
+  /**
+   * Update a live plugin's reported latency.
+   * VST3 plugins can report latency after instantiation or after parameter changes.
+   */
+  setPluginLatency(trackId: string, instanceId: string, latencySamples: number): void {
+    const chain = this.chains.get(trackId);
+    if (!chain) return;
+    const node = chain.find((candidate) => candidate.instanceId === instanceId);
+    if (!node) return;
+
+    const sanitizedLatency = Number.isFinite(latencySamples)
+      ? Math.max(0, Math.floor(latencySamples))
+      : 0;
+    const plugin = node.plugin as WAPPlugin & {
+      setLatencySamples?: (samples: number) => void;
+      latencySamples?: number;
+    };
+    if (typeof plugin.setLatencySamples === 'function') {
+      plugin.setLatencySamples(sanitizedLatency);
+      return;
+    }
+
+    try {
+      Object.defineProperty(plugin, 'latencySamples', {
+        value: sanitizedLatency,
+        configurable: true,
+        enumerable: true,
+      });
+    } catch {
+      // Some third-party plugin wrappers may expose latency as a non-configurable readonly field.
+    }
+  }
+
   /**
    * Dispose the plugin chain for a track.
    */

src/hooks/__tests__/useEffectsSync.vst3.test.ts

@@ -9,6 +9,8 @@ import { pluginEngine } from '../../engine/PluginEngine';
 import { effectsEngine } from '../../engine/EffectsEngine';
 import {
   buildCombinedEffectsChain,
+  calculatePluginDelayCompensation,
+  calculatePluginDelayCompensationForTracks,
 } from '../useEffectsSync';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -85,3 +87,56 @@ describe('buildCombinedEffectsChain', () => {
     expect(pluginOutput.connect).toHaveBeenCalledWith(effectsInput);
   });
 });
+
+describe('calculatePluginDelayCompensation', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('delays lower-latency tracks to match the maximum active plugin chain latency', () => {
+    vi.spyOn(pluginEngine, 'getChainLatency').mockImplementation((trackId) => {
+      if (trackId === 'track-late') return 512;
+      if (trackId === 'track-mid') return 128;
+      return 0;
+    });
+
+    const result = calculatePluginDelayCompensation(
+      ['track-late', 'track-mid', 'track-dry'],
+      48000,
+    );
+
+    expect(result.get('track-late')).toBe(0);
+    expect(result.get('track-mid')).toBe(384);
+    expect(result.get('track-dry')).toBe(512);
+  });
+
+  it('clears compensation when active plugin latencies are all zero', () => {
+    vi.spyOn(pluginEngine, 'getChainLatency').mockReturnValue(0);
+
+    const result = calculatePluginDelayCompensation(['track-a', 'track-b'], 48000);
+
+    expect(result.get('track-a')).toBe(0);
+    expect(result.get('track-b')).toBe(0);
+  });
+
+  it('accounts for group-bus latency without applying extra compensation to the bus', () => {
+    vi.spyOn(pluginEngine, 'getChainLatency').mockImplementation((trackId) => {
+      if (trackId === 'group-bus') return 512;
+      if (trackId === 'track-child') return 128;
+      return 0;
+    });
+
+    const result = calculatePluginDelayCompensationForTracks(
+      [
+        { id: 'group-bus', isGroup: true },
+        { id: 'track-child', parentTrackId: 'group-bus' },
+        { id: 'track-dry' },
+      ],
+      48000,
+    );
+
+    expect(result.get('group-bus')).toBe(0);
+    expect(result.get('track-child')).toBe(0);
+    expect(result.get('track-dry')).toBe(640);
+  });
+});

src/hooks/useEffectsSync.ts

@@ -13,6 +13,7 @@ import { useWAMStore } from '../store/wamStore';
 import { effectsEngine, initWasmDsp } from '../engine/EffectsEngine';
 import { pluginEngine } from '../engine/PluginEngine';
 import { getAudioEngine } from './useAudioEngine';
+import { VST3LatencyCompensation } from '../services/vst3bridge/VST3LatencyCompensation';
 import { createDebugLogger } from '../utils/debugLogger';
 import type { CompressorParams } from '../types/project';
 import type { WAMActiveInstance } from '../types/wam';
@@ -51,12 +52,12 @@ export function buildCombinedEffectsChain(trackId: string): { input: AudioNode |
 
 /**
  * Derive a stable fingerprint of VST3 instances for effect chain syncing.
- * Only includes fields that affect audio routing (instanceId, trackId, enabled).
+ * Only includes fields that affect audio routing or timing.
  */
 function selectVst3EffectChainKey(s: { instances: Record<string, VST3ActiveInstance> }): string {
   const parts: string[] = [];
   for (const [id, inst] of Object.entries(s.instances)) {
-    parts.push(`${id}:${inst.trackId ?? ''}:${inst.enabled ? '1' : '0'}`);
+    parts.push(`${id}:${inst.trackId ?? ''}:${inst.enabled ? '1' : '0'}:${inst.latencySamples ?? 0}`);
   }
   return parts.sort().join('|');
 }
@@ -69,6 +70,56 @@ function selectWamEffectChainKey(s: { instances: Record<string, WAMActiveInstanc
   return parts.sort().join('|');
 }
 
+export function calculatePluginDelayCompensation(trackIds: string[], sampleRate: number): Map<string, number> {
+  return VST3LatencyCompensation.calculateCompensation(
+    trackIds.map((id) => ({
+      id,
+      pluginLatencies: [pluginEngine.getChainLatency(id)],
+    })),
+    sampleRate,
+  );
+}
+
+interface PluginDelayCompensationTrack {
+  id: string;
+  isGroup?: boolean;
+  parentTrackId?: string;
+}
+
+function getSignalPathTrackIds(
+  track: PluginDelayCompensationTrack,
+  trackById: Map<string, PluginDelayCompensationTrack>,
+): string[] {
+  const path = [track.id];
+  const visited = new Set(path);
+  let parentTrackId = track.parentTrackId;
+  while (parentTrackId && !visited.has(parentTrackId)) {
+    visited.add(parentTrackId);
+    path.push(parentTrackId);
+    parentTrackId = trackById.get(parentTrackId)?.parentTrackId;
+  }
+  return path;
+}
+
+export function calculatePluginDelayCompensationForTracks(
+  tracks: PluginDelayCompensationTrack[],
+  sampleRate: number,
+): Map<string, number> {
+  const trackById = new Map(tracks.map((track) => [track.id, track]));
+  const sourceTracks = tracks.filter((track) => !track.isGroup);
+  const compensationByTrack = VST3LatencyCompensation.calculateCompensation(
+    sourceTracks.map((track) => ({
+      id: track.id,
+      pluginLatencies: getSignalPathTrackIds(track, trackById).map((id) => pluginEngine.getChainLatency(id)),
+    })),
+    sampleRate,
+  );
+  for (const track of tracks) {
+    if (track.isGroup) compensationByTrack.set(track.id, 0);
+  }
+  return compensationByTrack;
+}
+
 export function useEffectsSync() {
   const tracks = useProjectStore((s) => s.project?.tracks);
   const dspBackend = useUIStore((s) => s.dspBackend);
@@ -116,6 +167,8 @@ export function useEffectsSync() {
       instancesByTrack.set(inst.trackId, list);
     }
 
+    const trackNodes = new Map<string, ReturnType<typeof engine.getOrCreateTrackNode>>();
+
     // First pass: rebuild built-in effect chains + sync VST3 bypass, then splice combined chain
     for (const track of tracks) {
       const effects = track.effects ?? [];
@@ -133,14 +186,19 @@ export function useEffectsSync() {
       if (trackNode) {
         const { input, output } = buildCombinedEffectsChain(track.id);
         trackNode.spliceEffects(input, output);
-
-        // Always apply latency compensation (including clearing to 0 when plugins removed/bypassed)
-        const pluginLatency = pluginEngine.getChainLatency(track.id);
-        const sampleRate = engine.ctx?.sampleRate ?? 44100;
-        trackNode.setLatencyCompensation(pluginLatency, sampleRate);
+        trackNodes.set(track.id, trackNode);
       }
     }
 
+    const sampleRate = engine.ctx?.sampleRate ?? 44100;
+    const compensationByTrack = calculatePluginDelayCompensationForTracks(
+      tracks.filter((track) => trackNodes.has(track.id)),
+      sampleRate,
+    );
+    for (const [trackId, trackNode] of trackNodes) {
+      trackNode.setLatencyCompensation(compensationByTrack.get(trackId) ?? 0, sampleRate);
+    }
+
     // Second pass: wire sidechain connections (all chains must exist first)
     for (const track of tracks) {
       for (const effect of track.effects ?? []) {

src/hooks/useVST3Connection.ts

@@ -92,11 +92,18 @@ export function useVST3Connection() {
       });
     };
 
+    const onLatencyInfo = (msg: Record<string, unknown>) => {
+      const instanceId = msg.instanceId as string | undefined;
+      if (!instanceId) return;
+      store._updateLatency(instanceId, Number(msg.samples ?? 0));
+    };
+
     const unsubs = [
       client.on('statusChange', onStatusChange),
       client.on('error', onError),
       client.on('scanComplete', onScanComplete),
       client.on('scanProgress', onScanProgress),
+      client.on('latencyInfo', onLatencyInfo),
     ];
 
     // Sync current state immediately (handles HMR / singleton already connected)

src/services/vst3bridge/VST3PluginAdapter.ts

@@ -37,6 +37,10 @@ const AUDIO_PUMP_INTERVAL_MS = 5;
 /** Audio block size sent per pump iteration (in sample frames). */
 const BLOCK_SIZE = 128;
 
+function sanitizeLatencySamples(samples: number): number {
+  return Number.isFinite(samples) ? Math.max(0, Math.floor(samples)) : 0;
+}
+
 // ─── Adapter ────────────────────────────────────────────────────────────────
 
 export class VST3PluginAdapter implements WAPPlugin {
@@ -45,8 +49,8 @@ export class VST3PluginAdapter implements WAPPlugin {
   readonly version: string;
   readonly author: string;
   readonly description: string;
-  readonly latencySamples: number;
 
+  private _latencySamples: number;
   private instanceId: string;
   private bridgeClient: VST3BridgeClient;
   private paramDescriptors: PluginParamDescriptor[] = [];
@@ -74,7 +78,7 @@ export class VST3PluginAdapter implements WAPPlugin {
     this.author = pluginInfo.vendor;
     this.description = `VST3: ${pluginInfo.name} by ${pluginInfo.vendor}`;
     this.bridgeClient = bridgeClient;
-    this.latencySamples = instantiateResponse.latencySamples;
+    this._latencySamples = sanitizeLatencySamples(instantiateResponse.latencySamples);
     this.instanceIdHash = fnv1aHash(instanceId);
 
     // Map VST3 params to WAP param descriptors
@@ -234,9 +238,19 @@ export class VST3PluginAdapter implements WAPPlugin {
     return this.instanceId;
   }
 
+  /** Latency in samples introduced by this plugin. */
+  get latencySamples(): number {
+    return this._latencySamples;
+  }
+
+  /** Update latency reported by the companion. */
+  setLatencySamples(samples: number): void {
+    this._latencySamples = sanitizeLatencySamples(samples);
+  }
+
   /** Latency in samples introduced by this plugin. */
   get pluginLatency(): number {
-    return this.latencySamples;
+    return this._latencySamples;
   }
 
   /** Ask the companion to open the native VST3 editor window. */

src/services/vst3bridge/__tests__/PluginEngineLatency.test.ts

@@ -59,4 +59,33 @@ describe('PluginEngine.getChainLatency', () => {
     engine.addPlugin('track-1', 'inst-3', p3, ctx);
     expect(engine.getChainLatency('track-1')).toBe(384);
   });
+
+  it('excludes bypassed plugins from chain latency', () => {
+    const p1 = createMockPlugin(128);
+    const p2 = createMockPlugin(256);
+    engine.addPlugin('track-1', 'inst-1', p1, ctx);
+    engine.addPlugin('track-1', 'inst-2', p2, ctx);
+
+    engine.setPluginBypassed('track-1', 'inst-2', true);
+
+    expect(engine.getChainLatency('track-1')).toBe(128);
+  });
+
+  it('updates a live plugin latency report', () => {
+    const plugin = createMockPlugin(128);
+    engine.addPlugin('track-1', 'inst-1', plugin, ctx);
+
+    engine.setPluginLatency('track-1', 'inst-1', 512);
+
+    expect(engine.getChainLatency('track-1')).toBe(512);
+  });
+
+  it('normalizes invalid and fractional latency samples', () => {
+    const p1 = createMockPlugin(128.8);
+    const p2 = createMockPlugin(Number.NaN);
+    engine.addPlugin('track-1', 'inst-1', p1, ctx);
+    engine.addPlugin('track-1', 'inst-2', p2, ctx);
+
+    expect(engine.getChainLatency('track-1')).toBe(128);
+  });
 });