Web Integration

Connect one local stereo VST3 effect to your application's existing AudioContext. First complete Getting started and verify the Bridge/plugin in Studio, then work on your own integration.

Bundling and browser prerequisites

Run npm run build:web in this repository and consume @wvst/web through a workspace dependency. The package is currently private; npm install @wvst/web is not a published installation path.

The example uses Vite's ?worker and ?url imports. TypeScript apps need vite/client types. Other bundlers must emit an independent Worker module and serve the AudioWorklet entry as a JavaScript URL. Create neither a Worker nor an AudioContext during server rendering.

The page needs a secure context, AudioWorklet, SharedArrayBuffer and cross-origin isolation. requireLowLatency: false only skips the SDK check; it does not provide a non-SAB audio fallback. See Configuration and deployment for headers.

Let the user choose a plugin

Use client.plugins.list({ rescan: true }) to obtain both plugins and failures. Present plugin classes and obtain the selected pluginId and classId; do not assume plugins[0] or classes[0] exists.

If scan metadata lacks a class ID, query client.plugins.factoryInfo({ path }) and let the user select an audio component class. Discovery does not establish 2-in/2-out compatibility. Preserve mount errors so the user can try a compatible effect.

Mount one effect

Save this as mount-effect.ts in a Vite app. The caller owns the source and AudioContext; the helper owns its connections, instance and worklet. Disconnect any direct source-to-destination edge before mounting, or dry and wet signals will both play.

The control socket and audio-worker socket each complete bridge.hello. createHelloRequest() does not retain the original token, so explicitly add it to the worker handshake.

TypeScript
1import {2  WVSTClient,3  WVSTBridgeWorkerClient,4  configureLoopbackAudioWorkletNode,5  createLoopbackSharedBuffers,6  readLoopbackMetrics,7  type InstanceDescriptor8} from '@wvst/web';9import BridgeWorker from '@wvst/web/bridge-worker?worker';10import processorUrl from '@wvst/web/loopback-processor?url';1112const workletModules = new WeakMap<AudioContext, Promise<void>>();1314export async function mountEffect(15  context: AudioContext,16  source: AudioNode,17  options: { pluginId: string; classId: string; token: string; endpoint?: string }18) {19  const endpoint = options.endpoint ?? 'ws://127.0.0.1:35876';20  let client: WVSTClient | undefined;21  let worker: Worker | undefined;22  let transport: WVSTBridgeWorkerClient | undefined;23  let instance: InstanceDescriptor | undefined;24  let node: AudioWorkletNode | undefined;25  let connected = false;26  let disposePromise: Promise<void> | undefined;2728  function dispose(): Promise<void> {29    return disposePromise ??= (async () => {30      const errors: unknown[] = [];31      const attempt = async (operation: () => unknown) => {32        try { await operation(); } catch (error) { errors.push(error); }33      };34      if (connected && node) await attempt(() => source.disconnect(node!));35      if (node) {36        await attempt(() => node!.disconnect());37        node.port.close();38      }39      if (instance) {40        const { instanceId, streamId } = instance;41        if (transport) await attempt(() => transport!.stopAudioStream(streamId));42        if (client) {43          await attempt(() => client!.instances.stop({ instanceId }));44          await attempt(() => client!.instances.closeStream({ instanceId }));45          await attempt(() => client!.instances.destroy({ instanceId }));46        }47      }48      if (transport) await attempt(() => transport!.close());49      worker?.terminate();50      client?.close();51      if (errors.length) throw new AggregateError(errors, 'WVST cleanup failed');52    })();53  }5455  try {56    client = await WVSTClient.connect({57      endpoint, token: options.token, requireLowLatency: true58    });59    worker = new BridgeWorker();60    transport = new WVSTBridgeWorkerClient({ worker });61    await transport.connect(endpoint);62    await transport.request('bridge.hello', {63      ...client.createHelloRequest().params,64      token: options.token65    });6667    instance = await client.instances.create({68      pluginId: options.pluginId,69      classId: options.classId,70      sampleRate: Math.round(context.sampleRate),71      maxBlockFrames: 128,72      inputChannels: 2,73      outputChannels: 274    });75    await client.instances.start({ instanceId: instance.instanceId });7677    const buffers = createLoopbackSharedBuffers({78      frames: 128, inputChannels: 2, outputChannels: 2, capacityQuanta: 479    });80    let module = workletModules.get(context);81    if (!module) {82      module = context.audioWorklet.addModule(processorUrl);83      workletModules.set(context, module);84      void module.catch(() => workletModules.delete(context));85    }86    await module;87    node = new AudioWorkletNode(context, 'wvst-loopback', {88      numberOfInputs: 1, numberOfOutputs: 1, outputChannelCount: [2],89      channelCount: 2, channelCountMode: 'explicit'90    });91    configureLoopbackAudioWorkletNode(node, buffers);92    await transport.startAudioStream({93      streamId: instance.streamId, sampleRate: instance.sampleRate,94      frames: 128, inputChannels: 2, outputChannels: 2, buffers95    });96    source.connect(node);97    connected = true;98    node.connect(context.destination);99100    return { instance, readMetrics: () => readLoopbackMetrics(buffers), dispose };101  } catch (error) {102    try { await dispose(); }103    catch (cleanupError) {104      throw new AggregateError([error, cleanupError], 'WVST setup and cleanup failed');105    }106    throw error;107  }108}

