feat(core,audio-worklet): Expose WSOLA timing parameters

Add StretchParameters interface (sequenceMs, seekWindowMs, overlapMs, quickSeek)
and setStretchParameters() method to Stretch and SoundTouch for fine-grained
control of the WSOLA time-stretch algorithm at runtime.

Add public overlapMs getter/setter and quickSeek getter to Stretch, making the
previously-hidden timing internals accessible without replacing all parameters
at once. Add SetStretchParametersMessage to the processor message union so
SoundTouchNode.setStretchParameters() can queue updates to the render thread.

Author: cutterbl

packages/audio-worklet/README.md

@@ -141,6 +141,24 @@ stNode.setInterpolationStrategyParams({ edgeHoldFrames: 4 });
 
 These updates are applied by the processor at render-block boundaries for stable transitions.
 
+### WSOLA timing parameters
+
+Use `setStretchParameters()` to tune the time-stretch algorithm. Updates are queued and applied at the next render-block boundary.
+
+```ts
+stNode.setStretchParameters({ overlapMs: 12 });            // overlap only
+stNode.setStretchParameters({ quickSeek: false });         // exhaustive search
+stNode.setStretchParameters({ sequenceMs: 80, seekWindowMs: 20 }); // manual windows
+stNode.setStretchParameters({ sequenceMs: 0 });            // back to auto
+```
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `sequenceMs` | auto (50–125 ms) | Processing window in ms; `0` = auto |
+| `seekWindowMs` | auto (15–25 ms) | Seek window in ms; `0` = auto |
+| `overlapMs` | 8 ms | Crossfade overlap in ms |
+| `quickSeek` | `true` | Fast seek; `false` = exhaustive |
+
 ### Full example — AudioBuffer
 
 ```ts

packages/audio-worklet/src/SoundTouchNode.spec.ts

@@ -109,6 +109,22 @@ describe('SoundTouchNode', () => {
     });
   });
 
+  it('sends set-stretch-parameters message via MessagePort', async () => {
+    const { SoundTouchNode } = await import('./index.js');
+    const context = {} as BaseAudioContext;
+    const node = new SoundTouchNode({ context });
+
+    node.setStretchParameters({ overlapMs: 12, quickSeek: false });
+
+    const port = (
+      node as unknown as { port: { postMessage: ReturnType<typeof vi.fn> } }
+    ).port;
+    expect(port.postMessage).toHaveBeenCalledWith({
+      type: 'set-stretch-parameters',
+      params: { overlapMs: 12, quickSeek: false },
+    });
+  });
+
   describe('outputChannelCount option', () => {
     it('defaults to stereo (outputChannelCount [2]) when not specified', async () => {
       const { SoundTouchNode } = await import('./index.js');

packages/audio-worklet/src/SoundTouchNode.ts

@@ -21,7 +21,9 @@ import type {
   InterpolationStrategyParams,
   RateTransposerInterpolationStrategy,
   SampleBufferType,
+  StretchParameters,
 } from '@soundtouchjs/core';
+export type { StretchParameters } from '@soundtouchjs/core';
 import { DEFAULT_SAMPLE_BUFFER_TYPE, PROCESSOR_NAME } from './constants.js';
 
 /**
@@ -197,4 +199,24 @@ export class SoundTouchNode extends AudioWorkletNode {
       params,
     });
   }
+
+  /**
+   * Applies a partial set of WSOLA timing parameters to the render-thread processor.
+   *
+   * @remarks
+   * The update is queued and applied at the next render-block boundary. Only the
+   * provided fields are updated; omitted fields remain unchanged. Pass `sequenceMs: 0`
+   * or `seekWindowMs: 0` to switch that dimension back to auto-calculation.
+   *
+   * @param params Partial WSOLA timing parameters to apply.
+   *
+   * @example
+   * stNode.setStretchParameters({ overlapMs: 12, quickSeek: false });
+   */
+  setStretchParameters(params: StretchParameters): void {
+    this.port.postMessage({
+      type: 'set-stretch-parameters',
+      params,
+    });
+  }
 }

packages/audio-worklet/src/index.ts

@@ -29,5 +29,6 @@ export { SoundTouchNode } from './SoundTouchNode.js';
 export type {
   SoundTouchNodeConstructorOptions,
   SoundTouchNodeOptions,
+  StretchParameters,
 } from './SoundTouchNode.js';
 export { PROCESSOR_NAME } from './constants.js';

packages/audio-worklet/src/processor.spec.ts

@@ -21,6 +21,7 @@ const extract = vi.fn();
 const receive = vi.fn();
 const setInterpolationStrategy = vi.fn();
 const setInterpolationStrategyParams = vi.fn();
+const setStretchParameters = vi.fn();
 const soundTouchCtorArgs: unknown[] = [];
 
 vi.mock('@soundtouchjs/core', () => {
@@ -49,6 +50,10 @@ vi.mock('@soundtouchjs/core', () => {
       setInterpolationStrategyParams(params);
     }
 
+    setStretchParameters(params: unknown): void {
+      setStretchParameters(params);
+    }
+
     constructor(options?: unknown) {
       soundTouchCtorArgs.push(options);
     }
@@ -75,6 +80,7 @@ beforeEach(() => {
   receive.mockReset();
   setInterpolationStrategy.mockReset();
   setInterpolationStrategyParams.mockReset();
+  setStretchParameters.mockReset();
   soundTouchCtorArgs.length = 0;
   outputFrameCount = 0;
 
@@ -235,6 +241,40 @@ describe('processor', () => {
     expect(instance.process([[new Float32Array(2)]], [[]], params)).toBe(true);
   });
 
+  it('applies pending stretch parameter updates from message port', async () => {
+    await import('./processor.js');
+    const instance = new registeredCtor!({
+      processorOptions: { sampleBufferType: 'circular' },
+    }) as unknown as {
+      port: { onmessage: ((event: { data: unknown }) => void) | null };
+      process: RegisteredProcessorCtor['prototype']['process'];
+    };
+
+    instance.port.onmessage?.({
+      data: {
+        type: 'set-stretch-parameters',
+        params: { overlapMs: 12, quickSeek: false },
+      },
+    });
+
+    const inputLeft = new Float32Array([1, 2]);
+    const outputLeft = new Float32Array(2);
+    const outputRight = new Float32Array(2);
+    outputFrameCount = 0;
+
+    const ok = instance.process([[inputLeft]], [[outputLeft, outputRight]], {
+      pitch: new Float32Array([1]),
+      pitchSemitones: new Float32Array([0]),
+      playbackRate: new Float32Array([1]),
+    });
+
+    expect(ok).toBe(true);
+    expect(setStretchParameters).toHaveBeenCalledWith({
+      overlapMs: 12,
+      quickSeek: false,
+    });
+  });
+
   it('handles mono input/output channel fallback and buffer resize path', async () => {
     await import('./processor.js');
 

packages/audio-worklet/src/processor.ts

@@ -23,6 +23,7 @@ import type {
   InterpolationStrategyParams,
   RateTransposerInterpolationStrategy,
   SampleBufferType,
+  StretchParameters,
 } from '@soundtouchjs/core';
 
 const PROCESSOR_NAME = 'soundtouch-processor';
@@ -71,9 +72,15 @@ interface SetInterpolationStrategyParamsMessage {
   params: Partial<InterpolationStrategyParams>;
 }
 
+interface SetStretchParametersMessage {
+  type: 'set-stretch-parameters';
+  params: StretchParameters;
+}
+
 type ProcessorMessage =
   | SetInterpolationStrategyMessage
-  | SetInterpolationStrategyParamsMessage;
+  | SetInterpolationStrategyParamsMessage
+  | SetStretchParametersMessage;
 
 /**
  * Audio render-thread processor that applies SoundTouch transformations to stereo blocks.
@@ -114,6 +121,7 @@ class SoundTouchProcessor extends AudioWorkletProcessor {
   private _outputSamples: Float32Array;
   private pendingInterpolationStrategy: RateTransposerInterpolationStrategy | null;
   private pendingInterpolationStrategyParams: Partial<InterpolationStrategyParams> | null;
+  private pendingStretchParameters: StretchParameters | null;
 
   /**
    * @param options Worklet constructor options provided by the main thread.
@@ -151,6 +159,7 @@ class SoundTouchProcessor extends AudioWorkletProcessor {
     this._outputSamples = new Float32Array(128 * 2);
     this.pendingInterpolationStrategy = null;
     this.pendingInterpolationStrategyParams = null;
+    this.pendingStretchParameters = null;
 
     const port = this.port;
     if (port !== undefined) {
@@ -162,6 +171,10 @@ class SoundTouchProcessor extends AudioWorkletProcessor {
         }
         if (message.type === 'set-interpolation-strategy-params') {
           this.pendingInterpolationStrategyParams = message.params;
+          return;
+        }
+        if (message.type === 'set-stretch-parameters') {
+          this.pendingStretchParameters = message.params;
         }
       };
     }
@@ -194,6 +207,18 @@ class SoundTouchProcessor extends AudioWorkletProcessor {
       }
       this.pendingInterpolationStrategyParams = null;
     }
+
+    if (this.pendingStretchParameters !== null) {
+      try {
+        this._pipe.setStretchParameters(this.pendingStretchParameters);
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.info(
+          '[SoundTouchProcessor] Failed to update stretch parameters.',
+        );
+      }
+      this.pendingStretchParameters = null;
+    }
   }
 
   process(

packages/core/README.md

@@ -106,6 +106,29 @@ st.outputBuffer.extract(outputBuffer, 0, 4096);
 | `registerInterpolationStrategy`       | Registers a custom interpolation strategy id (or kernel)                 |
 | `resolveInterpolationStrategyRuntime` | Resolves runtime kernel + normalized params for an option                |
 | `setActiveInterpolationStrategy`      | Changes process-wide default interpolation strategy id                   |
+| `StretchParameters`                   | Type for WSOLA timing parameters passed to `setStretchParameters`        |
+
+#### WSOLA timing parameters
+
+`SoundTouch` exposes `setStretchParameters()` to tune the time-stretch algorithm at runtime:
+
+```ts
+const st = new SoundTouch({});
+
+st.setStretchParameters({ overlapMs: 12 });             // crossfade overlap only
+st.setStretchParameters({ quickSeek: false });          // exhaustive correlation search
+st.setStretchParameters({ sequenceMs: 80, seekWindowMs: 20 }); // manual windows
+st.setStretchParameters({ sequenceMs: 0 });             // back to auto
+```
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `sequenceMs` | auto (50–125 ms) | Processing window length; `0` = auto-calculate from tempo |
+| `seekWindowMs` | auto (15–25 ms) | Seek window length; `0` = auto-calculate |
+| `overlapMs` | 8 ms | Crossfade overlap length |
+| `quickSeek` | `true` | Fast multi-pass seek; `false` = exhaustive (better quality, slower) |
+
+`Stretch` also exposes individual `overlapMs` (getter/setter) and `quickSeek` (getter/setter) properties.
 
 ## Constructor API (breaking)
 

packages/core/src/SoundTouch.spec.ts

@@ -205,6 +205,20 @@ describe('SoundTouch', () => {
     });
   });
 
+  describe('setStretchParameters', () => {
+    it('delegates to stretch and updates overlapMs', () => {
+      const st = new SoundTouch({});
+      st.setStretchParameters({ overlapMs: 14 });
+      expect(st.stretch.overlapMs).toBe(14);
+    });
+
+    it('delegates quickSeek flag to stretch', () => {
+      const st = new SoundTouch({});
+      st.setStretchParameters({ quickSeek: false });
+      expect(st.stretch.quickSeek).toBe(false);
+    });
+  });
+
   describe('runtime interpolation strategy controls', () => {
     it('switches interpolation strategy through SoundTouch API', () => {
       const st = new SoundTouch({ interpolationStrategy: 'lanczos' });

packages/core/src/SoundTouch.ts

@@ -31,6 +31,7 @@ import {
   createFifoStretchInputBufferAdapter,
   default as Stretch,
 } from './Stretch.js';
+import type { StretchParameters } from './Stretch.js';
 import CircularSampleBuffer from './CircularSampleBuffer.js';
 import FifoSampleBuffer from './FifoSampleBuffer.js';
 import {
@@ -218,6 +219,23 @@ export default class SoundTouch {
     this.transposer.setInterpolationStrategyParams(params);
   }
 
+  /**
+   * Applies a partial set of WSOLA timing parameters to the stretch stage.
+   *
+   * @remarks
+   * Delegates directly to {@link Stretch.setStretchParameters}. Only the provided
+   * fields are updated; omitted fields remain unchanged. Pass `sequenceMs: 0` or
+   * `seekWindowMs: 0` to switch that dimension back to auto-calculation.
+   *
+   * @param params Partial set of WSOLA timing parameters to apply.
+   *
+   * @example
+   * st.setStretchParameters({ overlapMs: 12, quickSeek: false });
+   */
+  setStretchParameters(params: StretchParameters): void {
+    this.stretch.setStretchParameters(params);
+  }
+
   /**
    * Sets the pitch multiplier and recomputes the derived pipeline rate and tempo.
    *