Supported Formats

@vessel-dsp/core converts source files through CircuitDocument and target-specific serializers.

Format	Extension	Support
VesselDSP Source	.vdsp, .yaml	Project-native circuit-interchange/v2 and circuit-interchange/v3 YAML documents for source-visible, simulatable CircuitDocument graphs.
LTspice	.asc	Parsed and serialized as schematic data.
LiveSPICE	.schx	Parsed and serialized as schematic data.
tscircuit Circuit JSON	.circuit.json	Imported and exported using official circuit-json schema validation.
Legacy SPICE netlist	.cir, .net, .spice	Connectivity parser and serializer support outside the v1 bidirectional Circuit JSON contract.

.vsdp and .asr are treated as typos, not aliases.

VDSP source-visible role

.vdsp is the portable circuit document a host can render as a schematic and lower into a simulator/runtime. It should preserve source-visible component identity, schematic layout, reference labels, controls, and boundary metadata so users can inspect what was modeled and what was lowered. Host runtimes may map source-visible sections to compact MNA, reusable kernels, macro DSP, or view-only evidence, but those lowerings should not erase the source-facing schematic semantics.

Keep provenance-only material outside the portable .vdsp: source-trace ledgers, private artifact paths, source hashes, and packet-local evidence belong in the consuming project’s README, catalog, validation, or source-boundary metadata.

Semantic controls

.vdsp control metadata separates user-visible labels from machine-facing runtime roles. Visible labels remain source-faithful free text. Semantic compiler roles use ControlRole on source component properties and controlInterfaces[].controlRole in structured metadata.

ControlRole is optional so uploaded schematics can remain source/read-only documents. When present, core validates it against the canonical lower-kebab role registry exported as CONTROL_ROLE_VALUES. Unknown roles are warnings for source/read-only validation, and errors when callers validate with validateDocument(document, { playbackClaim: true }).

Use deviceInterface.controls[].role for UI/control grouping tokens, not compiler semantic roles. That field continues to use lower-kebab open tokens such as gain, tone, or input-level.

Circuit JSON contract

The v1 bidirectional Circuit JSON contract covers .vdsp, .asc, .schx, and .circuit.json.

Supported Circuit JSON import elements include:

• source_project_metadata
• source_component
• source_port
• source_net
• source_trace
• schematic_component
• schematic_port
• schematic_trace
• directive-style schematic_text values prefixed with !

Unsupported PCB, fabrication, BOM, or simulation-only Circuit JSON elements must not be silently converted into schematic data. Import and export paths should emit diagnostics when data is unsupported, synthesized, or lossy.

VDSP v3 build data

.vdsp v3 can preserve reviewed physical build metadata:

• build scope
• mechanical envelopes
• BOM rows
• embedded part profiles and board footprints
• off-board wiring
• panel drill placement
• board realizations for stripboard, perfboard, breadboard-pattern protoboard, and fabricated PCB

It can also preserve self-contained visual design metadata at top-level appearance. The appearance.kind field is required inside that block and is mutually exclusive:

appearance:
  kind: stompbox
  enclosure:
    color: "#f8fafc"
    strokeColor: "#111827"

appearance:
  kind: amp
  enclosureColor: "#334155"
  appearance:
    controlPanelColor: "#f8fafc"

validateDocument() reports mixed or invalid appearance kinds with appearance-invalid, and .vdsp parsing rejects a block that combines stompbox-only and amp-only appearance data.

Converting v3 documents to formats that cannot preserve these fields errors by default. Use convertCircuitDocumentFileWithReport() with lossPolicy: "drop-with-diagnostics" only when lossy export is intentional.