Playback and ownership

Call context.resume() in the user's play handler before starting the media or source, to satisfy browser autoplay policy. This helper does not create media elements, request microphone access or close an application-owned AudioContext.

Keep the result in your component:

TypeScript
1const effect = await mountEffect(context, source, {2  pluginId: selectedPluginId,3  classId: selectedClassId,4  token: tokenFromUser5});67// Read from a UI timer, never log inside AudioWorklet.process().8console.table(effect.readMetrics());910// Remove the effect or leave the page; handle remote cleanup errors.11await effect.dispose();

This continues the helper above; your app supplies the context, source, selection and token. Validate the path using Studio's built-in sound before substituting your own media input.

Resource	Caller responsibility
AudioContext	Resume from user interaction; close only when the whole audio session ends.
Media element and source	Create one MediaElementAudioSourceNode per media element and reuse it on reconnect.
File URL	Call URL.revokeObjectURL() when replacing a file or unmounting.
Effect session	Partial setup failures clean up; normal removal must await dispose().
Subscriptions and timers	Unsubscribe and stop timers so destroyed components no longer update.

dispose() can be called repeatedly. It attempts every cleanup step and aggregates failures. Remote requests can fail after the Bridge exits; your app should still remove local audio connections. If the component unmounts during setup, dispose the session as soon as mounting finishes, and prevent concurrent mount operations.

Multiple effects and reconnecting

This helper demonstrates one effect. A rack should share a control client and transport Worker while each slot owns its instance, buffers, node and stream. Construct source → effect A → effect B → destination; disconnect old edges before changing the graph to prevent duplicate routes.

Bypass removes a node from the signal path; it does not necessarily stop its plugin worker or eliminate its CPU use. Removal releases the instance and stream. Studio's rack-demo/audio-graph.ts and WVSTRackDemo.svelte provide the complete example.

After closure, create a new control client and Worker and repeat both handshakes. Do not reuse closed sockets or assume old instances are reusable. Save state snapshots ahead of time if recovery should restore parameters, and check plugin, class and processing configuration compatibility.

Channels, timing and metrics

The example uses 128 frames, 2-in/2-out and the actual AudioContext sample rate. Four quanta describe ring capacity, not fixed delay or delay compensation. At 48 kHz, 128 frames are about 2.67 ms; the round trip additionally includes scheduling, transport, queues and plugin latency.

readMetrics() returns queues, underflows/overflows, dropped events and transport failures, not end-to-end latency. Compare counter deltas over time so a startup underflow is not mistaken for persistent failure. See API reference for metric sources.

Instruments need a compatible zero-input or other bus arrangement and sample-offset MIDI events. Changing this effect example's input channels to zero alone does not establish instrument playback. See packages/wvst-web-examples/src/instrument and Troubleshooting.