Check, build and export

The maru module commands take a module project from the workbench to a release. Run them from the project directory, or pass the project as an argument; maru module <command> --help shows the arguments and options of each one, and --json returns a structured report for scripts and agents.

In the Help Center: Export your work for choosing between saving, downloading and publishing.

Check the module

maru module validate   # quick structural check of the declaration
maru module check      # the module's checks, in order, stopping at the first failure
maru module eval       # render a Graph module offline through its engine
maru module eval --suite levels   # compare output loudness with input loudness
maru module preview    # render the module's authored demo audio

maru module validate confirms the declaration is well formed: that the entry exports a module definition, that its nodes and imports exist, and that its identity matches the project. Passing means the module is worth building, not that it sounds right.

maru module check runs the project checks in the same order a release uses, from the declaration and face through the built programs, and can include the project's own test renders. Its fast mode runs the light checks only; use it while iterating and the full check before a release.

maru module eval renders a Graph module offline and reports audio health: valid samples, levels, clipping, DC and discontinuities. Without --suite it refuses a Processor module, which is what maru init creates by default; the suites below accept both. maru module preview renders the demo audio defined by the module's presets, so you can listen to what the module page will play.

Check output levels

An effect that comes out much quieter or louder than its input forces people to reach for a level-match button every time they change a preset. The levels suite measures this while you design:

maru module eval --suite levels

It renders the module's demo audio through the schema defaults and every factory preset, scaled to several input loudness levels (−30, −24, −18 and −12 LUFS by default), and prints one line per case:

case         Δ@nominal  Δ range        slope  max dBTP
Palm Shadow   -13.5 LU  -18.1…-7.0      0.38     -18.9
Defaults       -7.5 LU  -12.1…-0.9      0.37     -13.5
Hotel Radio    -5.0 LU  -9.7…+1.6       0.37     -11.8

• Δ@nominal is output minus input integrated loudness (ITU-R BS.1770) at the nominal input level, −18 LUFS by default. Near 0 means the module sits at unity for typical input.
• Δ range is the smallest and largest difference over every input level.
• slope is how much the output moves per LU of input: 1 follows the input, below 1 compresses it, 0 ignores it. A fixed-threshold compressor without make-up gain shows up here as a low slope.
• max dBTP is the highest true peak of the output.

The full report, with input and output loudness, RMS, sample and true peak, crest factor and clipping for every row, goes to build/eval/levels.json, or to --out. Add --json to print it instead of the table.

Narrow the run to what you are tuning. A full run renders every preset at every level; these options keep a design loop to a few seconds:

Option	Effect
--sweep drive.amount	Add cases that sweep one parameter from its minimum to its maximum in 5 steps. --sweep drive.amount=0:1:9 sets the range and step count. Repeat for more parameters.
--no-presets	Skip the factory presets.
--input-lufs -18	Measure only these input levels (repeatable).
--nominal -14	The input level the module should be unity at.
--stimulus guitar.wav	Use your own audio instead of the demo sources (repeatable). --stimulus bank:gen-drum-loop uses a shared demo source.
--max-seconds 4	Use at most this much of each stimulus.

Without a tolerance the suite only reports and exits 0. To make it a check, give the allowed difference at the nominal level, and optionally a true-peak ceiling:

maru module eval --suite levels --tolerance 2 --true-peak-ceiling -1

Any case outside ±2 LU at the nominal level, or any output above −1 dBTP, is listed and the command exits non-zero, so the same command works in CI. Choose the tolerance for the module: a utility should stay close to unity, while a deliberately loud drive or a quiet ambient preset may need a wider allowance or its own preset level.

The suite renders the module's own Processor offline, the same renderer maru module preview uses. Equal LUFS is a good starting point, not proof that two settings sound equally loud, so check the result by ear.

To render a Processor module offline, pack it and render the Release with your own 48 kHz input file:

maru module pack . --out dist
maru render ./dist/web/module --audio input.wav --out output.wav --offline

--params '{"drive":0.8}' sets parameter values by path before the first block. The output is a 32-bit float WAV at 48 kHz with two seconds of tail appended. This is the Program a host runs, so it is also the file to compare against your original plug-in when you port one.

In the workbench, also check input, output, controls, presets and saved state by ear. A passing check does not replace listening.

Build and verify

maru module build      # the module's distribution assets
maru module verify     # verify existing builds and their qualification reports

maru module build produces the assets a host loads: the compiled programs, the packaged face, presets and resources. maru module verify checks the existing builds, their artifact identities, embedded interfaces and qualification reports. Include compiled audio comparisons in the project's qualification steps to verify the programs against the module's reference output. Install the compiler components and platform SDKs required by the selected targets. maru module doctor reports whether this project and machine are ready to build.

Parity and determinism explains what verification measures.

Export

maru module export

maru module export writes the module as a self-contained package for native hosts and other build systems, with the declaration, programs, face and resources it needs. To build installable AU, VST3, CLAP or AAX plugins from a module, use Native plugins.

To publish a module as an npm package that other projects install and import, use maru module pack-npm.

Prepare a release

maru module pack

maru module pack prepares a versioned Release of the module locally: the built programs, face and resources, with their identities and the checks they passed. It does not upload anything.

Publish to maruaudio.com

maru publish --dry-run   # build and list the upload; needs no sign-in
maru login
maru publish             # upload; prints @handle/slug@version and the page URL

maru publish builds the project and uploads it under your account. Others install it with the printed reference. By default only the built module is uploaded. Add --source to upload the project's source as well, so it can be opened in Studio and used for native builds, and --source-visibility public to let anyone who can open the module page read it (the listing needs a source licence):

maru publish --source --source-visibility public

The source must install outside your checkout, so depend on published packages rather than file: or workspace paths. maru publish also takes the build options: --qualify, --programs js,wasm, --screenshot and --attach-to-revision-id. maru unpublish takes a sampler bank offline; a module is archived from its project on maruaudio.com. Before the first real publish, replace the provisional local. module id in src/index.ts: the id is permanent once published. See Publishing for what to prepare first.

Format support is explicit

For an automated build and publication recipe, see Build and publish a module in CI.

A module only presents a target when the required build path is available. Browser, VST3, CLAP, Audio Unit and standalone builds exist, but not every module supports every target. Check the module page and the verification report before you announce a release.

For a VST3 build, Testing your VST walks through loading it in a host and checking audio, MIDI, controls and saved state.