Integration reference · [Satie documentation](/docs)

# Satie for DAWs, 0.1 development preview

Two native plug-ins wrap `satie-core`, with JUCE supplying the DAW formats and UI:

- **Satie Space** is an audio effect. Insert it on a mono or stereo track and drag
  its source around the map. Position, height, room send, occlusion, wet/dry and
  output are host parameters you can automate. Its wet path treats the track as
  one mono point source; its dry path preserves the original stereo image.
- **Satie Sound** is an instrument. Import audio, describe a sound effect or
  request Satie synthesis, or load an exported portable scene. Use the host
  transport, MIDI, or Audition to play. Audio and parameters are embedded in the
  DAW session and in `.satiepreset` files, so reopening and bouncing need neither
  the original audio files nor a network connection.

This is **stereo spatial audio**: equal-power direction, Satie's distance law,
air absorption, occlusion and its room reverb. It does not implement a binaural
HRTF, front/back or elevation localization, surround, Atmos or head tracking.
Height affects distance. The map is a top view in metres, +Y up, -Z forward.

## Build

CMake 3.22+, a C++17 compiler, and a checkout of JUCE **8.0.12** are required.
The tested JUCE commit is `29396c22c93392d6738e021b83196283d6e4d850`.
SDKs are not committed or fetched implicitly. From the Satie repository:

```sh
git clone --depth 1 --branch 8.0.12 https://github.com/juce-framework/JUCE.git /tmp/satie-juce
cmake -S packages/satie-daw -B .satie/daw-build \
  -DSATIE_JUCE_DIR=/tmp/satie-juce -DCMAKE_BUILD_TYPE=Release
cmake --build .satie/daw-build --config Release --parallel 4
ctest --test-dir .satie/daw-build -C Release --output-on-failure
```

Outputs live in `.satie/daw-build/SatieSpace_artefacts/Release/` and
`SatieSound_artefacts/Release/`. macOS builds VST3, AU and standalone applications;
Windows builds VST3 and standalone. The macOS deployment target is 13.0; the
default architecture is the build machine's. A universal Mac build can be
requested with `-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"`. Windows and Intel Mac
runtime validation remain separate release gates.

Mac bundles receive an ad-hoc signature after resources are assembled, for local
development loading. This is not Developer ID notarization or AAX/PACE signing.
Set `SATIE_DAW_ADHOC_SIGN=OFF` when supplying your own release-signing pipeline.

On this development Mac, AppleClang 21 misses its SDK's C++ headers. Supply
`-DCMAKE_CXX_FLAGS="-isystem /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1"`.
JUCE's nested helper build also needs that flag: configure the JUCE checkout into
`.satie/daw-build/juce/tools` with `-DJUCE_BUILD_HELPER_TOOLS=ON` and the same flag
before re-running the top-level configure. This is a local toolchain workaround.

## Ableton Live

Copy the `.vst3` bundles to `~/Library/Audio/Plug-Ins/VST3/` on macOS (or use a
custom VST3 folder). AU bundles go to `~/Library/Audio/Plug-Ins/Components/`.
Enable the corresponding plug-in source and rescan in Live's preferences.
Place **Satie Space** on an audio track; place **Satie Sound** on a MIDI track.
The build never installs or overwrites existing plug-ins automatically.

