The Book

Long-form documentation for PedalKernel — guide, reference, internals, and project notes.

This is PedalKernel’s written documentation. If you want generated type-level reference instead, jump to the API docs .

The book is organised in four parts:

Guide — narrative, start-to-finish explanations. Read these in order if you’re new.
Reference — lookup material. DSL grammar, component catalogue, Rust API primer, performance numbers.
Internals — for contributors and the curious. Where the model is circuit-exact, where it approximates, and how we validate.
Project — roadmap, contribution guide.

Every chapter renders directly from the canonical .md files in the repo, so what you read here is what contributors work from day-to-day.

Guide

Introduction — What PedalKernel is, what it isn't, and how to read the rest of this book.
How it works — The WDF compilation pipeline — from .pedal file to per-sample processing.
Physical realism — Oversampling, interstage loading, component tolerance, and thermal drift.
Hardware export — KiCad netlists, Mouser BOMs, and .pedalhw voltage-safety checks.

DSL Reference — Syntax and semantics of .pedal and .board files.
Components — Every component type available in the DSL, with syntax and variants.
Circuit provenance — Accuracy-stamp registry: what each .pedal circuit claims to model, where the schematic came from, how verified the values are, and what the engine currently does with it.
Rust API — A primer for the pedalkernel crate — parse, compile, process.
Performance — Indicative CPU budgets, FLOPS breakdown, and sample-rate scaling.
CLI & tools — Python scripts for schematics and BOMs, plus cargo bench.

Compiler internals — SPQR decomposition, stage routing, and the compiler passes that turn a .pedal file into a runnable processor.
The Component trait — How circuit elements plug into the compiler, and how to add a new one.
Controls and pots — How runtime control updates flow through the engine — binding, dispatch, and what each pot movement actually costs.
DSP blocks — The DspBlock lowering pass — how delay/tap, BBD, VCO, VCA, and spring reverb get plugged into the SPQR pipeline.
Metering and the metrics ring buffer — Real-time-safe signal and state metrics — what's recorded, how the ring buffer works, and how a UI consumes it.
Nonlinear elements — Catalogue of nonlinear devices — which are memoryless, which carry state, and which are K-method candidates.
Modeling limits — Where PedalKernel is pure WDF, where it approximates, and why.
Validation — How we verify WDF output against ngspice ground truth.