> Note: This text was written by Opus 5.5 # Creating an NXS plugin: .fmx author's contract Nov 13, 2026 · @Silas Gyger This is what your `.fmx` plugin must do to be valid and run in Audiotool, and what the host guarantees in return. **NXS and .fmx.** In Audiotool, a plugin device is called NXS. `.fmx` is the file format an NXS plugin is shipped in. "Create an NXS plugin" and "create an .fmx plugin" ask for the same thing: one `.fmx` file that follows this contract. **What a plugin is.** An `.fmx` plugin is a single JSON file that bundles three things: a WebAssembly module that processes audio (the DSP), an HTML page that serves as its interface (the UI), and a list of parameters. Audiotool loads it into a device with a main audio input, a sidechain input, a note input and an audio output. The same plugin runs in Studio, in Booster and in the server renderer, in real time and offline. **What this document is.** The complete set of rules a valid plugin must follow, and what the host guarantees in return. Every limit, memory address, call and message is listed here. You can pass it to an agent to check the shape of your plugin against the standard. **What it isn't.** A tutorial or getting-started guide. To learn how a plugin is built, read [the implementation guide](https://audiotool.com/blog) instead. **When a file is valid.** A file is valid only once upload accepts it. Hosts don't re-check upload rules, and loading a local file in Studio's dev mode skips upload validation, so a file that plays locally may still be rejected on upload. To check a file before uploading it, run the upload validator locally: the nxs-plugin agent skill ships it as `scripts/validate.mjs`. A copy can be older than the validator upload runs. **Wording.** "Must" and "must not" are hard rules. "Should" is a strong recommendation that a plugin or host may in rare cases deviate from. ## 1. Plugin requirements A valid .fmx plugin meets every requirement below. Files that don't are rejected on upload. Not every rule can be checked on upload. Some, such as never writing to host-owned memory at runtime (§3) or staying under the memory cap (§2), only show up while the plugin runs: breaking them passes upload but faults the device or stops it from loading (§4). ### File and manifest The file is a single UTF-8 JSON object, without a byte-order mark, of at most **5 MiB** and nesting depth ≤ 32. Keys must be unique at every level, including inside the `metadata` string. | Key | Type | Required | Content | | --- | --- | --- | --- | | `name` | string | yes | Display name, 1–255 characters, not only whitespace. | | `type` | string | yes | `vst_effect` or `vst_instrument`. Only sets how the plugin is labelled (e.g. in the preset browser). A `vst_instrument` must export `noteOn` and `noteOff`. | | `html` | string | yes | The UI document, encoded as below. Inflates to at most **10 MiB**. | | `wasm` | string | yes | The DSP module, encoded as below. Inflates to at most **10 MiB**. | | `metadata` | string or object | yes | `{ "params": [ … ] }`, normally serialized as a JSON string. | | `version` | string | no | Optional and ignored by hosts. When present, a string of at most 100 characters; any other value is rejected. No format rule. | | `versionId`, `spaceId`, `spaceVersion`, `signature`, any other key | any | no | Optional and ignored: any value, or none, is accepted. Don't rely on them. | **Encoding `html` and `wasm`:** 1. Take the raw bytes: the HTML document as UTF-8 text, or the wasm binary. 2. Compress them with gzip (RFC 1952, magic bytes `1f 8b`). Raw deflate or zlib streams are not accepted. 3. Encode the result as standard base64 (RFC 4648 alphabet `A–Z a–z 0–9 + /`, with `=` padding), on one line, with no `data:` prefix. Both strings therefore start with `H4sI`. **One file is one plugin.** A device never switches to another file or version; users add a new device to use a new version. A minimal file, with the base64 payloads and the `metadata` string shortened: ```json { "name": "Simple Gain", "type": "vst_effect", "html": "H4sIAAAAAAAAA+y9e3vb…", "wasm": "H4sIAAAAAAAAA+17d3gT…", "metadata": "{\"params\":[{\"id\":0,\"name\":\"Gain\",…}]}" } ``` The `metadata` string decodes to: ```json { "params": [ { "id": 0, "name": "Gain", "type": "gain", "automatable": true, "meta": false, "min": -60, "max": 12, "default": 0, "step": 0.1, "label": "dB", "unit": "db", "curve": "linear", "stepped": false, "choices": [] }, { "id": 1, "name": "Mode", "type": "int", "automatable": true, "meta": false, "min": 0, "max": 2, "default": 0, "step": 1, "label": "", "unit": "none", "curve": "linear", "stepped": true, "choices": ["Soft", "Hard", "Fold"] } ] } ``` ### Parameters (`metadata.params[]`) Every param must have `id` (integer), `name` (string), `min`, `max`, `default` and `step` (finite numbers) and `curve` (string). `stepped` and `automatable` are optional booleans and `choices` is an optional array of strings; if present with another type, the file is rejected. Missing optional fields mean `stepped` false, `choices` empty and `automatable` true. An integer is any integral JSON number: `2` and `2.0` both mean id 2. | Field | Requirement | | --- | --- | | `id` | Unique integer in 0–1023; at most 1024 params. Ids only need to be stable within one file. | | `name` | Non-empty and not only whitespace, at most 64 characters. | | `min`, `max`, `default`, `step` | Plain values, in the units your DSP reads (§3). Finite; `min ≤ max`; `default` in \[min, max\], bounds included. `default` doesn't have to lie on a step. | | `curve` | One of `linear`, `squared`, `cubed`, `sqrt`, `cbrt`, `exponential`. `exponential` needs `min > 0`. | | `stepped` | Needs `step > 0`. Non-empty `choices` makes a param stepped. On a non-stepped param, step is only a UI hint; values are never snapped to it. | | `choices` | At most 1024 strings. Either empty (`[]`) or exactly `(max − min)/step + 1` of them. Choice `i` is the value `min + i·step`. | | `automatable` | Defaults to true. Non-automatable params are hidden from automation but otherwise behave normally. | | `unit`, `label` | Display only. | | `type`, `meta`, any other key | Ignored. Flow emits `type` (`float`, `int`, `percent`, `gain`, …) and `meta: false`; both may be omitted. | **Defaults.** `default` is the value a new device starts with: when Studio creates a device from your file, it stores your default, normalized as below. Nothing uses it after that. Studio's Reset in a parameter's context menu currently sets the param to normalized 0 (its `min`), not to `default`, and no host ever resets params for you. If your UI offers a reset, such as a double-click, send the normalized default with `SPVFUI` (§6). A stepped default that isn't on a step reaches your DSP snapped, like any other value. **Plain and normalized values.** Hosts store each param as a normalized value n in \[0, 1\]. Your DSP reads plain values v (§3), and your UI sends and receives normalized ones (§6). With k = 1, 2, 3, 1/2, 1/3 for `linear`, `squared`, `cubed`, `sqrt`, `cbrt`: | Curve | Normalized → plain | Plain → normalized | | --- | --- | --- | | `linear`, `squared`, `cubed`, `sqrt`, `cbrt` | v = min + n^k·(max − min) | n = ((v − min)/(max − min))^(1/k) | | `exponential` | v = exp(ln(min) + n·ln(max/min)) | n = ln(v/min) / ln(max/min) | - **Stepped params** are snapped on the plain value, after the curve: v = min + round((v − min)/step)·step, clamped to \[min, max\]. Your DSP reads the snapped value, and `SPVFD` sends its normalized form. On a non-linear curve, the steps are therefore not evenly spaced in normalized space. - **Choices:** choice `i` is the plain value `min + i·step`; for a `linear` param that is normalized `i / (count − 1)`. Studio's own parameter strip currently labels and parses choices as `min + i`, which is right only for `step` 1, so use step 1 for choices. ## 2. Wasm module ### Features and limits - **Allowed:** WebAssembly 2.0 core only: mutable globals, sign-extension, non-trapping float-to-int, bulk memory, reference types, multi-value and fixed-width SIMD. A `start` section is allowed; it runs before `init`. - **Not allowed:** every feature beyond Wasm 2.0, including threads (atomics and shared memory), tail calls, exception handling, GC and typed function references, relaxed SIMD, memory64, multi-memory and extended constant expressions. Hosts don't filter features, so a local file using them may run in dev mode and still be rejected on upload. - **Limits:** at most 20 000 functions, a 4 MiB code section, 512 KiB per function body, 50 000 locals per function (parameters included), 1 000 globals, 10 000 data and element segments, and one table of at most 10 000 elements. - **Memory:** exactly one memory, defined in the module (not imported), not shared, exported as `memory`. Initial size 2–1024 pages (at least 131072 bytes, at most 64 MiB). Any declared maximum, or none, is accepted. Your memory is capped at 64 MiB (1024 pages), or your declared maximum if lower. After `init` returns, the host adds **one page** for its audio buffers on top of that; it doesn't count against your maximum or the cap, and it is not yours. A `memory.grow` past your limit fails; if the plugin then traps or aborts, that is a fault (§4). Staying under the cap is your job: upload can't see how much you allocate at runtime, so a plugin that needs more than 64 MiB, or ends `init` above 1024 pages, passes upload and then fails to load or faults. - **Data segments:** every active segment must have a constant `i32.const` offset and lie inside the initial memory. Upload rejects any active segment that overlaps a "read" or "reserved" range in §3 (65536–65791, 66048–66107, 69632–73471, 98304–131075). The free range 65792–66047 between params and transport may hold data. Passive segments aren't checked. - **Stack pointer:** put the shadow stack first: the initial stack pointer at or below 65536, growing down into 0–65535, so it never covers a host range. Put static data above the host ranges (flags in the appendix). Upload checks this best-effort. It finds the stack pointer through the `__stack_pointer` export or, failing that, a name-section entry of that name, and rejects an initial value that isn't a single `i32.const` ≤ 65536. If it finds neither, it skips the check, and stack placement is your responsibility. Modules without a stack are fine. - **Allocation:** allocate everything you need in `init`. Don't grow memory after `init`: `process` runs on the audio thread, and `memory.grow` there can stall it and cause dropouts. Growing later still works up to the cap, but it is discouraged. ### Imports Use any subset of these, with exactly these signatures. Anything else, including imported memory, tables or globals, is rejected. | Import | Signature | Use | | --- | --- | --- | | `env.abort(msgPtr, filePtr, line, col)` | `(i32, i32, i32, i32) → ()` | Calling it is a fault (§4). | | `env.hostExposeBuffer(namePtr, nameLen, ptr, floatCount)` | `(i32, i32, i32, i32) → i32` | Expose a buffer to your UI; call from `init` only (§6). | | `env.getStateString(keyPtr, keyLen, outPtr, outCap)` | `(i32, i32, i32, i32) → i32` | Read custom state; call from `onStateChanged` only (§5). | | `env.getStateInt(keyPtr, keyLen, default)` | `(i32, i32, i32) → i32` | Read custom state; call from `onStateChanged` only (§5). | Audio files aren't supported. Importing any of `env.hostOpenAudioFile`, `env.hostGetAudioFileSampleRate`, `env.hostGetAudioFileChannels`, `env.hostGetAudioFileFrames` or `env.hostReadAudioFileChannel` gets the file rejected. ### Exports | Export | Signature | Status | | --- | --- | --- | | `memory` | memory | Required. | | `init(sampleRate)` | `(f32) → ()` | Required. Called once per instance. | | `process(inL, inR, outL, outR, frames)` | `(i32 × 5) → ()` | Required (§4). | | `getAbiVersion()` | `() → i32` | Required. Body must be exactly `i32.const 1` followed by `end`: no locals, no other instructions (encoded body `00 41 01 0b`). | | `getNumParams()` | `() → i32` | Required. Body must be exactly `i32.const N` followed by `end`, with no locals and no other instructions. N ≤ 1024 and N > your largest param id. | | `reset()` | `() → ()` | Optional (§4). | | `noteOn(key, velocity)` | `(i32, i32) → ()` | Optional; export together with `noteOff` or not at all. | | `noteOff(key)` or `noteOff(key, velocity)` | `(i32) → ()` or `(i32, i32) → ()` | Optional; either form works. | | `__setArgumentsLength(n)` | `(i32) → ()` | Optional. If exported, called with 2 before every two-argument `noteOff`. | | `onStateChanged()` | `() → ()` | Optional, for custom state (§5). | | `pitchBend`, `controlChange`, `channelPressure` | any | **Rejected.** MIDI expression isn't supported. | | Any other name | | Allowed but never called. A listed name with the wrong signature is rejected. | `setTempo`, `noteOffVelocity` and `aftertouch` are never called. Read tempo from memory (§3). ## 3. Memory map The host writes every "read" range below before each `process` call. Never write to a "read" or "reserved" range: the host rewrites "read" ranges every block, and "reserved" slots are kept for future use. | Address | You | Contents | | --- | --- | --- | | 0–65535 | own | Stack. | | 65536 + 4·id, id 0–63 | read | f32 **plain** value of param `id` (already curved, snapped and clamped, §4). | | 65792–66047 | own | Free for your use (e.g. a param smoothing cache). | | 66048 | read | f64 project tempo in BPM. Always valid. | | 66056 | read | f64 song position in quarter notes at block start. Use only when 66104 is non-zero. | | 66064 | reserved | Don't read or write. | | 66072 | read | f64 samples per quarter note. Always valid. | | 66080–66103 | reserved | Don't read or write. | | 66104 | read | i32 playing flag. Test for non-zero only; 0 means ignore the position. | | 66108–67363 | own | Free for your use. | | 69632 + 4·(id − 64), id 64–1023 | read | f32 plain value of params 64 and up. Ends at 73471. | | 98304–131075 | read | Sidechain region. Never put data, stack or heap here. | | 98304 + 4·i, i < 4096 | read | f32 sidechain left, same frame index as `inL`. | | 114688 + 4·i, i < 4096 | read | f32 sidechain right. | | 131072 | read | i32 sidechain-connected flag. Ignore the sidechain buffers while it is 0. | | everything else | own | Static data and heap (every range not listed above). | **Getting a sidechain.** There is no flag to set. If your memory covers 98304–131075 at the end of `init`, you get a sidechain port for the life of the instance; if not, you never do, even if you grow memory later. The 2-page minimum ends at 131071 and doesn't cover it, so a minimal plugin gets no sidechain. If you want one, declare at least 3 initial pages, or grow before `init` returns. **Audio buffers.** The four `process` buffers live wherever the host puts them; use only the offsets you are given, only during that call. The host keeps them in the page it adds after `init` (§2 Memory). That page belongs to the host: it doesn't count toward sidechain coverage, and memory pages you didn't grow yourself aren't yours. ## 4. Runtime ### Load 1. Instantiate (your `start` section runs). 2. Params are written to memory. 3. `init(sampleRate)`, exactly once per instance. A sample-rate change gives you a fresh instance. 4. `onStateChanged()`, if you export it and the device has custom state. 5. First `process`. ### Each block 1. All params are written as plain values. 2. The transport block is written (66048, 66056, 66072, 66104). 3. If you cover the sidechain region, the flag is written, and the buffers when connected. 4. Note events are delivered. 5. `process(inL, inR, outL, outR, frames)` is called. `onStateChanged` (§5) also runs between blocks, before the next `process`, never during one. ### What you can rely on | Topic | Guarantee | Your side | | --- | --- | --- | | Block size | `frames` is anything from 1 to 4096 and may change every call. | Handle every size in that range. Don't rely on `maxBlockSize`. | | Buffers | `inL`, `inR`, `outL`, `outR` are separate, non-overlapping f32 buffers of at least `frames` samples. `inL`/`inR` carry main audio input, zeroed when unconnected. | Write `outL`/`outR` every call. | | Threading | Calls are synchronous, never concurrent; one instance per device. | None. | | Param values | Plain values: `min + n^k·(max − min)` (k = 1, 2, 3, 1/2, 1/3 for linear, squared, cubed, sqrt, cbrt) or `exp(ln(min) + n·ln(max/min))` for exponential. Stepped params arrive snapped and clamped. | Don't write param memory. | | Notes | Only if you export `noteOn`/`noteOff`. All events arrive before `process` and act at block start (no sample offsets). `noteOn` key 0–127, velocity 1–127. Two-argument `noteOff` gets velocity 0–127, 64 when unknown. Every held note is released when the transport stops. | Never expect velocity 0 in `noteOn`. | | Transport | Tempo and samples per quarter note are always valid and finite. Position at 66056 holds its last value while stopped. | Take bar length from a param or custom state: there is no time signature in the DSP. | | `reset()` | Called when the transport stops and at the start and end of an offline render. Never after load or on play, so tails carry into playback. A reset that arrives while bypassed or disabled is delivered right before the next process call. | Clear tails and voices. | | Bypass | You aren't called while bypassed; your time doesn't advance. Main input passes to output dry. An instrument with nothing on its main input is silent. | None. | | CPU | During real-time playback, hosts should stop a plugin that runs slower than real time over two consecutive 500 ms windows. A single `process` over 250 ms, or instantiation plus `init` over 1 s, may be ended. Offline renders have no budget. | Stay well under real time. | | Memory | Your own memory is capped at 64 MiB per instance; the host's audio-buffer page comes on top (§2). Upload doesn't check runtime use. | Allocate in `init`; growing during `process` can glitch. | ### Faults A trap, a call to `abort`, or a non-finite output sample disables the device. Its block output is discarded, it passes the main input through dry, and it shows an error. Hosts should let the user reload it, which creates a fresh instance. ## 5. Custom state Each device holds one custom state value: a JSON object of at most **64 KiB** (UTF-8), saved with the device and in presets, synced to collaborators, and undoable. The last write replaces the whole value. ### From the UI - Save with `vstSetCustomState { state }`. A string `state` is stored as-is (normally your JSON text); any other JSON value is stored as its `JSON.stringify` text. A message without `state` is ignored. Your state reaches the DSP only through the saved document: the host sends the first change immediately, then at most one update per second, and the latest value always arrives within about a second. Changes made in the last second before the device is removed or the project closes may be lost. - Over 64 KiB, the save is refused, the user is warned, and the state is reset to empty. - You receive the parsed value in `__vstCustomState` / `__spaceMeta.customState` at load, and through `__vstOnCustomState(value)` when it changes from elsewhere or on `vstGetCustomState`. - When there is no state, both globals are unset and `__vstOnCustomState` receives `undefined`. If the stored text isn't valid JSON, you receive it as a string. - UI defaults aren't state until the UI writes them. ### From the DSP - Export `onStateChanged()` and import `getStateString` / `getStateInt`. Call the imports **only** inside `onStateChanged`. - `onStateChanged` runs after `init` when state exists, and after every change (your UI, undo, redo, a collaborator, an oversized-write reset). It runs between blocks, at most once per block, on the audio thread and against your CPU budget. - Keys are the object's top-level keys, given as UTF-8 bytes; arrays aren't flattened. - `getStateString(keyPtr, keyLen, outPtr, outCap)` writes the raw string for strings and JSON text for other values, as UTF-8 with no NUL, truncated to the first `outCap` bytes. It returns the number of bytes written: 0 for an empty value, -1 for a missing key. Truncation isn't signalled and can split a UTF-8 sequence, so size `outCap` for your largest value. A negative `keyLen` or `outCap` counts as 0. A key range outside memory, or an output range outside memory for the bytes actually written, is a fault. - `getStateInt(keyPtr, keyLen, default)` returns the number truncated toward zero (3.7 → 3, −3.7 → −3), or `default` when the key is missing or not a JSON number (`true`, `"5"`, objects and arrays count as non-numeric). - **Empty state is normal:** a device whose UI never wrote state (for example, it was never opened), or a reset. State that was written is stored with the device and delivered to the DSP everywhere, offline renders included, but the host never runs the UI to produce or refresh it. Carry your own defaults in the DSP. ## 6. UI Every plugin must ship a UI (the html field): it is how people use the plugin. The DSP, in turn, must work without the UI: the host runs it whether or not the UI is open, users open and close the UI at any time, and offline renders never load it. Its container is up to the host. The UI receives no param metadata: embed the names, ranges, curves and defaults you display. To convert between plain and normalized values, use the formulas in §1 (Parameters). ### Sandbox - Ship one self-contained HTML document: inline scripts and styles, no external URLs. - It runs in a sandboxed iframe with an opaque origin. - Allowed: inline `