---
name: pam-audio-gen
description: Generate, analyze and edit local audio, create seeded MIDI patterns, or render procedural drums with MAP Audio pam. Model inference requires Apple Silicon; sample tools are free; headless PAM engine rendering needs a PAM licence or trial.
---

# pam — local audio generation

This workflow needs a local Mac execution environment or connected pam MCP tools.
It cannot run a Mac binary in a hosted chat environment. Inference runs on the Mac;
the conversation and tool results are still handled by the chosen AI client.

For shell commands, use `PAM_CLI_BIN` when supplied, then `pam` on `PATH`, or
`/Library/Application Support/MAP Audio/PAM/bin/pam` on an installed Mac.
Where it is bundled, `scripts/pam.sh` performs this discovery.
A Dock-launched client may not inherit the terminal's `PATH`; configure an absolute path.
The examples below use `pam` for the resolved executable.

Commands support `--json`; progress and logs go to stderr. Exit codes: `0` ok,
`1` error, `2` usage, `3` licence required. If the launcher reports a missing binary,
explain the installation requirement and stop. Do not install software implicitly.

## 1. Check the machine

```bash
pam version --json
pam manifest --json
pam search "measure loudness"
pam schema audio generate --json
```

Choose the interface from the available local shell or MCP tools. For analysis of an
existing WAV, skip model setup and go directly to measurement. For generation, run
`pam model list --json` or `model_list` and inspect readiness.
Generation, streaming and analysis are free. Check `account_status` only
when the installed command contract marks the requested command paid. A missing
PAM licence must never block a free command.

- `downloaded: false` for `stable-audio-3-small-sfx` → explain the 2.7 GB prerequisite.
  Run `pam model pull` only when the user has requested or approved the model download.
- `runtimeReady: false` → the daemon has no supported runtime adapter for this model on this platform; report `daemonReason`, do not retry.

## 2. Generate

```bash
pam audio generate -p "deep sub kick, tight transient" -d 1.2 --category kick -o kick.wav --json
# {"ok":true,"wavPath":"/…/kick.wav","sampleRate":44100,"seed":2718281828}
```

- `--prompt` (`-p`): Sound or starting style description. Required.
- `--duration` (`-d`): Duration in seconds, up to the model's limit (120 s for the small models, 380 s for Medium). Default: 1.0.
- `--seed`: Reproducible seed; zero draws a random seed. Default: 0.
- `--category`: Sound category. Choices: kick|snare|hat|perc|bass|synth|pad|fx|loop.
- `--out` (`-o`): Output WAV or MIDI path; absent uses an exclusive derived filename (patterns default to JSON only).
- `--model`: Model ID from model list.
- `--request-key`: Stable caller key for a retained daemon job; reuse to recover its result.
- `--detach`: Return the retained job identity without waiting.

- Without `-o` the file lands in the working directory as `<prompt>-<seed>.wav`, never overwriting.
- Failure: `{"ok":false,"error":…}` and exit 1. Surface `error` verbatim.
- A cold generation also loads the model. Wait for the running call; do not start a
  second generation merely because the first is slow.

## 3. Measure (free)

```bash
pam audio analyze kick.wav --json
# {"ok":true,"integratedLufs":-9.8,"loudnessRange":0.0,"truePeakDb":-0.6,"samplePeakDb":-0.8,…}
```

`integratedLufs` is `null` when the file is under 400 ms or silent.

With MCP use `audio_analyze` and its `files` array. Never estimate measurements.
Return the generated file or an accessible local link using the host's supported
file tools. A returned `wavPath` alone does not mean the file was uploaded or auditioned.
Do not claim to have listened without actually playing or inspecting the audio.

## 4. Edit, sequence and synthesize (free)

Use `search` and `describe` to inspect installed options, then `run` for the commands below.
No model download or licence is needed.

```bash
pam audio normalize input.wav --lufs -14 --tp -1 -o normalized.wav --json
pam audio repitch input.wav --semitones 3 -o pitched.wav --json
pam audio trim input.wav --start 0.1 --end 1 -o trimmed.wav --json
pam audio gain input.wav --db -3 -o quieter.wav --json
pam audio reverse input.wav -o reversed.wav --json
pam pattern generate --genre house --seed 42 --bars 4 -o groove.mid --json
pam synth drum --engine 808 --param Tune=55,Decay=1.5 -d 2 -o bass.wav --json
```

