dsp-graph

Visual graph editor, inspector, and debugger for gen-dsp signal-processing graphs.

Overview

dsp-graph provides a web UI (React + React Flow) backed by a Python server (FastAPI) for loading, visualizing, simulating, optimizing, building, and inspecting DSP signal graphs defined with gen-dsp's graph DSL.

Features:

• Load graphs from JSON or .gdsp DSL source (toolbar or drag-and-drop), with localStorage auto-save/restore

• .gdsp editor with syntax highlighting, autocomplete, snippets, go-to-definition, inline error markers, and debounced live preview

• Interactive React Flow canvas (pan, zoom, minimap) with ELK auto-layout and auto fit-to-view

• Canvas editing: add/delete/duplicate nodes and draw/replace/delete edges via per-input handles, with undo/redo

• Validation overlays: per-node error/warning borders and feedback-cycle highlighting

• Node inspector showing all properties

• Stateful, streaming simulation: live parameter sliders, "step N more samples", peek-value overlays, oscilloscope waveform and FFT spectrum views, with a configurable sample rate

• Multi-pass and per-pass graph optimization with before/after comparison

• C++ code generation preview with copy/download

• Binary plugin build for multiple platforms (CLAP, VST3, AU, LV2, etc.), with batch build + zip download

• Content-addressed build cache (avoids recompilation for unchanged graphs)

• Graphviz DOT and SVG export; round-trip export back to graph JSON and .gdsp

Installation

pip install dsp-graph

Or from source:

git clone https://github.com/shakfu/dsp-graph.git
cd dsp-graph
make install-dev
make frontend-build

Quick Start

dsp-graph serve

Starts the server at http://127.0.0.1:8765. Open that URL in a browser, then load a gen-dsp graph JSON or .gdsp file via the toolbar or by dragging it onto the window. Use --open to auto-open the browser on start.

CLI Options

dsp-graph serve [--host HOST] [--port PORT] [--reload] [--open] [--experimental] [--disable-build]

• --host: Bind address, 127.0.0.1 (default) or localhost. Other addresses, including 0.0.0.0, are refused.

• --port: Port (default: 8765)

• --reload: Auto-reload on code changes

• --open: Open browser on start

• --experimental: Enable experimental features (the gen~/GenExpr transpiler tab and its Max .maxpat test-patch export). Off by default; when omitted the GenExpr tab is hidden and POST /api/genexpr and POST /api/graph/export/maxpat return 404.

• --disable-build: Disable the native build endpoints (/api/build*), which compile graphs to plugin binaries on the host. Enabled by default; when set the Plugin Target build panel is hidden and every /api/build* route returns 404. Source generation (/api/generate*) is unaffected either way. Use this for a hardened, inspect-only deployment.

Security model

dsp-graph is designed for single-user, localhost use and binds only to 127.0.0.1 or localhost. Requests whose Host header names anything else get a 400, which blocks DNS-rebinding pages from reading the session token. The build endpoints generate and compile native code on the host, so the server should not be exposed to untrusted networks. For a hardened, inspect-only deployment they can be turned off entirely with --disable-build. As a safeguard against cross-origin requests from other browser tabs, all state-changing (POST/PUT/PATCH/DELETE) /api requests require a per-process session token (GET /api/session), which the bundled UI fetches automatically.

Single-worker deployment. The server runs a single worker, and this is assumed throughout: simulation sessions, the batch-build cache, and the build-cache singleton are all in-process, per-worker state. Blocking work (native builds, simulation, cache disk IO) is offloaded to a worker-thread pool so it does not stall the async event loop, but the shared dictionaries are only ever touched on the event loop, so they need no locking. Running multiple workers (uvicorn --workers N) would break session and batch-download continuity -- a request can land on a worker that does not hold its state -- and requires moving that state to a shared store first.

Development

# Install dev dependencies
make install-dev

# Run backend tests
make test

# Install frontend dependencies
make frontend-install

# Run frontend dev server (hot reload, proxies /api to backend)
make frontend-dev

# Build frontend (outputs to src/dsp_graph/static/)
make frontend-build

# Run frontend tests (Vitest)
make frontend-test

# Run full backend QA (test + lint + typecheck + format)
make qa

# Run full frontend QA (ESLint + tsc + Vitest)
make frontend-qa

# Start server with auto-reload
make dev

CI (.github/workflows/ci.yml) runs the backend lint/format/type-check/tests (Python 3.11 and 3.13) and the frontend tests + build on every push and pull request.

Architecture

Backend (Python)

• convert.py -- Core Graph <-> ReactFlow conversion layer

• server.py -- FastAPI app with SPA static serving

• security.py -- Session-token (anti-CSRF) and body-size middleware

• cli.py -- CLI entry point (dsp-graph serve)

• cache.py -- Content-addressed disk cache for build artifacts

• api/graph.py -- Graph load/validate/export/catalog endpoints

• api/simulate.py -- Per-sample simulation endpoint

• api/optimize.py -- Multi-pass optimization endpoint

• api/compile.py -- C++ code generation endpoint

• api/genexpr.py -- gen~ codebox (GenExpr) transpile endpoint

• api/maxpat.py -- Max .maxpat test-patch export endpoint (wraps maxpat.py)

• api/generate.py -- Project generation (source files, zip download, platform listing)

• api/build.py -- Binary build, batch build, and build cache management

• api/layout.py -- Auto-layout endpoint

Frontend (React + TypeScript)

• React Flow (xyflow) for graph visualization

• Zustand for state management

• CodeMirror editor with custom .gdsp language support

• Custom node types: input, output, param, dsp_node

• Vite build, outputs to src/dsp_graph/static/

API Endpoints

FastAPI also serves interactive docs at /docs (Swagger UI) and /redoc.

All /api/build* routes are enabled by default but return 404 when the server is started with --disable-build.

License

MIT