SoundTouchJS

SoundTouchJS is a toolkit for real-time audio manipulation in the browser, including playback speed control (time stretching), pitch shifting, and key transposition.

Core Components

• @soundtouchjs/core: The main engine and building blocks for custom pipelines or offline processing.
• @soundtouchjs/stretch-phase-vocoder: An alternative time-stretch algorithm (phase vocoder) for smoother results at extreme playback ratios. Can be used as a drop-in stage in SoundTouch or standalone.
• Interpolation Plugins: Swappable modules for tuning the quality vs. CPU cost of sample-rate conversion. Available strategies include lanczos, linear, hann, blackman, and kaiser.

The @soundtouchjs/core package is designed for building custom audio pipelines, offline processing, or integration into non-browser environments.

Note: If you are building real-time browser audio, you should use @soundtouchjs/audio-worklet instead.

The SoundTouch class is the core engine for real-time pitch and key manipulation. It functions by chaining RateTransposer and Stretch stages into a single processing pipeline.

When to use it:

• Use SoundTouch directly if you are building a custom, low-level audio pipeline.
• Do NOT use it directly for browser playback. Instead, use SoundTouchNode from @soundtouchjs/audio-worklet, which is designed to manage the pipeline and Web Audio integration automatically.

The interpolation strategy registry is a process-wide lookup table managed by @soundtouchjs/core. It tracks which interpolation strategies are available for use in SoundTouch and RateTransposer.

When to use it: While most developers simply pass a strategy ID when constructing SoundTouch or SoundTouchNode, you should use the registry directly when:

• Building plugins that provide new interpolation kernels.
• Testing if specific strategies are available in the current environment.
• Changing the process-wide default strategy at runtime.

The FifoSampleBuffer is a resizable First-In-First-Out (FIFO) container optimized for interleaved stereo frame processing. It is designed to manage audio data as it moves through a processing pipeline, ensuring that the oldest data is handled first. This is particularly useful for audio effects that require historical context (memory of previous samples).

import { FifoSampleBuffer } from '@soundtouchjs/core';

// Initialize a buffer with an optional maximum number of frames
const buffer = new FifoSampleBuffer(1024);

Choosing between the default WSOLA and the Phase Vocoder depends on your application's requirements:

| Feature | WSOLA (Default) | Phase Vocoder | | :--- | :--- | : | | Quality at extreme ratios | Artifacts above 2× | Smooth at all ratios | | Transient preservation | Better (time-domain) | Worse (frequency smearing) | | Computation | Lower | Higher (FFT per hop) | | Startup latency | Lower | fftSize samples | | Artifacts | Clicks / repeats | "Phasiness" / smearing |

Recommendation: Use WSOLA for most musical applications at moderate tempos (0.5–2×). Use the Phase Vocoder for very slow-motion or very fast playback, or when WSOLA artifacts are unacceptable.

Choose between the standard SoundTouchNode and the FormantCorrectionNode based on your use case:

When working in a browser environment, keep the following in mind:

1. Tempo Control: The tempo property on the Stretch class is an internal DSP control. It is not exposed as an AudioParam.
2. AudioWorklet Integration: For browser-based audio processing, you should prefer calling SoundTouchNode.setStretchParameters(). This ensures that parameter updates are correctly queued on the render thread.

Because AudioBufferSourceNode is a 'one-shot' node (it cannot be restarted once stopped), you must manage playback state manually to support pause/resume and tempo changes.

To keep state coherent, track these three variables:

1. playStartTime: The audioCtx.currentTime when playback started/resumed.
2. pauseOffset: The source position in seconds where playback should start next.
3. currentTempo: The current playback rate.

Calculating the new offset when pausing or changing tempo: pauseOffset += (audioCtx.currentTime - playStartTime) * currentTempo

The RateTransposer class is a building block used to change the playback speed (rate) of audio by resampling. It performs sample-rate transposition and interpolation as a single stage in the SoundTouch processing pipeline. While most users will interact with the higher-level SoundTouch class (which uses RateTransposer internally), you should use RateTransposer directly if you are building a custom audio processing pipeline.

import { RateTransposer } from '@soundtouchjs/core';

// Example initialization
const transposer = new RateTransposer();

When changing speed or pitch, SoundTouchJS uses interpolation strategies to estimate in-between audio samples. Choosing a strategy involves a trade-off between CPU cost, latency, and sound quality.

Available Strategies