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.

Core and stompbox are headless. They do not ship a browser editor, realtime simulator, or custom schematic rendering surface. 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.

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.
• API Reference is generated from the public TypeScript entrypoints.