For analysis, `--peaks` returns the 48-bin RMS envelope, `--pitch` returns Hz and confidence,
and `--class` returns the sample family and measured features. Normalization verifies the
encoded WAV true peak and returns achieved loudness; `targetReached: false` means the requested
LUFS could not be reached under that ceiling. Repitch changes duration. Explicit output paths
must be unused; MCP `out` stays a bare filename inside the configured output directory.
Patterns use the shared MIDI corpus; a nonzero seed reproduces their JSON notes. Drum named
parameters and ranges come from the shared engine registry and appear in `describe`.

## 5. Render presets and effect chains (paid)

`preset render`, `fx` and `audio master` run without PAM open. Inspect their schemas with
`describe`, then call `run`. A PAM licence or active trial is required; `license_required`
includes the next step. Free sample editing and generation stay available when locked.

```bash
pam preset render groove.preset --bars 4 --seed 42 --stems --out groove.wav --json
pam fx input.wav --chain effects.json --out processed.wav --json
pam audio master mix.wav --chain mastering.json --out master.wav --json
```

Use `--song` for the saved arrangement, or `--variation` for one variation (numbered from 1).
`--stems` writes cell stems in the same pass as the master. Missing samples cause a refusal
listing their paths; use `--allow-missing` only when the user accepts silence in their place.
Hosted plugins, Magenta, Notochord and video content cannot be rendered headlessly.
A nonzero `--seed` makes repeat renders reproducible. For long renders use `--request-key`
and `--detach`, then inspect `job status` or `job result` instead of starting another render.
Use the running plugin's `export_audio` or `export_song` when bouncing edits in that session.

## Prompt guidance

- Describe the sound, not settings: timbre, material, transient, length, mood.
- Lead with the core sound, then qualifiers: `"808 sub bass, long decay, slight distortion"`.
- Match `--category` to the role so PAM files the sample correctly.

## As an MCP server

Tools: `model_list`, `audio_analyze`, `audio_generate`, `account_status`, `list_packs`, `install_pack`, `get_pack_install_status`, `uninstall_pack`, `job_status`, `job_result`, `search`, `describe`, `run`. The plugin
registers them as the `pam` server, alongside controls for a selected running PAM instance.
Without the plugin, register the absolute path:

```json
{ "mcpServers": { "pam": { "type": "stdio", "command": "/usr/local/bin/pam", "args": ["mcp"] } } }
```

`audio_generate` writes into `~/Music/MAP Audio/PAM` and its `out` is a file name, not a path.
Report typed failures without blind retries. Prefer the CLI for requested downloads because it reports progress;
Use `run` with `command: "model pull"` and a model argument for an authorized download; it blocks until done.

## Control a running PAM

Enable the MCP Bridge in PAM's Settings → Integrations. `situation` reads the preset, transport and
cells, and `connection_status` diagnoses a failed connection; with several PAM, MFX or MSQ instances
open, `select_instance` picks one. Common edits are listed tools: `set_parameters` (ids and ranges from
`get_parameter_info`), `update_pattern`, `start_transport`, `set_bpm`, `load_preset` then
`get_preset_load_status`, `list_samples` and `load_sample`. Most tools are unlisted: unless a listed tool
does exactly what was asked, `search` (two to four words) before combining listed tools, and call a
result with `run`, after `describe` when its arguments are unknown:

```json
{ "command": "set_metronome", "arguments": { "enabled": true } }
```

Read back state after every edit (`get_state` with `keys`); a queued acknowledgement is not proof
of a changed session.

PAM and pamd keep separate model copies. `get_model_status`, `load_model` and `unload_model` act on
the running PAM; `model ps`, `model load` and `model unload` through `run` act on pamd's workers,
which keep a model loaded until it is unloaded. `generate_sample` uses PAM's copy when PAM has
it loaded, otherwise pamd's.