# Check, build and export

> Validate, evaluate, preview, build, export and prepare a release of a module with the maru module commands.

Canonical: https://maru.audio/docs/export
Documentation index: https://maru.audio/llms.txt

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](https://maru.audio/help/exporting-your-work.md) for choosing between saving, downloading and publishing.

## Check the module

```bash
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:

```bash
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:

```text
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:

```bash
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:

```bash
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

```bash
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](https://maru.audio/docs/parity-and-determinism.md) explains what
verification measures.

## Export

```bash
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](https://maru.audio/docs/native-plugins.md).

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

## Prepare a release

```bash
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

```bash
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):

```bash
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](https://maru.audio/docs/publishing.md) for what to
prepare first.

## Format support is explicit

For an automated build and publication recipe, see
[Build and publish a module in CI](https://maru.audio/docs/build-and-publish-in-ci.md).

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](https://maru.audio/docs/testing-your-vst.md)
walks through loading it in a host and checking audio, MIDI, controls and saved
state.