Skip to content
v0.1.0-alpha.3
On this page

Getting Started

Build the Bridge from source, process your first local VST3 effect in Live Studio, and verify each layer.

Start with the repository's Live Studio. You need a browser, the Rust Bridge, a host worker and a VST3 effect on the same computer. Even when the webpage is hosted remotely, the Bridge runs on the user's machine.

Prepare your environment

ComponentRequirement and check
Node.jsUse 22; check with node --version.
RustUse stable from rust-toolchain.toml; inspect it with rustc --version.
macOS build toolsxcode-select -p should print the developer tools path. Install with xcode-select --install if needed.
BrowserStart with current desktop Chromium, with AudioWorklet, secure context and cross-origin isolation.
VST3Install a stereo input/output effect matching the host worker's CPU architecture. An AU-only installation is insufficient.

macOS is the first runtime target. Responsive mobile styling does not mean a phone can host desktop VST3 plugins. Windows/Linux plugin compatibility requires separate validation.

1. Install workspace dependencies

Shell
git clone https://github.com/backrunner/wvst.gitcd wvstnpm ci

Run subsequent commands from the repository root. @wvst/web is a local workspace package; no separate npm installation or adjacent Svedocs checkout is required.

2. Build and start the Bridge

Build both executables:

Shell
cargo build -p wvst-bridge-server -p wvst-host-worker

In terminal A:

Shell
WVST_TOKEN=local-dev-token \WVST_HOST_WORKER=target/debug/wvst-host-worker \  target/debug/wvst-bridge-server serve

Expect:

Text
wvst-bridge-server listening on ws://127.0.0.1:35876

Keep terminal A running. The standalone CLI requires a nonempty WVST_TOKEN. This value is a local development example; keep real tokens out of frontend bundles and source control. WVST_HOST_WORKER points at the worker you built; building only the Bridge does not produce that executable.

For an optimized build, use a matching pair of release binaries:

Shell
cargo build --release -p wvst-bridge-server -p wvst-host-workerWVST_TOKEN=local-dev-token \WVST_HOST_WORKER=target/release/wvst-host-worker \  target/release/wvst-bridge-server serve

For published portable previews, check Releases and follow Versions and releases to select and verify an archive. Drafts are not public downloads. The source-build instructions above remain available.

To use the hosted Studio, add WVST_ALLOWED_ORIGINS=https://wvst.pwp.sh to the Bridge startup command above and restart it. The local docs server below is only needed for local development. Browser local-network requirements are covered in Configuration and deployment.

3. Start the docs and Studio

In terminal B:

Shell
npm run docs:dev

This builds the Web SDK and starts Svedocs. Open the printed address (normally http://localhost:5173) and visit Live Studio. If the port is occupied, use the actual URL printed by the server.

The dev server supplies:

Text
Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corp

Run this in the page console; all three values should be true:

JavaScript
({  secureContext: window.isSecureContext,  crossOriginIsolated: window.crossOriginIsolated,  sharedArrayBuffer: typeof SharedArrayBuffer === 'function'})

A secure localhost page is not automatically cross-origin isolated. Do not open the HTML as a file or replace the server with one that omits these headers. For hosting, see Configuration and deployment.

4. Hear your first effect

  1. Expand advanced connection settings. Enter ws://127.0.0.1:35876 and token local-dev-token, then connect. The initial automatic attempt has no token; fill it in if authorization fails.
  2. Choose Try a synth loop or drop a browser-supported audio file. Preview original audio first to verify your output device.
  3. Select and mount a VST3 effect. If the list is empty, rescan and inspect scan failures.
  4. Press Play, adjust parameters and compare with bypass. Confirm the effect is enabled in the signal path.
  5. Expand Processing details to inspect queues and error counters. Output meters respond to actual audio.

macOS scan paths include /Library/Audio/Plug-Ins/VST3 and ~/Library/Audio/Plug-Ins/VST3. Discovery does not establish channel-layout, licensing or processing compatibility.

5. Stop and reconnect

Pause playback, then remove effects or disconnect the Bridge. Studio releases its instances and audio streams. Remount effects after reconnecting. Finally, press Ctrl+C in terminal A to stop the Bridge and in terminal B to stop the docs server.

Refreshing the page does not preserve the rack or plugin state. Application persistence requires the SDK's state snapshot APIs.

First diagnostic checkpoints

SymptomNext check
Bridge does not startToken, occupied port and executable paths.
Browser cannot connectSame computer, matching endpoint and browser local-network restrictions.
Scan succeeds but mount failsWorker path, plugin architecture, class ID and channel layout.
Mounted effect is silentBypass to verify the source, then check instance state, audio-worker authorization and counters.

Inspect local diagnostics:

Shell
WVST_HOST_WORKER=target/debug/wvst-host-worker \  target/debug/wvst-bridge-server diagnose

diagnose inspects configuration and worker discovery. It does not process real plugin audio and can run without a token. See Troubleshooting for recovery steps.

Next steps