A plugin format native to the web.
A Jig is a plugin conforming to this specification.
A plugin is a dereferenceable IRI. Fetching it is installing it. What comes back says what the plugin is, what signals it accepts and produces, what it needs from a host, and where its WebAssembly module, its AudioWorklet processor and its user interface are, each with an integrity digest. There is no registry, and no install step distinct from having fetched it.
The main purpose of this repository is to host the Jig specification: the normative documents in docs/, the vocabulary and shapes in vocabs/, and the examples that validate against them. The code is here too, as sample applications that show the specification working and test it by implementing it: Jiggy, a host that runs the plugins in a browser (below), a second host that runs them as a VST3, 36 worked plugins, and a validator that enforces the specification on its own files. None of it is required to use the format.
The specification is published at danja.github.io/jigdaw, rendered from the markdown in docs/, which is the authoritative copy.
curl -H "Accept: text/turtle" https://strandz.it/jigdaw/plugins/pulse/That is the whole install path. The profile is Turtle, its subject is its own IRI, and every
resource it names carries a sha384 digest that a host MUST check before running anything.
<>
a jig:WebPlugin , trn:PluginProfile ;
rdfs:label "Pulse" ;
trn:role trn:Instrument , trn:AudioInstrument ;
trn:accepts trn:Midi ;
trn:produces trn:Audio ;
trn:requires jig:MidiEvents ;
jig:audioOutputs 1 ; jig:outputChannels 2 ; jig:latencyFrames 0 ;
jig:module <#module> ;
jig:processor <#processor> ;
lv2:port <#waveform> , <#attack> , <#release> , <#cutoff> , <#gain> .
<#module>
a jig:Module ;
jig:location <pulse.wasm> ;
jig:abi jig:Abi1 ;
jig:integrity "sha384-g3DvRxgIQlAOtAs4igRA3txWG2twyHsPR5zgZxM2iods9jcnIcPebid0qCDgohrE" .trn: says what it is musically, lv2: describes its parameters, and jig: says what it
takes to run it in a browser. Which vocabulary a statement belongs to is not a detail: the
first two are shared with other projects and only the third is ours.
And it plays. bin/host.js is a minimal reference host, in Node, no browser: it loads a
plugin by that same IRI and renders real audio to a WAV file.
node bin/host.js https://strandz.it/jigdaw/plugins/pulse/ --note 69@0:0.5 --out note.wavbin/jig.js is the same host with a jalv-like surface: list the local plugins, info
one plugin's ports, panel to draw its generated control surface, render for audio,
and shot to screenshot the panel. Every plugin drawn that way is on the
plugin gallery.
The format is not new. It extends the profile vocabulary published at plugin-universe.com/about/profiles and already in use across hundreds of plugins, adding the terms a browser needs to fetch and run one. A profile written for that catalogue stays valid here.
This is the deliverable, and it is normative. RFC 2119 throughout.
| Document | What it governs |
|---|---|
| host-plugin-contract.md | What a host guarantees and what a plugin must do. The others hang off this one |
| plugin-profiles.md | How to describe a plugin, and how it extends the published format |
| messaging.md | The wire format between host, processor and user interface |
| latency.md | Compensation, and what a graph with feedback does |
| module-abi.md | The optional WebAssembly ABI, for a host with no JavaScript |
| plugin-bundles.md | Sending a plugin as a file, with provenance and signing |
| plugin-collections.md | A list of plugins as one Turtle file at one URL, and how a host opens it |
| project-format.md | The session graph, which carries plugin IRIs and so stays portable |
| webmcp.md | The tool surface an agent drives a host through |
| namespace.md | What http://purl.org/stuff/jigdaw/ serves and how its terms resolve |
The vocabulary is vocabs/jigdaw.ttl, in the namespace http://purl.org/stuff/jigdaw/. Every
profile is validated against SHACL Core shapes in vocabs/shapes.ttl, which is a gate rather
than a diagnostic: JigDAW ingests profiles from origins it does not control.
npm run validate -- examples/reference-profile.ttlexamples/ holds a reference profile, a reference session and a reference provenance record, each of which validates, and a counterexample for each, each of which violates every constraint once and must not.
36 worked plugins are in plugins/: a subtractive synth,
a reverb, a compressor/expander/limiter/clipper with a side chain input, a transport-synced
bass line generator, a transport-synced drum pattern generator, a synthesised drum
instrument, a phrase-aware melody generator, a long-form bass section planner, a
learning MIDI harmonizer, a learned counter-melody processor and a twelve-voice
tonal instrument, all eleven written in Rust
and compiled to WebAssembly; the
8-Bit 8asterd, which is the firmware of an
Arduino driving three AY-3-8910 chips compiled
unedited from C++ and driving a model of those chips; Mop, an
OPL3 FM General MIDI instrument compiled from C with its AdLib bank embedded;
three REAPER JSFX effects converted
by bin/jsfx-import.js, which run under the shared bytecode interpreter in
plugins/_jsfx-runtime/ rather than each compiling their own DSP to
WebAssembly; Tremolo, which declares no jig:module at all, its whole
signal path the AudioWorklet processor, plain JavaScript, which jig:module has always
permitted and which nothing exercised until this one; Boost, a gain
stage in C++ meant to be copied rather than shipped: the minimal starting point for a new
WebAssembly plugin, everything in it beyond one line of DSP being ABI wiring;
Ferrite, a neural amp model and a cabinet impulse response in series, the
first plugin here depending on a real external crate (nam-rs)
rather than hand-writing every line of DSP; Squelch, a resonant
lowpass that an envelope follower sweeps open on every note, plain JavaScript like Tremolo;
and Quefrency, which splits its input through the cepstrum into formants
and harmonics and shifts each independently, the first plugin here with latency to
compensate (its design); and
Lookahead, a switchable lookahead delay in plain JavaScript whose
latency changes while running and which the host recompensates
(its design); and
Parameq, a six-band stereo parametric equalizer in C++ with peak,
shelf, pass and notch shapes per band and a graphic curve editor of its own.
Each is a directory holding a profile.json, a build script, the .wasm, the processor and a
generated profile.ttl. The profile is generated because a digest written by hand goes stale
on the next build, silently.
A plugin that ships no user interface is not degraded. Its panel is generated from its
lv2:port declarations, which is why the accessibility rules in
AGENTS.md are load bearing: one accessible generator makes every plugin
accessible.
docs/for-plugin-authors.md is the guide, and docs/for-hosts.md is the same for anyone implementing the other side.
node bin/bundle.js plugins/pulse --by https://you.example/#me --key ~/.config/jigdaw/keys/ed25519.json
node bin/verify.js plugins/pulse/pulse.jig --onlineTwo forms, both carrying the canonical IRI: a flattened profile whose locations are data:
URIs, which any host already reads, and a .jig archive that unpacks into a working plugin
origin. Both carry a provenance record and can carry an Ed25519 signature over a canonical
form of the graph. See plugin-bundles.md.
The code in this repository is sample code for the specification, and the first sample is a working digital audio workstation in the browser, called Jiggy: a plugin rack, an arbitrary directed graph with cycle refusal and latency compensation, a channel strip, transport, a catalogue search, sessions that save and reopen as RDF, and a WebMCP surface an agent can drive. It is a reference host, and a real one, and you can use it without reading the specification.
It is here to exercise the specification. A normative document with no implementation is a claim about behaviour nobody has, and most of what this project has learned came from the host refusing to do what the specification said. It is not the point of the repository; if it disappeared, the format would still be the thing.
npm install
npm run serve # http://127.0.0.1:8748/Needs Node 20.11 or later. PORT and HOST set where it listens, and it is loopback only by default.
Jiggy on its own, without the specification, the tests or the plugin sources, is one zip of about 3 MB: the page, the plugins it loads, and the small server that gives the page its plugin catalogue.
unzip jiggy.zip -d jiggy && cd jiggy
npm install --omit=dev
npm start # http://127.0.0.1:8748/Get the zip from the App zip workflow on this repository's Actions tab (every push to main
leaves one as an artifact), or from the Releases page for a tagged version. To build it yourself:
npm install
npm run build:app # writes dist/jiggy.zipWhat goes in is decided by bin/package-app.js, which reads each plugin's own profile for the files it needs, and tests/bin/package-app.test.js starts the server from the unpacked folder and asks for everything the page asks for. docs/deployment.md covers putting it behind a web server.
architecture.md covers the layers and why they are where they are. The separation that matters is that RDF persistence, the project model, the compiled audio graph and real-time processing never see each other's problems.
A format with one host is a format with an implementation, not a specification. There are three that run Jigs, and a fourth that can be packaged for.
./install.sh # VST3 into ~/.vst3; --all for the CLAP and LV2 tooIn this repository, C++ over DPF, loading Jigs by
IRI so a desktop DAW can open them. It was built as a sanity check on the specification and
earned its keep before it made a sound: it could not load a Jig at all, because the
only thing the contract guaranteed was a JavaScript AudioWorklet. The specification had
accidentally made itself browser-only. module-abi.md is the answer, and
every worked plugin whose module compiles per plugin now declares an ABI. The three converted
from JSFX are the exception: their module is the shared interpreter in
plugins/_jsfx-runtime/, and an ABI's fixed, no-payload calling
sequence has nowhere to carry the compiled script a native host would need to run one. See
native/jigdaw-adapter/README.md.
Transmission, a generative audio workstation for
Linux, hosts Jigs alongside VST3 ones:
its JigDAW page is the documentation.
Adding one to a project is a node typed trn:JigdawPlugin carrying a trn:pluginIri, and
nothing else; both module ABIs are implemented, port counts are read from the profile rather
than from what the project guessed, and a plugin declaring no jig:abi is refused with a
message saying it is private to its JavaScript processor.
It is a different kind of evidence from the adapter. Rather than reimplementing the contract
it links jigdaw_core, the portable half of the adapter above, which is the first time
anything outside this repository has consumed it. So it does not independently confirm the
specification, and it does show that the code written to read a profile, verify a digest and
call a module travels, and that a Jig runs in an application written for something
else.
It has already sent one defect back. Profile.cpp parsed numbers with std::stof, which
reads the decimal separator from the global C locale; GTK calls setlocale(LC_ALL, ""), so
under a comma-decimal locale every fractional lv2:default, lv2:minimum and lv2:maximum
in every profile parsed as zero. Fixed here and recorded in MISTAKES.md. A
host nobody here wrote is the only thing that was ever going to find that.
node bin/wam.js plugins/pulseWeb Audio Modules is the existing standard for web-native
plugins, and JigDAW was specified without reference to it. bin/wam.js packages a plugin as a
WAM: same profile, same WebAssembly, same processor, with the packaging a WAM 2.0 host expects
generated from the profile. 21 kB, standalone, and it carries the profile's digests, which the
WAM API has no way to express at all.
The other direction works too, under contract section 12, and costs something the contract states rather than hides. A WAM's entry point is a module the host imports into its own document, so it runs with the host's privileges and cannot be sandboxed. A foreign plugin is therefore a separate class, outside sections 9.1 and 11: its container is verified as one archive, consent is bound to that container's digest, and it is marked wherever it appears. Supporting none of it still conforms.
web/foreign/probe.html is the check, since a service worker is not reachable from a test.
Measured in Chrome: a real Web Audio Module, loaded from a verified container and passing
audio. See wam.md.
The specification is complete and normative. The browser host implements it and runs all 9 worked plugins; the native adapter fetches, verifies, instantiates and sounds the two that produce audio, under its own tests; Transmission runs them in a workstation written for VST3. A session saves and reopens carrying the IRIs that make it portable. Phases and their state are in plan.md; TODO.md is what is open and HUMANS.md is the short list of things only a person can do.
npm install && npm testREADME.agents.md is the entry point for machine consumers. AGENTS.md holds the conventions. docs/first-thoughts.md is the original sketch, kept as written.
Apache 2.0. See LICENSE.