# Xoradora workflows

## Sound-design recipe

Ask for the source role, the feature to preserve, the desired change, and
whether the result should remain close to neutral. Then return:

1. one mode and the reason it fits;
2. a first pass using three to six controls;
3. a listening checkpoint;
4. one controlled extreme and one recovery move; and
5. optional exact `pNN_` parameter IDs.

Example: “Make a snare more metallic but keep the crack” usually starts with
Hull or Strand. Keep Residual/Transient active, tune or stretch the ringing
body, then add damping or a small amount of colour/noise rather than removing
the attack first.

## Tune a drum to a song

For a kick, tom, or other drum with a stable ringing body:

1. Set the pad's Root to the MIDI note at which the drum should be at its
   target pitch.
2. Enable the intended global tuning map, load a `.tun`/`.scl`, or choose
   MTS-ESP Follow. Ensure the pad's microtuning is enabled when using the map.
3. Use the pad menu's **Sound → Tune to root (current map)** action. It uses
   the stored pitch estimate to choose Coarse and the smallest remaining Fine
   correction; the action is undoable.
4. For a ringing Warp sound, raise Harmonic until the resonant poles settle
   around the played pitch and its integer multiples. Use Ring separately for
   sustain/resonance amount.
5. For Strand, balance Partials/Tonal Residual/Transient first, then raise
   Harmonic to organize the tracked partials. Use Partial Tune for the
   oscillator bank and Residual Tune for the residual when those need different
   treatment.

This is different from merely transposing the sample: Coarse/Fine and the
tuning map establish the reference pitch, while Harmonic changes the internal
resonant or partial structure. Noise-heavy or strongly swept drums may not have
a reliable pitch estimate; in that case tune by ear and use Harmonic as a
creative way to create a stable pitched identity, keeping the attack component
active.

## Hear what Strand is doing

When Partials and Tonal Residual seem confusing, temporarily make the comparison
deliberate:

1. Keep Transient and Noise low enough that they do not mask the tonal paths.
2. Turn Tonal Residual down and Partials up. This exposes the stable
   tracked-peak bank; it is the cleaner, more explicitly transformable, often
   more synthetic path.
3. Restore Partials to neutral and turn Partials down while Tonal Residual
   stays up. This exposes the tonal residual left after the partial-bank render;
   it keeps more complex source body and texture.
4. Recombine them, then use Harmonic/Partial Spread on Partials, Residual Tune
   on Tonal Residual, and Chirp or Partial Slew only when the onset or frequency
   trajectory needs to change.

Use **Partial Slew** for partials that wobble or follow changing frequencies too
quickly: it makes the frequency trajectory lag smoothly without changing
amplitude or duration. Use **Chirp** for an onset sweep: it changes how a new
partial enters, not its steady-state pitch. At zero Chirp the partial begins at
its measured frequency; higher values introduce a longer downward-from-DC
onset sweep.

## Parameter explanation

Explain a control in the order “what part of the reconstruction it changes →
what the ear should hear → what it interacts with → how to return to neutral.”
If the control is an analysis setting, say that it may trigger a background
refresh and is not simply an audio-rate effect.

## Automation planning

Before generating an automation plan, identify:

- DAW and plugin format, if any;
- pad number and source/mode;
- musical timeline and tempo assumptions;
- displayed units versus normalized host values;
- whether the lane should target Morph or an underlying parameter; and
- whether the user wants host steps, MIDI/OSC messages, or a file.

Use a table such as:

| Time | Target | Value/unit | Purpose |
| --- | --- | --- | --- |
| bar 1 | `p03_morph` | 0% → 35% | reveal the model gradually |
| bar 3 | `p03_lpc_ring` | small positive amount | add moving resonance |

Do not claim that the automation was inserted. Without a DAW bridge, give
host-specific instructions or a portable recipe. If a user has a direct bridge,
confirm the target pad and parameter before any mutation, prefer undoable
operations, and report exactly what changed.

## Kit and provenance

For a `.xorakit`, work on a copy. A portable bundle contains kit/pattern/state
documents, samples, and optionally root-level `attribution.json`. Describe
missing files and kit state without modifying them just to answer a question.

Attribution metadata is not required to create, load, export, or share a kit,
and its presence or absence must not be presented as permission or a
restriction. It is available when users want to retain credit for their own
work or carry credits they choose to give contributors and source authors.

When a user wants to create or audit that record, invoke
`$xoradora-attribution`. A useful complete record for a distinct bundled
sample includes the exact work title, creator, source URL, license name and
URL, and the edits made. Leave an unknown field unresolved rather than
inventing a credit. The metadata records information; it does not establish
rights or prove that an uploader cleared every input.

## Troubleshooting map

- **Neutral sounds wrong:** verify Root-note audition, Morph 0%, full trim,
  loop off, pitch 0, shared output settings, and disabled modulation/envelopes
  before changing the model.
- **A change appears delayed:** it may be a background analysis/cache refresh;
  wait for the prepared result and avoid judging during rapid edits.
- **A held voice ignores routing changes:** this is intentional trigger-time bus
  latching; retrigger the pad to hear the new route.
- **The sound loses its attack:** restore Residual, Strike, Transient, or the
  relevant high-frequency/attack control before increasing body complexity.
- **A reconstruction clips or distorts:** for Warp, reduce Excitation Level;
  for other modes, reduce Pre-Saturation Gain or the mode's own gain controls.
  Reducing Level afterward cannot undo clipping that already occurred. Voice
  Ceiling is a fixed per-voice safety stage, not a dynamic final-bus limiter.
- **Warp sounds too smooth or broad:** establish the resonances first, then add
  a small amount of Notches. It carves valleys between the model's peaks; it
  does not target a fixed frequency. Reduce Notches if the result becomes thin
  or phasey.
- **Automation targets the wrong mode:** use permanent host codes and parameter
  IDs, not the visible editor order.
- **The user wants credits retained:** use optional `attribution.json`; keep
  unresolved fields visible rather than inventing details.
