VesselDSP Docs

VesselDSP is a TypeScript workspace for audio-circuit conversion, headless stompbox layout artifacts, and optional React controls for core panel data.

The published packages are:

Package	Use it for
@vessel-dsp/core	Parse, validate, inspect, and convert circuit documents through CircuitDocument, .vdsp, LTspice .asc, LiveSPICE .schx, legacy SPICE netlists, and tscircuit Circuit JSON.
@vessel-dsp/stompbox	Turn parsed .vdsp or CircuitDocument panel data into drill layouts, print templates, preview SVG/GLB artifacts, live preview state patches, and GLB state-target validation.
@vessel-dsp/control-ui	Render core Panel controls in React with default CSS, class hooks for Tailwind-style customization, and a theme provider.
@vessel-dsp/visual-effects	Share Three.js toon, grain, and glitch effect preset helpers across generated preview viewers.
@vessel-dsp/amp	Generate deterministic amplifier preview layouts, Three.js object graphs, and GLB preview payloads from compact amp profiles.
@vessel-dsp/cabinet	Generate deterministic speaker cabinet preview layouts, Three.js object graphs, and GLB preview payloads from compact cabinet profiles.
@vessel-dsp/compiler	Compile .vdsp / CircuitDocument schematic data into executable simulation Program ROMs (version 0.1.0, not yet published to npm).
@vessel-dsp/runtime	Run compiled Program ROMs through a real-time MNA simulation runtime and solver console (version 0.1.0, not yet published to npm).
@vessel-dsp/chain	Build a headless audio signal chain graph: guitar input profiling, compiled circuit runtimes, amp shaping, NAM playback, cabinet IR convolution, and master output (version 0.1.0, not yet published to npm).
@vessel-dsp/player	Embed a <vessel-player> custom element shell (transport, pickers, pre-rendered fallback) with a fake-engine seam; real-time audio waits on extraction phase 2 (version 0.1.0, not yet published to npm).

Core and stompbox are headless. They do not ship a browser editor or custom schematic rendering surface. Realtime simulation lives in the newer workspace packages: @vessel-dsp/compiler lowers source schematics to simulation programs, @vessel-dsp/runtime solves them, @vessel-dsp/chain arranges runtimes with profiling, amp shaping, NAM, and cabinet IR nodes, and @vessel-dsp/player provides the <vessel-player> embed shell with a pre-rendered fallback until the real-time audio path lands. Core still treats .vdsp as the portable source-visible CircuitDocument for those hosts: downstream apps can render a source-like schematic, simulate a lowered runtime graph, and explain which source sections became explicit primitives, MNA islands, reusable kernels, macro DSP, or view-only evidence. Use downstream tscircuit applications to render or edit emitted Circuit JSON. See the Signal Chain guide to arrange compiler, runtime, and chain nodes.

Core data flow

.vdsp / .asc / .schx / .cir / .net / .circuit.json
  -> source-specific parser
  -> CircuitDocument
  -> Circuit JSON / .vdsp / .asc / .schx / legacy netlist output

CircuitDocument is the normalized in-memory model used for conversion. Source fidelity comes first: unsupported, synthesized, runtime-lowered, or lossy data should be reported through diagnostics or host metadata instead of silently converted into schematic semantics.

Stompbox data flow

.vdsp / CircuitDocument
  -> core parse and validation
  -> declared or generated physical placement
  -> drill layout / A4 print SVG / preview SVG / preview GLB / live preview state patches / GLB state-target validation

When .vdsp panel placement exists, stompbox preserves it. When common enclosure hardware is missing, stompbox owns deterministic mechanical defaults for knobs, jacks, footswitches, status LEDs, and the optional 9V connector.

Control UI data flow

.vdsp / CircuitDocument
  -> core extractPanel()
  -> control-ui React controls
  -> PanelMessage callbacks to a host runtime

Control UI is intentionally optional. The consuming app still owns parsing, state transport, audio runtime integration, and any multi-pedal namespacing.

Generated 3D preview data flow

amp / cabinet profile
  -> profile validation
  -> deterministic generated layout
  -> Three.js Object3D / generated GLB preview payload
  -> optional shared visual-effects preset

Amp and cabinet previews are approximate product visualization, not CAD-exact manufacturer models. Use them for realtime browser previews, catalog sketches, and generated docs assets where a simple rectangle box, controls, grille, and brand/model metadata are enough.

Start reading

• Getting Started covers installation and a first conversion.
• Supported Formats explains the conversion contract and lossy export policy.
• Pro Co Rat Schematic walks through a LiveSPICE pedal fixture.
• Stompbox Layouts covers drill templates, previews, generated hardware defaults, and live preview state.
• Generated 3D Previews covers amp/cabinet profile visualization and reusable Three.js effects.
• Controls explains how core derives Panel controls from imported schematics and .vdsp metadata.
• Control UI covers React controls, default CSS, class hooks, and theming.
• Signal Chain covers headless guitar signal chains with input profiling, amp shaping, cabinet IR convolution, and NAM playback.
• Compiler covers compiling .vdsp schematics into simulation Program ROMs.
• Runtime covers running compiled programs through the MNA solver console.
• API Reference is generated from the public TypeScript entrypoints.