# Xoradora control model

## Stable identity and addressing

The host-facing mode parameter uses permanent stepped codes:

| Code | Mode |
| ---: | --- |
| 0 | Warp |
| 1 | Halo |
| 2 | Hull |
| 3 | Prism |
| 4 | Grain |
| 5 | Strata |
| 6 | Strand |

Codes 7–31 are reserved. The visible editor presents the modes in a different
strong-first order: Warp, Hull, Halo, Strata, Strand, Grain, Prism. Never infer
host automation identity from visible list position. Pad parameters are normally
addressed as `pNN_<parameter>`, with `NN` from `01` to `16`.

Some stable IDs retain older internal terminology. Use the current visible name
when explaining the control, but preserve these IDs in automation and saved-state
advice:

| Visible name | Stable parameter ID |
| --- | --- |
| Playback Start | `pNN_offset` |
| Resynthesis Mode | `pNN_method` |
| Warp Order | `pNN_lpc_ord` |
| Warp Excitation Quantize | `pNN_exc_qnt` |
| Warp Excitation Decimate | `pNN_exc_dec` |
| Warp Excitation Tilt | `pNN_lpc_emph` |
| Halo Colour Detail | `pNN_halo_lift` |
| Halo Colour Mix | `pNN_halo_mix` |
| Halo Motion Steps | `pNN_halo_res` |
| Strand Tonal Residual Gain | `pNN_stn_tonal` |
| Strand Partial Detail | `pNN_stn_detail` |
| Strand Residual Stretch | `pNN_stn_tone_time` |
| Strand Residual Tune | `pNN_stn_tonal_tune` |
| Strand Analysis Gate | `pNN_stn_partial_gate` |
| Strand Partial Time Stretch | `pNN_stn_partial_time` |
| Strand Noise Stretch | `pNN_stn_noise_time` |
| Strand Partial Slew | `pNN_stn_inertia` |
| Warp Excitation Level | `pNN_lpc_exc_level` |
| Pre-Saturation Gain | `pNN_preamp` |
| Strata Strike Time | `pNN_strata_strike_time` |
| Strata Body Time | `pNN_strata_body_time` |
| Strata Air Time | `pNN_strata_air_time` |
| Strata Tail Time | `pNN_strata_tail_time` |
| Voice Ceiling | `pNN_lim` |

**Shared output controls.** Pre-Saturation Gain ranges from `-inf` to `+6 dB`,
defaults to `0 dB`, and trims the reconstructed signal before Saturation and
Voice Ceiling. It is shown only in Guided view for non-Warp modes and is not
morphable. Compact detail keeps the four output controls in a 2x2 arrangement:
Saturation, Voice Ceiling, Pan, and Level. Warp Excitation Level ranges from
`-30 dB` to `+6 dB`, defaults to `0 dB`, and acts before the Warp resonator, making
it the better high-Ring headroom control. Voice
Ceiling is a fixed per-voice safety gain and clamp; `pNN_lim` is retained as the
stable automation and saved-state ID. It is not a dynamic final-bus limiter,
and overlapping voices can still exceed it after Level, Pan, and summing.

## Morph

Morph blends the active model from its genuine neutral settings at 0% toward
the pad's stored sound-shaping settings at 100%. It does not overwrite the
underlying controls. It generally includes model controls, model modulation,
envelopes, and the stored placement state for Strata, Prism, and Strand.
Tuning, trim, loop/Playback Start, level/pan, output routing/effects,
Resynthesis Mode selection, and most analysis controls are outside Morph.
Strata Factor Separation is an
analysis exception because Morph changes its learned factorisation.

When a user asks for “more of the sound design” while preserving a reversible
patch, Morph is usually safer than moving every endpoint manually. When they
ask for a precise automation lane, identify whether the lane targets Morph or
the underlying control; they are not interchangeable.

## Trigger and routing behavior

- Pads have MIDI low/root/high zones, root-note audition, Trigger/Gate mode,
  Mono playback, choke groups, mute/solo, level/pan, and one exclusive output
  bus assignment.
- Xoradora exposes Master plus four additional stereo output buses. Extra
  outputs use pad level/pan but bypass the global master level.
- A voice captures trigger-scoped state such as mode, MIDI origin, output bus,
  and relevant modulation values. Existing ringing voices keep their output
  bus; later routing edits do not retarget a held voice.
- A sound-design recipe should say whether it changes the next trigger, the
  currently held voice, or a persistent pad setting.

## Modulation and time

The modulation matrix is bipolar. LFOs can be free-running or tempo-synced,
and envelopes can target common and mode-specific destinations. Modulation and
envelopes are attenuated by Morph for destinations included in Morph. Use the
native control's unit in instructions: st, ct, Hz, ms, seconds, bands, dB, or
percent. Do not describe a normalized host value as if it were the displayed
musical value.

For automation plans, separate these layers:

1. persistent pad state (sample, mode, routing, saved controls);
2. host automation (APVTS parameters and undoable edits);
3. trigger-time values (velocity, note, channel, bus, and latched state);
4. generated modulation (LFO/envelope/matrix); and
5. background analysis or preview caches.

Only the first four are sound-design targets. Cache publication is an internal
latest-wins implementation detail, not a DAW automation lane.

## Cache and realtime expectations

Sample decoding, analysis, spectrogram/cochleagram generation, and expensive
cache renders happen off the audio thread. A recipe can tell the user to wait
for a prepared result or to audition a lighter setting, but must not recommend
filesystem work, sample decoding, or bulk analysis inside realtime callbacks.

Halo, Prism, Grain, and Strata commonly use prepared caches; Warp and Hull have
compact models that can be evaluated directly, while Strand may choose between
prepared and realtime-safe paths depending on its effective controls. This is
an implementation distinction, not a promise about latency in every host.