Live supports VST3 and AU; see [Ableton's supported formats](https://help.ableton.com/hc/en-us/articles/5937501570460-Supported-Plug-in-Formats).
Only install the format you intend to use in a particular project.

## Pro Tools

Configure with `-DSATIE_DAW_AAX=ON` to build AAX development bundles from the same
processors. JUCE 8.0.12 includes its supported AAX SDK. These binaries are **not
PACE-signed for retail Pro Tools**. Avid developer access, signing, a suitable
test host and actual Pro Tools acceptance are still required before distributing
a usable Pro Tools release. Do not represent a successful compile as host
compatibility. See [Avid's AAX developer program](https://developer.avid.com/aax/).

## Generation

The first preview reuses Satie's existing terminal/MCP account session. From the
repository, sign in once:

```sh
node scripts/satie-login.mjs
```

The plug-in reads the unexpired account session from `~/.satie/session.json` only
when Generate is clicked. For an expired session, refresh it without printing a
token into a terminal transcript:

```sh
node scripts/satie-token.mjs > /dev/null
```

Describe the source, choose Sound effect or Synthesis, set duration and whether
the generated asset should be loopable, then click Generate. This uses the
existing metered `/api/generate-audio` route at `https://www.satie.world` with the
Satie account's bearer token. Synthesis uses the server's existing synth path;
the plug-in receives frozen audio, not a live Csound instrument. It holds no
vendor keys. Tokens are never embedded in presets, projects or diagnostics.
The UI states that generation uses account credits. No generation happens on
load, playback, bounce or restore. Generation failure retains the current sound.

Generation runs on a background worker; the audio callback never accesses the
network, reads files, decodes audio or creates/destroys a runtime. The worker
publishes a prepared sound at a block boundary. The old runtime is reclaimed on
the control thread. A browser sign-in/refresh flow inside the plug-in is not yet
implemented; the helper is a development-preview requirement.

## MCP scenes

Compose and realize a scene with the existing Satie MCP tools, then export its
placement JSON and audio. Compile that export with the existing portable tool:

```sh
npx tsx packages/satie-core/compiler/placement-cli.ts \
  /path/to/scene.json /path/to/audio /path/to/compiled
```

Import `/path/to/compiled/scene.satp` into Satie Sound. This is the same core and
bundle used by the game adapters. The scene controls which sounds play, their
levels and their rooms. The map moves the **listener**, with the default pose at
the scene origin; Room and Occlusion are disabled because the scene owns them.
The compiler refuses unsupported behavior unless its existing explicit override
is used. Inspect `scene.manifest.json` and its `notRendered` list before import.
The DAW does not currently expose a scene's event, state or signal mappings.

## Playback contract and limits

- Supported audio: mono or stereo WAV, AIFF, FLAC, Ogg and MP3; at most 120 s,
  8–192 kHz. A positioned sound is folded to mono. SATP bundles are limited to
  128 MiB and render with 64 voices. Preserve a scene's manifest separately.
- Sound playback loops the loaded take. Loopable requests a seamless generated
  asset; it does not switch playback to a one-shot mode. Source endpoints are
  not automatically crossfaded.
- Transport starts and timeline discontinuities **restart the scene/take from
  its beginning**. There is no arbitrary timeline chase, tempo synchronization,
  time stretching or sample-exact seek into a scene. For a fixed timeline use a
  DAW bounce. Continuous offline playback is deterministic from a fresh start.
- MIDI mode is monophonic: each note-on retriggers, and releasing the current
  note stops it. MIDI note 60 is original pitch (host octave labels differ),
  clamped to three octaves either way. Notes retrigger samples or entire scenes;
  pitch affects samples only. Note-off and transport stop fade output over 10 ms.
  Velocity and sustain are not interpreted. Audition is temporary and not saved.
- Hosts get 2 ms of reported latency, rounded up to whole frames. Both the dry
  path and scenes without a limiter are padded appropriately. Native bypass
  preserves delayed stereo input; instrument bypass is silence.
- Parameter changes arrive at host callback boundaries. Gains fade over 20 ms;
  room/occlusion use the core's control grid and smoothing. Positions ramp over
  30 ms, delivered in slices of at most 64 frames. Parameter changes are not advertised as
  sample-accurate VST3 automation.
- The standalone Space application needs audio input access from macOS. Sound
  can be auditioned with its button without DAW transport.
- Shipping requires appropriate [JUCE licensing](https://juce.com/legal/juce-8-licence/),
  platform signing/notarization and DAW acceptance. This folder does not change
  the parent repository's license or claim a signed public release.

## Verification

Native tests compare live-input PCM against baked-take PCM through the same
core, exercise reset, reject invalid output modes and nonfinite input, and run
the existing portable conformance suite. Processor tests cover spatial direction,
dry/bypass delay, sample-rate and block-size changes, embedded audio/state recall,
invalid state, MIDI offsets, transport restart and runtime replacement. The
test executable can additionally capture its native editor and load the built
VST3 binaries through a JUCE host. Live paid generation, human listening and
named-DAW acceptance must be recorded separately from these automated checks.
