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,7 @@ import { pluginEngine } from '../../engine/PluginEngine';
 import { effectsEngine } from '../../engine/EffectsEngine';
 import {
   buildCombinedEffectsChain,
+  calculatePluginDelayCompensation,
 } from '../useEffectsSync';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -85,3 +86,35 @@ 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);
+  });
+});

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,16 @@ 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,
+  );
+}
+
 export function useEffectsSync() {
   const tracks = useProjectStore((s) => s.project?.tracks);
   const dspBackend = useUIStore((s) => s.dspBackend);
@@ -116,6 +127,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 +146,16 @@ 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 = calculatePluginDelayCompensation([...trackNodes.keys()], 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);
+  });
 });

src/store/__tests__/vst3Store.test.ts

@@ -25,6 +25,7 @@ const mockInstance = (overrides: Partial<VST3ActiveInstance> = {}): VST3ActiveIn
   parameters: [],
   presets: [],
   activePreset: null,
+  latencySamples: 0,
   ...overrides,
 });
 
@@ -249,29 +250,21 @@ describe('vst3Store', () => {
       const { _getBridgeClient } = await import('../../hooks/useVST3Connection');
       const client = _getBridgeClient();
 
-      // Intercept on/off to capture event listeners registered by loadPlugin
-      const listeners: Record<string, ((...args: unknown[]) => void)[]> = {};
-      client.on = vi.fn().mockImplementation((event: string, handler: (...args: unknown[]) => void) => {
-        if (!listeners[event]) listeners[event] = [];
-        listeners[event].push(handler);
-      });
-      client.off = vi.fn();
-
-      // Mock createInstance to simulate the companion responding with instanceCreated
-      const mockCreateInstance = vi.fn().mockImplementation((_pluginUid: string, instanceId: string) => {
-        queueMicrotask(() => {
-          for (const fn of listeners['instanceCreated'] ?? []) {
-            fn({ type: 'instanceCreated', instanceId, parameters: [] });
-          }
-        });
-        return Promise.resolve();
-      });
-      client.createInstance = mockCreateInstance;
+      const mockInstantiate = vi.fn().mockImplementation((_pluginUid: string, instanceId: string) => Promise.resolve({
+        type: 'instantiated',
+        reqId: 'req-1',
+        instanceId,
+        parameters: [],
+        latencySamples: 384,
+        tailSamples: 0,
+        presets: [],
+      }));
+      client.instantiate = mockInstantiate;
 
       await useVST3Store.getState().loadPlugin('com.xfer.serum', 'track-1');
 
-      // Should have called createInstance with the pluginId and a generated instanceId
-      expect(mockCreateInstance).toHaveBeenCalledWith('com.xfer.serum', expect.any(String));
+      // Should have called instantiate with the pluginId and a generated instanceId
+      expect(mockInstantiate).toHaveBeenCalledWith('com.xfer.serum', expect.any(String));
 
       // Should have created an instance in the store
       const { instances } = useVST3Store.getState();
@@ -285,28 +278,26 @@ describe('vst3Store', () => {
       expect(instance.trackId).toBe('track-1');
       expect(instance.enabled).toBe(true);
       expect(instance.online).toBe(true);
+      expect(instance.latencySamples).toBe(384);
+    });
+
+    it('updates store and PluginEngine when the companion reports latency changes', () => {
+      const setPluginLatencySpy = vi.spyOn(pluginEngine, 'setPluginLatency').mockImplementation(() => undefined);
+      useVST3Store.getState()._upsertInstance(mockInstance({ instanceId: 'inst-1', trackId: 'track-1', latencySamples: 128 }));
+
+      useVST3Store.getState()._updateLatency('inst-1', 512.8);
+
+      expect(setPluginLatencySpy).toHaveBeenCalledWith('track-1', 'inst-1', 512);
+      expect(useVST3Store.getState().instances['inst-1'].latencySamples).toBe(512);
+
+      setPluginLatencySpy.mockRestore();
     });
 
     it('does not create an instance when bridge call fails', async () => {
       const { _getBridgeClient } = await import('../../hooks/useVST3Connection');
       const client = _getBridgeClient();
 
-      const listeners: Record<string, ((...args: unknown[]) => void)[]> = {};
-      client.on = vi.fn().mockImplementation((event: string, handler: (...args: unknown[]) => void) => {
-        if (!listeners[event]) listeners[event] = [];
-        listeners[event].push(handler);
-      });
-      client.off = vi.fn();
-
-      client.createInstance = vi.fn().mockImplementation(() => {
-        // Trigger the error listener
-        queueMicrotask(() => {
-          for (const fn of listeners['error'] ?? []) {
-            fn('Connection lost');
-          }
-        });
-        return Promise.resolve();
-      });
+      client.instantiate = vi.fn().mockRejectedValue(new Error('Connection lost'));
 
       await useVST3Store.getState().loadPlugin('com.xfer.serum', 'track-1');