Scripting Languages × Execution Contexts — Rationale Reference

A cheat-sheet for which scripting language to reach for in which part of SEANCE, and why each combination is allowed or forbidden. This exists because the allowed combinations are not arbitrary — they fall out of one hard constraint (the audio thread must never block, allocate, or call an interpreter it can't bound) and a few capability facts about each language.

This is the "why / which-one" doc, not the API spec. For the exact per-binding scripting reference — emit functions, variable vocabulary, multi-pin I/O, the terrain whole-grid program model, the warp/waveform functions, the WASM ABI — see REFERENCE.md: Script program reference, Script (signal + MIDI), and the terrain / warp / wavetable sections. For task-oriented tutorials, see the in-app Help pages (docs/*.html): Signal Shape, MIDI Script, Wavetables, Terrain Synth.

If you only remember one thing: there are two worlds.

Everything below is just the consequences of that split.

The five languages at a glance

Build-time / runtime availability:

• Builtin — always present.
• Lua — compiled in when HAS_LUA is set (it is, by default). Greys out in the language picker if absent.
• WASM — needs wasm3; greys out if absent.
• Python — optional find_package(Python3); DLL is delay-loaded and runtime-probed (ScriptEngine::pythonAvailable()). If the DLL isn't there, the Python option simply disappears — the app still runs.
• GLSL — needs a GL 4.3 driver; probed by glslComputeAvailable(). Greys out otherwise.

The full matrix

Rows are the languages you named; columns are the execution contexts you named. ✓ = supported, — = not supported / not applicable. The "why" for every cell is expanded in the sections below.

¹ Expression mode is not a separate language — it's the Builtin language running its single-expression-per-sample evaluator. It's listed as its own column because that's how you think about it in the UI ("just type a formula"), but mechanically it's the Builtin × per-sample cell.

² Sample-rate mode and expression mode overlap for Builtin. Builtin only runs per-sample, so "expression mode" and "Builtin in sample-rate mode" are the same thing. The distinction matters once you add Lua, which can also run per-sample but is a full program, not a single expression.

³ WASM's "—" here is about the calling convention, not the signal. This is the point that trips everyone up, so it gets its own section (WASM and "sample-rate": resolving the apparent contradiction). Short version: a WASM module already produces a fully sample-accurate signal and can react per-sample — it just does that inside its own block loop rather than by being re-entered once per sample. There is no capability missing; the per-sample/per-block toggle simply doesn't apply to a program that owns its loop.

Enforced in code by scriptLangSupportsRate() (script_runtime.cpp:49-56):

Builtin -> PerSample only
Lua     -> PerSample and PerBlock
WASM    -> PerBlock only

The editor's Run dropdown (Per sample / Per block) is greyed out and forced for Builtin (→ Per sample) and WASM (→ Per block); only Lua leaves it live.

Real-time contexts (the Script node)

These four "modes" are all the same Script node — they differ in how often your code runs and who owns the loop. Pick the cheapest one that can express your idea.

Multiple I/O pins — signals and MIDI in and out

One thing the matrix above doesn't capture: a Script / Signal-Shape / MIDI-Script node isn't limited to one input and one output. The node's pin counts (each 0–16) give it several signal inputs (s1…sN), several signal outputs (o1…oP), several MIDI inputs (told apart by the idx value midievent()/pollmidi() returns), and several MIDI outputs (selected by the reserved out variable). So one program can merge two MIDI inputs while emitting on two MIDI outputs and reading three control signals at once — none of which changes which language is allowed where. The exact per-pin binding spec lives in the API reference, not here: see Multiple MIDI outputs / inputs / Signal inputs and Script (signal + MIDI) in REFERENCE.md, and the Signal Shape / MIDI Script tutorials (Help menu).

Expression mode — Builtin, per-sample

What it is: one formula, re-evaluated every sample, returning one number (or, in MIDI role, calling note()/cc()/bend()). Persistent variables and init:/start:/loop: sections are available, but no loops or tables.

Sample-rate mode (per-sample) — Builtin or Lua

What it is: the host owns the loop and calls your code once per audio sample, and you return/process one sample per call. Sample-accurate by nature. (Note the emphasis on invocation — this is a calling convention, not the only way to get a sample-accurate signal; see the WASM section.)

Block mode (per-block) — Lua or WASM

What it is: your code runs once per audio block (e.g. once per 512 samples) and fills the whole output buffer / emits all MIDI for the block, stamping each event with a sample offset for accuracy.

Program-loop mode (streaming) — Lua stream(), or WASM

What it is: your program owns the loop. Instead of being called per sample/block, you write an infinite loop that pull()s input and out()s output; the host suspends/resumes you at block boundaries. Cross-block state is just ordinary locals — a filter's running value, a delay line, a phase counter — no manual global bookkeeping.

Lua streaming vs WASM: pick Lua when you want to iterate quickly in-editor with full language ergonomics and the perf is fine; pick WASM when you need native speed, many instances, or you already have C/Rust/Zig DSP to drop in.

WASM and "sample-rate": resolving the apparent contradiction

This is the one that reliably causes confusion, because the word "per-sample" means two different things and they get conflated. Untangling them:

Two different "per-sample"s:

1. Per-sample resolution (the signal): does the output change every sample? Can the code react to each incoming sample / MIDI event at the exact sample it happens?
2. Per-sample invocation (the calling convention): does the host enter and exit your code once per sample — 44,100 separate calls per second?

The "Run: Per sample / Per block" dropdown is about #2, the invocation. It is not a knob for signal resolution.

What WASM actually does: a WASM module exports ss_process(), which the host calls once per block, and inside that one call the module runs its own loop over every sample in the block. So:

• Its output is fully sample-accurate (#1 ✓) — it writes every sample, can hold per-sample state, and stamps MIDI events at their exact sample offset.
• It is not re-entered per sample (#2 ✗) — and that's a feature, not a limit.

So when I said earlier "WASM works in sample rate," I meant #1: a WASM module does genuine sample-by-sample work and produces a sample-accurate signal. When the doc says "WASM is per-block only," it means #2: the host calls it once per block, so the per-sample/per-block toggle doesn't apply. Both are true. They're describing different axes. My earlier phrasing blurred them — apologies.

"But you agreed sample-rate and block-rate signals are basically the same at different rates — so if it's fast enough, WASM should do per-sample too." The key realization: there's nothing to add, because per-sample invocation would produce the exact same signal as what WASM already does, just slower. Calling ss_process() with blockSize = 1, 44,100 times a second, computes bit-for-bit the same output as calling it once with blockSize = 512 — but pays the host↔︎WASM call-boundary cost 512× as often for zero benefit. The module's internal loop is the per-sample loop; moving that loop out into the host buys nothing and costs overhead. So "make WASM work in sample-rate mode" isn't a withheld capability — it's a strictly-worse way to get the identical result, and that's why the toggle is fixed rather than offered.

The clean mental model — there are only two kinds of real-time program:

WASM and Lua stream() are the same category — both own their loop, both are sample-accurate, both ignore the Run dropdown. WASM isn't a limited version of a per-sample language; it's a self-driven one, exactly like streaming Lua.

(Aside: per-sample host invocation also wouldn't unlock cross-node sample feedback in this engine, because the JUCE AudioProcessorGraph processes the whole graph a block at a time regardless — even a "per-sample" Builtin node is per-sample only within its own block. So nothing about the graph's behaviour changes either. Sample-accurate feedback inside a single WASM module already works, because the module owns its loop.)

Self-driven, two ways: Lua stream() yields, WASM returns

The table above lumps Lua stream() and WASM into one "self-driven" bucket, and for picking a language that's the right level of detail. But they reach the same place by two different mechanisms, and the difference explains a question that otherwise looks like a contradiction: if WASM can't suspend/yield, why isn't the audio thread stuck waiting on it at block rate too?

The trap is treating "hand control back to the host" as one operation. It's two:

• Return — the function finishes and exits. Its call stack is destroyed. The host gets control because the call ended. To do more work later, the host calls the function again from the top, and any state that must survive has to live outside the call stack.
• Yield / suspend — the function pauses in the middle, keeps its entire call stack frozen and alive, hands control back, and is later resumed from that exact instruction.

WASM (under wasm3) can return but cannot yield — a WASM call runs to completion on one stack; the MVP has no coroutines, continuations, or stack switching. Lua can yield, because Lua coroutines suspend across the C boundary.

Now the two streaming styles fall out cleanly:

So "WASM can't yield" never bites at block rate, because the block model is built on return, not yield. The host calls ss_process(), WASM does the whole block's work and finishes, the host regains control because the call completed — nobody is blocked, nothing is paused mid-flight. Cross-block continuity doesn't need a frozen stack; it comes from linear memory plus re-calling from the top.

Yield is only required for the one thing WASM can't express: a single continuous loop that spans block boundaries (the while true do … pull() … end form). And that's pure syntactic sugar — it produces the identical signal to a per-block fill function, just spelled as one loop instead of a re-entered function. You could give WASM that form via Asyncify (rewrites the binary to unwind/rewind its own stack), a dedicated OS thread with a real blocking primitive, or the stack-switching proposal — but all three add real cost (code-size/runtime overhead, thread-per-node sync, runtime support wasm3 lacks) to buy only the loop syntax. Persistent linear memory already delivers the actual capability, so the per-block ABI is the right call.

The same return-vs-yield split also re-frames "WASM can't run at sample rate" precisely: WASM could be invoked per-sample in return style (call ss_process() with blockSize = 1, return after each sample) — that's possible, just strictly wasteful (identical signal, 512× the call overhead). What WASM can't do is the streaming style of per-sample work (one continuous loop pulling per sample), because that needs yield. The Run dropdown is fixed to Per block because per-block return is the only option that's neither impossible (the stream style) nor pointless (per-sample return).

Why GLSL can't do real-time audio — in any mode

GLSL is offered for offline bakes (terrain, wavetable/curve shapes) but never in the Script node, in either program-owns-loop or per-sample form. This isn't an oversight or a "not wired up yet" — a GPU is the wrong kind of machine for the real-time audio path, and the reasons hold for every mode:

Walking the two modes the question asks about:

• Per-sample GLSL is the worst case: dispatching a shader to compute one scalar wastes the entire parallel machine and pays the full round-trip latency 44,100×/sec. A GPU doing one sample at a time is all latency and no throughput.
• Program-owns-loop / streaming GLSL doesn't fit the hardware model at all. GPU compute is batch-parallel — "run this kernel over this whole array at once." There is no coroutine-style pull() one sample, suspend, out() one sample interleaved with a CPU producer. The closest a GPU gets to "owning its loop" is processing a whole buffer in parallel — i.e. the block model — and the block model is exactly what the round-trip latency above kills.

So GLSL's strengths (massive parallel batch compute, high throughput, latency irrelevant) line up perfectly with offline baking — run once, freeze the result into the project, never touch the GPU again at playback — and line up against everything real-time audio needs. It's not strictly impossible to imagine a high-latency bulk-processing GPU audio path, but for an interactive real-time node graph it's the wrong tool, so it's deliberately not offered. The audio thread only ever reads GLSL's baked output, exactly like a hand-drawn curve.

"Then run GLSL on the CPU to dodge the GPU concerns?" Tempting — the latency and thread-affinity problems come from the GPU execution model, not from GLSL the language, so CPU execution would sidestep them. But there's no "CPU mode" switch on our GL backend (glsl_compute is fundamentally an OpenGL-context wrapper), and the two ways to get CPU-GLSL are both large, with a punchline that makes the whole exercise pointless:

• A software GL driver (llvmpipe / SwiftShader). Heavy dependency to vendor and ship, and still not real-time-safe — a software driver allocates, spawns worker threads, JIT-compiles shaders, and owns a thread-affine context, so calling it from the audio callback per block is the same forbidden behaviour. You lose the PCIe round-trip and keep almost every other problem; realistically you'd still only run it offline, which is what we already do on the real GPU.
• Compile GLSL ourselves (glslang → SPIR-V → CPU). Translate to SPIR-V, then either emit C++/LLVM and compile it or interpret SPIR-V on a small VM. To be real-time-safe the result must be bounded, allocation-free, and compiled offline (UI thread), so the audio thread only calls a fixed routine. But that artifact — an expressive language, compiled ahead-of-time off the audio thread into a bounded allocation-free per-block routine — is exactly what WASM already is. Route 2 is "build a new compiler/VM to arrive at a more awkward WASM."

So a real-time-safe CPU-GLSL is architecturally the same thing as the WASM path we already have; the GPU was the only thing GLSL added over WASM/Lua/Builtin, and CPU execution throws that away. If the real want is GLSL's ergonomics in real time (vector math, and especially waveform(id, phase) bank access), the proper move is to enrich the languages already in the audio path — not to port GLSL to CPU. And anyone who genuinely needs a GLSL algorithm running live can go GLSL → SPIR-V → WASM offline and load the .wasm as a Script node. Building CPU-GLSL for real time would duplicate WASM at high cost, so it's deliberately not done.

What was actually enriched. Following the "enrich the languages already in the path" plan, the complete scalar slice of GLSL's Trigonometry/Exponential/Common builtins is now shared across all three custom-expression dialects — the Built-in parser (builtin_synth.cpp WaveExprParser), the Lua prelude (lua_prelude.h), and the Python bake preludes (scripting.cpp): asin acos atan(y[,x]) sinh cosh tanh asinh acosh atanh exp2 log2 inversesqrt sign round roundEven trunc fract mod mix step smoothstep fma radians degrees (on top of the pre-existing sin cos tan sqrt exp log pow abs floor ceil min max clamp), with mod using GLSL's floored semantics and domain guards (acosh/atanh) matching across the three. The only scalar GLSL builtins deliberately omitted are the ones that don't fit a float-only single-return evaluator: bit-reinterpret (floatBitsToInt & friends — no integer type), the two-output modf/frexp (their pieces are already reachable via trunc/fract and log2), and ldexp/isnan/isinf (niche). One subtlety worth recording: Lua 5.3 removed math.tanh/math.sinh/math.cosh, so on Lua 5.4 the single most common waveshaping saturator (tanh) was silently absent until the prelude re-defined all three by hand (with an overflow guard, ±20 → ±1) — a real gap the "don't forget the other languages" pass closed.

The waveform(id_or_name, phase) factory-bank accessor — once present only in Built-in, Lua, Python and GLSL — is now in WASM too, closing the last cross-language gap. The Script node's WASM ABI gains two host imports, ss_waveform(int id, float phase) (raw [-1,1] sample, identical wrap+interpolate to the other languages) and ss_waveform_id(const char* name) (resolve a name to its stable integer id once, then reuse the integer — the WASM analogue of Lua's waveforms[name]), with the ~4000-entry bank warmed off the audio thread at module-link time. Because WASM modules compile -nostdlib (no libm), the same pass added header-only GLSL-parity shaping helpers to soundshop_wasm.h (ss_fract/ss_sign/ss_mod/ss_clamp/ss_mix/ss_step/ss_smoothstep/ ss_radians/ss_degrees/ss_saw/ss_square/ss_triangle/ss_unipolar/ ss_bipolar, built on __builtin_floorf so they need no libm); the transcendentals still require <math.h> + a linked libm.

Waveshaping warps — the same transfer functions, every language

SEANCE's warp framework (warp.h/warp.cpp) is the single source of truth for the catalogue of amplitude/phase shaping transfers — soft-clip, hard-clip, wavefold, wavewrap, rectify, quantize, tube/tape saturation, flip, Chebyshev, the bend/asym/PWM phase shapers, etc. (the same WarpMethod enum used by the node-graph Warp effect and the wavetable painter). Those transfers are now callable directly from scripts so a bake or a live Script node can reach the exact same shaping math the rest of the app uses, instead of re-deriving a saturator by hand.

Per-sample scalar warps — every language, real-time-safe. Two scalar primitives are exposed in all custom-expression dialects (Built-in, Lua, Python, WASM):

• warpamp(method, x, amount) — amplitude transfer: shapes one signal sample.
• warpphase(method, phase, amount) — phase transfer: shapes one phase value.

The method comes first (consistent with the rest of the warp API); the whole-buffer calls below put their buffer first instead. method is either the stable integer id or a name string ("soft clip", "bend+", … — case/space/punctuation-tolerant, resolved by warpMethodFromName). amount is 0..1 where 0 is an exact identity and an unknown method is identity too, so they're safe to sweep. Because they're pure float→float (no allocation, no state), they're allowed in every mode including per-sample real time. In WASM they're the host imports ss_warpamp/ss_warpphase plus ss_warp_method(const char*) to resolve a name to its id once (the warpMethodFromName analogue, same pattern as ss_waveform_id). The SS_WARP_* id constants are in soundshop_wasm.h.

The method names accepted here are the same catalogue the node-graph morph editor offers (the registry in warp.h). Each method also carries a human label for its amount — Drive, Fold, Width, Crush, Bend, … — which the UI shows on a modulated op (so a pinned Soft-Clip reads "Soft Clip Drive"); from a script the parameter is just the same 0..1 amount regardless of that label. Note the catalogue is Type-2 (arbitrary-wave) warps only — the wave-defining Type-1 generators (PWM / sync / FM / phase-distortion) are layer wave sources, not warp methods, and aren't reachable through warpamp/warpphase.

Whole-buffer warps — offline/streaming only. Two transforms operate on a whole buffer rather than a single sample, because they warp a representation of the signal, not its instantaneous amplitude:

• spectralwarp(buf, method, amount) — FFT the buffer, run the amplitude transfer over the per-bin magnitude envelope (phase preserved, DC bin left alone), inverse-FFT back.
• waveletwarp(buf, method, amount[, filter="db4", levels=5]) — multi-level DWT, warp every wavelet coefficient through the transfer, inverse-DWT back. The round trip is exact perfect-reconstruction, so amount 0 returns the buffer unchanged.

Both route every value through the same warpAmpValue transfer as warpamp, so the catalogue stays a single source of truth. They take a whole buffer (a Lua/ Python list, or a (ptr,len) pair in WASM) and are therefore bake/offline or block/stream context only — never per-sample. There is deliberately no granularwarp binding: a per-grain amplitude warp collapses to warpamp applied sample-by-sample, so adding one would just duplicate the scalar primitive over a loop (documented in buffer_warp.h). Implementations live in buffer_warp.cpp; the FFT is fft_util.h, the wavelet filters are getWaveletFilter() from wavelet.h (the synthesis here is a local perfect-reconstruction transform — wavelet.h's own idwt is frozen for painter compatibility and is not perfect-reconstruction for multi-tap filters).

Composition ("multiple wave objects"). Lua/Python/GLSL bakes could always define local intermediates and combine them; the Built-in language now does too — a Formula/curve source with newline/;-separated statements and name = expr assignments runs in program mode (WaveExprParser::runProgram), so a = sin(x) / b = 0.5*sin(3*x) / a + b builds several waves and sums them. Each baked sample is an independent pure function of the sweep position (fresh state per sample), matching the other languages' per-call-local semantics.

So the practical ergonomics gap between "our expression language" and GLSL is now just the type system — vectors, matrices, and swizzles — not the math vocabulary or value composition. Closing that gap is a compiler project, scoped in the next note.

How big is "make our expression language exactly GLSL"?

Honest sizing, because the temptation ("just keep adding functions until it's GLSL") hides a cliff:

• Scalar parity — done, cheap. Adding named float→float (and a couple of float,float→float/float,float,float→float) builtins to a recursive-descent evaluator is an afternoon each; the complete scalar GLSL set described above is now in. Plus newline/assignment composition. This is the 90% of what hand-authored wavetable/curve formulas actually use.
• Full GLSL — a from-scratch compiler, person-months. "Exactly matches GLSL" means a real type system (float/int/uint/bool × vec2/3/4 × mat2/3/4), swizzles (v.xyzw, v.rgba, write-masks), ~100+ overloaded builtins with the component-wise/per-type overload rules, implicit conversions, user-defined functions with overload resolution, const/uniform/control flow, the preprocessor, and array types. Our current evaluator re-parses the source string per sample and only knows float; none of that scaffolding generalises. A robust subset (scalars + vecN + swizzle + the common builtins, no preprocessor) is still weeks of focused work plus a serious test suite; genuine spec conformance is the kind of thing glslang represents — not something to hand-roll.
• Therefore the recommended split: keep growing the scalar vocabulary in lockstep across the three dialects whenever a useful function is missing (it's cheap and instantly available in real time), and for anyone who truly needs GLSL's vector expressiveness running live, point them at the documented GLSL → SPIR-V → WASM (offline) toolchain rather than reimplementing GLSL's type system inside our parser. Building our own GLSL compiler would land us, at great expense, on a worse-tooled version of a path (SPIR-V) the ecosystem already maintains.

Offline / bake contexts (no audio-thread constraint)

Here the script runs once, on the UI thread, and its output is frozen into the project file (a grid, or a 512-sample lookup table). At playback the audio thread just reads the baked data — no interpreter ever runs in real time. That's why Python and GLSL are allowed here and nowhere else, and why "is it real-time safe?" is simply not a question that applies.

Terrain synthesis — Builtin, Lua, Python, GLSL, WASM

Generates an N-dimensional grid. GenLang { Builtin, Lua, Python, Glsl, Wasm } (terrain_synth.h:81). Two sub-modes: per-cell (a function returning one value per cell) and whole-grid (the program sees the whole array and can do cross-cell work — convolution, cellular automata, diffusion — optionally over multiple passes).

The whole-grid program API (Lua / Python). All three expose the same read-only shape facts and the same cell helpers, so a Lua program and a Python program read almost identically:

• nd — rank; dims — per-axis sizes (Lua: 1-indexed table; Python: 0-indexed list); total — product(dims). These are fixed by the dialog's Dimensions field and injected read-only — the program reads them to decide what to draw, it does not define them.
• set(i, v) / get(i) — flat-index write/read (v clamped to [0,1]).
• coord(i, axis) — normalized [0,1] position; coordAxis(i, axis) — the integer index; flatten(c0, …) — N-D integer coords → flat index (each clamped to the axis); neighbor(i, axis, delta) — flat index of an edge-clamped neighbour.
• getAt(c0, …) / setAt(c0, …, v) — direct N-D pixel read/write, no manual flatten(). Reads edge-clamp; an out-of-range write is a no-op.

Python gets a real N-D array. When numpy is importable, the whole-grid Python program is also handed grid — a float64 ndarray shaped exactly like the terrain (grid.shape == tuple(dims)). So instead of flat indices you can write grid[r, c] = …, slice (grid[0, :] = ramp), or run fully vectorized numpy/scipy ops over the whole field, and the result is read back through the buffer protocol (no per-cell Python calls). The set/get/getAt/setAt helpers operate on the same live grid, so you can freely mix helper calls with numpy slicing; reassigning grid wholesale (grid = grid + 1) is honoured at readback. Raw numpy writes skip the helper clamp, so out-of-range values are clamped once at the end via np.clip(grid, 0, 1). If numpy is not installed, grid is None and the cells live in a flat list reached through the helpers — write your generator to branch on grid is not None if you want it to run in both environments. (Lua and WASM have no native N-D array type — Lua only has nested tables, which are 1-indexed and allocation/GC-heavy, and WASM has only flat linear memory — so for those two the flat-buffer + getAt/setAt helpers are the right model. numpy is the one scripting stack here with a true native N-D container, so Python is the only one that gets grid.)

Why is WASM whole-grid only (no per-cell)? It's the mirror image of Builtin's "can't whole-grid":

• Per-cell is fundamentally impossible for WASM. Per-cell generation re-invokes the program once per grid cell (the PerSample path), but a WASM module owns its own loop — it is never re-entered per element (this is the exact same property that makes it a streaming audio node; see the WASM section). So per-cell WASM is correctly rejected (the self-test asserts a per-cell WASM request fails). Builtin has no loop, WASM is the loop.
• Whole-grid fits WASM exactly, and is now built. The whole-grid path runs the program once and hands it the array, which matches WASM's PerBlock model. The WASM runtime overrides IScriptRuntime::runGenerate(dims, data, error) (script_runtime_wasm.cpp): it exposes the host-owned grid through fixed-arity host imports and calls the module's ss_generate export.

The terrain WASM ABI (declared in cpp/include/soundshop_wasm.h, mirrors the Lua whole-grid API one-for-one). The module exports void ss_init(void) and void ss_generate(void); the host imports (module "env"):

The grid is row-major (last axis varies fastest). The module writes each cell a value in [0,1]; the host maps it to bipolar [-1,1] as v*2-1. The header also ships #ifndef SS_NO_GRID_HELPERS inline helpers (ss_grid_flatten, ss_grid_getat, ss_grid_setat) that take an N-D coordinate array. Because the bake is offline, host-call overhead per cell is irrelevant, so the grid stays host-owned (poked via imports) rather than shared through linear memory.

In the generate dialog WASM appears as "WASM (.wasm module)": instead of a code editor you get a Browse .wasm… button, the mode is forced to whole-grid, and the chosen module is baked into the node's __generate__ script just like the other languages (so it never re-runs on load).

Pick order: Builtin for simple analytic surfaces → Lua for scripted / cross-cell → GLSL when the grid is big or the algorithm is iterative and parallel → Python when you specifically want numpy/scipy → WASM when you have a heavy generator already written in a compiled language and want to ship it as a binary.

Wavetable layers & ADHSR / spectral curves — Builtin, Lua, Python, GLSL

A Formula wavetable layer (sample space), or any ADHSR-envelope segment curve / spectral magnitude/phase curve set to Equation mode (frequency/phase space), is a text expression baked to a sample buffer. ShapeLang { Builtin, Lua, Python, Glsl } (shape_expr.h:28). The same four languages cover both the time-domain waveshape (loop var x in radians, clamped to [-1,1]) and the frequency/phase-domain curves (var f/x normalized [0,1], unclamped) — the domainRadians flag is the only difference.

Why these never need to be real-time safe: the formula is evaluated once at edit/load time into a lookup table; during playback the voice just samples the table. So even Python and GLSL — which can never touch the audio thread — are perfectly fine here. (GLSL bakes on the UI thread, same thread-affine GL context as terrain generation.)

Quick-pick decision guide

"I want to drive a parameter / make an LFO or envelope." → Builtin (expression mode). Only escalate if a one-liner can't say it.

"My idea needs loops/tables/state but stays light." → Lua. Prefer per-block; use per-sample only if the logic is trivial and heed the stutter warning.

"I'm writing a filter / delay / anything with state that flows across blocks." → Lua streaming (stream()). Locals persist for free.

"It's heavy DSP, or I'm running many instances, or I have C/Rust code." → WASM (per-block, owns its loop).

"I'm generating a terrain grid." → Builtin (simple analytic) → Lua (scripted) → GLSL (big/iterative/parallel) → Python (numpy/scipy).

"I'm defining a wavetable Formula layer or an ADHSR/spectral curve." → Builtin (simple) → Lua (logic) → GLSL (richest waveshaping, GPU) → Python (library math). Baked offline, so pick purely on expressiveness — GLSL works for both the time-domain waveshape and frequency/phase-space curves.

"Should I use Python for sound generation in real time?" → No. Python only ever bakes offline tables/grids on the UI thread. It is never in the audio path. If the DLL is missing the feature just disappears.

"Can I run GLSL on the GPU as a real-time audio node (per-sample or streaming)?" → No — in any mode. A GPU is a high-latency, batch-parallel throughput machine; real-time audio needs low latency on a hard deadline. The context is UI-thread-bound, and a dispatch+readback round-trip per block can exceed the block period with no driver-level real-time guarantee. GLSL earns its place offline, where its parallelism shines and latency is irrelevant. See Why GLSL can't do real-time audio.

The one rule that explains every "no"

Almost every — in the matrix traces back to a single principle:

The audio thread runs forever, can't block, and can't tolerate unbounded allocation or GC.

• Builtin is allowed per-sample because it's allocation-free.
• Lua is allowed but warned per-sample because its GC can stutter; it's safe per-block where it's called ~100×/sec instead of ~44,100×/sec.
• WASM is per-block-only because its whole-block ABI is the only shape that fits, and it's safe because it's compiled with persistent linear memory and no GC.
• Python and GLSL are banned from real time entirely and live only in the bake world, where their output is frozen and the audio thread never calls them.

Get that, and you can re-derive the whole table.

Source-of-truth pointers (for when this drifts)

• Real-time capability matrix: cpp/src/script_runtime.cpp:49-56, cpp/src/script_runtime.h (enum + doc comment).
• UI gating (Language / Run dropdowns, greying, per-sample warning): cpp/src/script_lang_bar.h.
• Lua per-sample / per-block / stream(): cpp/src/script_runtime_lua.cpp.
• WASM ABI (per-block, owns loop): cpp/src/script_runtime_wasm.cpp, cpp/include/soundshop_wasm.h.
• Terrain languages: cpp/src/terrain_synth.h:81 (GenLang), cpp/src/generate_dialog.cpp, cpp/src/glsl_compute.h/.cpp.
• Curve / wavetable formula languages: cpp/src/shape_expr.h:28 (ShapeLang), cpp/src/layered_wave_editor.h, cpp/src/adsr_envelope.h, cpp/src/curve_editor.h.
• Python embedding (offline only): cpp/src/scripting.h/.cpp, cpp/CMakeLists.txt (optional find_package(Python3)).
• Warp transfers (single source of truth): cpp/src/warp.h/.cpp (WarpMethod, warpAmpValue/warpPhaseValue, warpMethodFromName).
• Scalar warp bindings (warpamp/warpphase): cpp/src/builtin_synth.cpp (Built-in parser), cpp/src/script_runtime_lua.cpp, cpp/src/scripting.cpp, cpp/src/script_runtime_wasm.cpp + cpp/src/wasm_script_processor.cpp (ss_warpamp/ss_warpphase/ss_warp_method), cpp/include/soundshop_wasm.h.
• Whole-buffer warp bindings (spectralwarp/waveletwarp): cpp/src/buffer_warp.h/.cpp (FFT cpp/src/fft_util.h, wavelet cpp/src/wavelet.h), same four binding files as above.