# Instruments and sampling

SDK 1.53.0. Generated from the SDK source and its original JSDoc. See the [API index](/docs/sdk-index) for version and source provenance, or the [SDK guide](/docs/sdk) for a first composition.

## `SampleSpec`

One sample voice. A bare string is `{ src }`.

```ts
export type SampleSpec = Readonly<{
  /**
   * Audio file: track-relative (`samples/kick.wav`) or project-relative
   * (`tracks/x/samples/kick.wav`), or a pack sound
   * `pack:<pack>/<sound>[:<n>]` such as `pack:tidal-drum-machines/RolandTR909_bd:0`
   * (fetched once into the cache; see `/pack`).
   */
  src: string;
  /** Pack sounds: content hash DAWN pinned when the sound was first used. */
  sha256?: string;
  /** Pack sounds: the pinned HTTPS file. */
  url?: string;
  /** Pack sounds: the pack's license, recorded for credits. */
  license?: string;
  /** Pitch the file plays at, keyed mode only; default C4. */
  root?: Pitch;
  /** Start fraction 0..1 of the file, like Strudel `begin`. */
  begin?: number;
  /** End fraction 0..1 of the file, like Strudel `end`. */
  end?: number;
  /** Linear gain 0..2. */
  gain?: number;
  /** Playback rate, like Strudel `speed`; negative reverses. */
  speed?: number;
  /** Sustain by looping `begin..end`. */
  loop?: boolean;
  /** Choke group, like Strudel `cut`: a new hit stops the previous one in the group. */
  choke?: string;
  /** Looped part, like Strudel `loopBegin`/`loopb` (fraction, ≥ begin). */
  loopBegin?: number;
  /** Alias of `loopBegin` (Strudel `loopb`). */
  loopb?: number;
  /** Looped part end, like Strudel `loopEnd`/`loope` (fraction, ≤ end). */
  loopEnd?: number;
  /** Alias of `loopEnd` (Strudel `loope`). */
  loope?: number;
  /** Like Strudel `clip`: the voice lasts note length × clip (0 < clip ≤ 16), cutting the sample. */
  clip?: number;
  /** Alias of `clip` (Strudel `legato`). */
  legato?: number;
  /** Like Tidal `unit`: `"r"` rate (default), `"c"` speed in cycles (bars), `"s"` speed in seconds. */
  unit?: "r" | "c" | "s";
  /** Like Strudel `fit`: the window lasts exactly the note's length. */
  fit?: boolean;
  /** Like Strudel `loopAt(n)`: the window lasts n bars (stored as `speed: 1/n, unit: "c"`). */
  loopAt?: number;
  /** Like Tidal `accelerate`: rate ramps by this × the start rate over the voice (−8..8). */
  accelerate?: number;
  /** Like Tidal `squiz`: pitch-raise ratio per zero-crossing cycle (1..32). */
  squiz?: number;
  /** The file's own tempo (20..400, SDK 1.20.0): the window follows the song's tempo map. */
  bpm?: number;
  /** How a fitted window changes time (SDK 1.20.0): `"repitch"` (tape), `"beats"` (onset slices), `"tones"` (keeps pitch). */
  fitmode?: "repitch" | "beats" | "tones";
  /** Window length in beats (SDK 1.20.0); `fit` wins over `bpm`, `bpm` over `len`. */
  len?: number;
  /** Pitch shift in semitones at the same length (−24..24, SDK 1.29.0). */
  shift?: number;
  /** Formant shift in semitones with `shift` (SDK 1.29.0): absent follows the pitch, 0 keeps the formants. */
  formant?: number;
  /** Like Strudel `fadeTime`: release fade in seconds (0..2, SDK 1.29.0). */
  fadeTime?: number;
  /** Like Strudel `fadeInTime`: attack fade in seconds (0..2, SDK 1.29.0). */
  fadeInTime?: number;
  /** Where `resample` rendered the file from (informational, SDK 1.29.0). */
  from?: SampleProvenanceSpec;
  /** Velocity layer (SDK 1.31.0, SFZ lovel/hivel): MIDI velocities `[lo, hi]` this voice plays. */
  vel?: readonly [number, number];
  /** Round-robin group (SDK 1.31.0, SFZ seq_length): voices in a group take turns, A B A B. */
  rr?: string;
}>;
```

## `SampleProvenanceSpec`

`SampleSpec.from` (SDK 1.29.0): the source of a resampled file.

```ts
export type SampleProvenanceSpec = Readonly<{
  /** `track:<id>`, `orbit:<n>` or `master`. */
  source: string;
  section?: string;
  bars?: readonly [number, number];
  /** sha256 of the score the file was rendered from. */
  score: string;
}>;
```

## `SamplerSpec`

Result of `sampler()`; pass it as a track's `instrument`.

```ts
export type SamplerSpec = Readonly<{
  kind: "sampler";
  voices: Readonly<Record<string, SampleSpec>>;
  /** `oneshot` (default): voices are hits. `keyed`: voices are resampled across the keyboard from `root`. */
  mode: "oneshot" | "keyed";
}>;
```

## `SamplerOptions`

Options for `sampler()`.

```ts
export type SamplerOptions = Readonly<{
  mode?: "oneshot" | "keyed";
}>;
```

## `sampler`

A sample instrument. Voice names are `[A-Za-z][A-Za-z0-9_]*`, at most 64.

```ts
instrument: sampler({ kick: "samples/kick.wav", snare: "samples/sd.wav" });
instrument: sampler(
  { vox: { src: "samples/vox.wav", root: "C4" } },
  { mode: "keyed" },
);
```

One-shot voices are played with `hit("kick", 0)`; keyed voices with `note()`.

```ts
export declare function sampler(
  voices: Readonly<Record<string, string | SampleSpec>>,
  options?: SamplerOptions,
): SamplerSpec;
```

## `WAVETABLE_INSTRUMENT`

Instrument name that selects a track's wavetable oscillator.

```ts
export declare const WAVETABLE_INSTRUMENT = "wavetable";
```

## `WarpMode`

Strudel's `warpmode` names.

```ts
export type WarpMode =
  "none" | "asym" | "bendp" | "bendm" | "bendmp" | "sync" | "quant";
```

## `WavetableParams`

Wavetable parameters, with Strudel's names. Omitted means default.

```ts
export type WavetableParams = Readonly<{
  /** Position 0..1 (default 0). */
  wt?: number;
  /** Position envelope amount -1..1 and its ADSR (seconds, sustain 0..1). */
  wtenv?: number;
  wtattack?: number;
  wtdecay?: number;
  wtsustain?: number;
  wtrelease?: number;
  /** Position LFO rate (Hz) and depth 0..1. */
  wtrate?: number;
  wtdepth?: number;
  /** Phase warp amount 0..1 and mode. */
  warp?: number;
  warpmode?: WarpMode;
  /** Start phase randomness 0..1 (seeded per note). */
  wtphaserand?: number;
}>;
```

## `WavetableSpec`

Result of `wavetable()`; pass it as a track's `instrument`.

```ts
export type WavetableSpec = Readonly<
  {
    kind: "wavetable";
    table: SampleSpec;
  } & WavetableParams
>;
```

## `wavetable`

A wavetable instrument. `table` is a built-in (`basic`, `pwm`,
`formant`, `harmonics`), a Strudel `wt_` sound (`wt_digital:2` plays
`pack:uzu-wavetables/wt_digital:2`), any `pack:` ref, a project WAV
(`./wavetables/vox.wav`, relative to the track's directory, as the agent's
make_wavetable writes it), or a pinned `{ src, sha256, url }` that DAWN
writes back after resolving it.

```ts
instrument: wavetable("basic", { wt: 0.4 });
instrument: wavetable("./wavetables/vox.wav", { wtenv: 0.5 });
instrument: wavetable("wt_vgame:3", {
  wtenv: 0.6,
  wtdecay: 0.4,
  warp: 0.3,
  warpmode: "bendp",
});
```

```ts
export declare function wavetable(
  table: string | SampleSpec,
  params?: WavetableParams,
): WavetableSpec;
```

## `STRING_INSTRUMENT`

Instrument name of the 0.6 string engine (`Track.string`).

```ts
export declare const STRING_INSTRUMENT = "string";
```

## `StringInput`

String engine settings (SDK 1.21.0): a `preset` (`nylon`, `steel`,
`electric`, `jangle`, `ebass`, `slap`, `upright`, `sitar`, `tanpura`,
`harpsichord`, `lute`, `oud`, `setar`, `tar`, `santur`, `dulcimer`, `koto`,
`harp`, `banjo`, `tres`, `requinto`; bowed since SDK 1.31.0: `violin`,
`viola`, `cello`, `contrabass`, `fiddle`, `erhu`, `kamancheh`, `violins`,
`violas`, `cellos`, `contrabasses`, `pizz`, `trem`) plus any parameter to
override (`ring`, `bright`, `damp`, `pos`, `mute`, `buzz`, `body`, `sym`,
bow: `exciter: "bow"`, `pressure`, `speed`, `attack`, `vib`, `vibmod`,
`vibdelay`, `tremhz`, `sord`, `dyn`). DAWN validates names and ranges;
see **Strings** in DAWN.md.

```ts
export type StringInput = Readonly<
  {
    preset?: string;
  } & Record<string, number | string | undefined>
>;
```

## `StringSpec`

Result of `stringed()`; pass it as a track's `instrument`.

```ts
export type StringSpec = Readonly<
  {
    kind: "string";
  } & StringInput
>;
```

## `stringed`

A plucked or bowed string instrument (SDK 1.21.0; bowed and the object
form 1.31.0): a preset and overrides.

instrument: stringed("nylon")
instrument: stringed("sitar", { buzz: 0.8, sym: 0.5 })
instrument: stringed({ preset: "cello", vib: 6 })

```ts
export declare function stringed(
  preset?: string | StringInput,
  params?: Readonly<Record<string, number | string>>,
): StringSpec;
```

## `GRANULAR_INSTRUMENT`

Instrument name of the 0.6 granular engine (`Track.granular`).

```ts
export declare const GRANULAR_INSTRUMENT = "granular";
```

## `GranularInput`

Granular settings (SDK 1.23.0). `src` is a sample (`sample(...)` shape,
pinned like a sampler voice) or a built-in synth render
`"synth:<preset>[@note]"` (default `synth:pad`, nothing to download);
`preset` is `cloud`, `hold`, `sparkle`, `swarm`, `stutter`, `microloop`,
`backwards` or `dust`; every other key overrides one parameter (`grain`
seconds, `overlap`, `scan`, `pos`, `begin`, `end`, `spray`, `jitter`,
`pitch`, `detune`, `shimmer`, `shimint`, `spread`, `window`, `reverse`,
`freeze`, `repeat`, `hold`, `drift`, `drate`, `attack`, `release`,
`veltone`, `gain`, `seed`, `root`). DAWN validates names and ranges; see
**Granular** in DAWN.md.

```ts
export type GranularInput = Readonly<
  {
    src?: string | SampleSpec;
    preset?: string;
  } & Record<string, number | string | boolean | SampleSpec | undefined>
>;
```

## `GranularSpec`

Result of `granular()`; pass it as a track's `instrument`.

```ts
export type GranularSpec = Readonly<
  {
    kind: "granular";
  } & GranularInput
>;
```

## `granular`

A granular instrument (SDK 1.23.0): an optional preset, then overrides.

```ts
instrument: granular("cloud");
instrument: granular("hold", { src: "samples/choir.wav", scan: 0 });
instrument: granular({ src: "synth:bell@72", grain: 0.08, overlap: 6 });
```

```ts
export declare function granular(
  preset?: string | GranularInput,
  params?: GranularInput,
): GranularSpec;
```

## `MODAL_INSTRUMENT`

Instrument name that selects the modal mallet-and-bell engine (SDK 1.25.0).

```ts
export declare const MODAL_INSTRUMENT = "modal";
```

## `ModalPresetName`

Modal presets (DAWN's core/resonators.ts).

```ts
export type ModalPresetName =
  | "marimba"
  | "vibes"
  | "xylophone"
  | "glock"
  | "celesta"
  | "chimes"
  | "kalimba"
  | "mbira"
  | "steelpan"
  | "bowl"
  | "gong"
  | "timpani"
  | "crotales"
  | "musicbox"
  | "toypiano"
  | "saron"
  | "demung"
  | "slenthem"
  | "gangsa"
  | "gender"
  | "bonang"
  | "kenong"
  | "kethuk"
  | "kempul"
  | "daf"
  | "bodhran"
  | "tabla";
```

## `ModalParams`

Modal overrides; omitted means the preset's value. DAWN validates ranges.

```ts
export type ModalParams = Readonly<{
  /** `yarn` `cord` `rubber` `plastic` `brass`: sets hardness. */
  mallet?: "yarn" | "cord" | "rubber" | "plastic" | "brass";
  /** Mallet hardness 0..1: brighter, shorter contact. */
  hardness?: number;
  /** Strike position 0..1 (0.5 is the bar's centre). */
  position?: number;
  /** Fundamental ring time (T60 seconds). */
  ring?: number;
  /** How much faster upper modes die (octaves of decay per octave). */
  tilt?: number;
  /** Damping on note-off 0..1 (0 lets the bar ring). */
  damp?: number;
  /** Choke time after note-off, seconds. */
  release?: number;
  /** Vibraphone motor rate Hz and depth 0..1. */
  motor?: number;
  motordepth?: number;
  /** Beat between paired gamelan modes, Hz. */
  ombak?: number;
  /** Mbira buzz 0..1 and mallet click 0..1. */
  buzz?: number;
  click?: number;
  /** Strike pitch bend in semitones and its decay seconds (Strudel penv/pdecay). */
  strikebend?: number;
  strikedecay?: number;
  /** Output level 0..2 (1 is the preset level). */
  gain?: number;
  /** Mode table override (`marimba`, `bell`, `gong`, …). */
  body?: string;
  /**
   * The partner track id of an ombak pair (SDK 1.30.0): this track (the
   * pengisep) sounds `ombak` Hz above it. song() sets the partner's ombak
   * to 0 (one straight voice) unless the partner gives its own.
   */
  pair?: string;
}>;
```

## `ModalSpec`

Result of `modal()`; pass it as a track's `instrument`.

```ts
export type ModalSpec = Readonly<
  {
    kind: "modal";
    preset?: ModalPresetName;
  } & ModalParams
>;
```

## `modal`

Mallets and bells on the modal engine (SDK 1.25.0): a preset and
optional overrides. A preset word alone (`instrument: "vibes"`) is the
same as `modal("vibes")`, except `"marimba"`, which stays the legacy
marimba voice; `modal("marimba")` is the modal one.

```ts
instrument: modal("vibes", { motor: 4, hardness: 0.6 });
instrument: modal("marimba", { mallet: "rubber" });
instrument: modal({ ring: 2 }); // default preset (marimba)
```

```ts
export declare function modal(
  preset?: ModalPresetName | ModalParams,
  params?: ModalParams,
): ModalSpec;
```

## `WIND_INSTRUMENT`

The instrument value of the wind engine (core/winds.ts).

```ts
export declare const WIND_INSTRUMENT = "wind";
```

## `WindPresetName`

Wind presets (core/winds.ts WIND_PRESET_NAMES).

```ts
export type WindPresetName =
  | "flute"
  | "recorder"
  | "whistle"
  | "ney"
  | "shakuhachi"
  | "panpipe"
  | "suling"
  | "bansuri"
  | "clarinet"
  | "bassclarinet"
  | "oboe"
  | "bassoon"
  | "sax"
  | "altosax"
  | "barisax"
  | "trumpet"
  | "harmon"
  | "plunger"
  | "trombone"
  | "tuba"
  | "horn";
```

## `WindParams`

Wind overrides (core/winds.ts WIND_PARAMS).

```ts
export type WindParams = Readonly<{
  model?: "jet" | "reed" | "sax" | "lips";
  breath?: number;
  noise?: number;
  attack?: number;
  release?: number;
  vib?: number;
  vibmod?: number;
  reed?: number;
  bright?: number;
  stopped?: boolean;
  mute?: "open" | "straight" | "cup" | "harmon" | "plunger";
  wah?: number;
  wahenv?: number;
  growl?: number;
  flutter?: number;
  players?: number;
  gain?: number;
}>;
```

## `WindSpec`

Result of `wind()`; pass it as a track's `instrument`.

```ts
export type WindSpec = Readonly<
  {
    kind: "wind";
    preset?: WindPresetName;
  } & WindParams
>;
```

## `wind`

Winds and brass on the wind engine (SDK 1.30.0): a preset and optional
overrides. A preset word alone (`instrument: "flute"`) is the same as
`wind("flute")`; the bare word `"wind"` stays the legacy wind tone.

```ts
instrument: wind("sax", { breath: 0.8, growl: 0.2 });
instrument: wind("trumpet", { mute: "harmon", players: 3 });
instrument: wind({ bright: 0.3 }); // default preset (flute)
```

```ts
export declare function wind(
  preset?: WindPresetName | WindParams,
  params?: WindParams,
): WindSpec;
```

## `VOCODER_INSTRUMENT`

The instrument value of the built-in vocoder carrier (core/vocoder.ts).

```ts
export declare const VOCODER_INSTRUMENT = "vocoder";
```

## `VocoderPresetName`

Vocoder presets (core/vocoder.ts VOCODER_PRESET_NAMES).

```ts
export type VocoderPresetName =
  | "classic"
  | "robot"
  | "talkbox"
  | "choir"
  | "glass"
  | "whisper"
  | "smear"
  | "lofi";
```

## `VocoderParams`

Vocoder overrides (core/vocoder.ts VOCODER_PARAMS).

```ts
export type VocoderParams = Readonly<{
  /** The modulator track: an id or a name slug (`"vox"`, `"lead-vox"`). */
  src?: string;
  tap?: "chain" | "dry";
  mode?: "channel" | "talkbox";
  carrier?: "saw" | "supersaw" | "pulse" | "noise";
  follow?: "notes" | "chords" | "drone";
  root?: number;
  spread?: number;
  bands?: number;
  lo?: number;
  hi?: number;
  width?: number;
  attack?: number;
  release?: number;
  formant?: number;
  unvoiced?: number;
  sens?: number;
  hiss?: number;
  gate?: number | "auto";
  enhance?: boolean;
  depth?: number;
  freeze?: boolean;
  mix?: number;
  gain?: number;
  seed?: number;
}>;
```

## `VocoderSpec`

Result of `vocoder()`: a track's `instrument` or its `vocoder` field.

```ts
export type VocoderSpec = Readonly<
  {
    kind: "vocoder";
    preset?: VocoderPresetName;
  } & VocoderParams
>;
```

## `vocoder`

A vocoder (SDK 1.32.0): another track's voice (`src`) shapes this track's
sound. As the `instrument` it plays the built-in carrier (a supersaw
following the notes); as the `vocoder` field it vocodes the track's own
synth or sampler. `src` takes a track id or a name slug.

```ts
instrument: vocoder("talkbox", { src: "vox", formant: 2 });
vocoder: vocoder({ src: "t-vox", bands: 24 });
```

```ts
export declare function vocoder(
  preset?: VocoderPresetName | VocoderParams,
  params?: VocoderParams,
): VocoderSpec;
```

## `TEXTURE_INSTRUMENT`

The instrument value of the texture engine (core/texture.ts).

@since 1.45.0

```ts
export declare const TEXTURE_INSTRUMENT = "texture";
```

## `TextureType`

Texture types (core/texture.ts TEXTURE_TYPES).

@since 1.45.0

```ts
export type TextureType =
  | "room"
  | "rain"
  | "wind"
  | "vinyl"
  | "tape"
  | "hum"
  | "city"
  | "crowd"
  | "data"
  | "air";
```

## `TextureParams`

Texture overrides; omitted means the type's value. DAWN validates them.

@since 1.45.0

```ts
export type TextureParams = Readonly<{
  /** How much happens (drops, gusts, crackle, talkers, glitches), 0..1. */
  density?: number;
  /** Near and bright (0) to far, dark and roomy (1). */
  distance?: number;
  /** Clean (0) to worn (1): grit, whistles, pops, flutter, buzz. */
  wear?: number;
  /** Mono (0) to wide (1); left and right stay positively correlated. */
  width?: number;
  /** Over each note: steady, rise (riser), fall (downlifter) or swell (whoosh). */
  motion?: "steady" | "rise" | "fall" | "swell";
  /** Hum fundamental, 40..70 Hz (50 or 60). */
  mains?: number;
  /** Fade in at each note, seconds. */
  attack?: number;
  /** Fade out after each note, seconds. */
  release?: number;
  /** Level, 0..2. */
  gain?: number;
  /** Variation, a whole number 0..65535. */
  seed?: number;
}>;
```

## `TextureSpec`

Result of `texture()`; pass it as a track's `instrument`.

@since 1.45.0

```ts
export type TextureSpec = Readonly<
  {
    kind: "texture";
    type?: TextureType;
  } & TextureParams
>;
```

## `texture`

A seeded DSP texture (SDK 1.45.0): room tone, rain, wind, vinyl, tape,
mains hum, city, crowd murmur, data glitches or air. Pitch is ignored:
each note is one event, its length the bed's length and its velocity
the level. Renders are byte-identical for the same seed.

```ts
instrument: texture("rain", { density: 0.7, distance: 0.4 });
instrument: texture("air", { motion: "swell" }); // a whoosh
instrument: "texture"; // room tone
```

@since 1.45.0

```ts
export declare function texture(
  type?: TextureType | TextureParams,
  params?: TextureParams,
): TextureSpec;
```

## `SING_INSTRUMENT`

The instrument value of the singing voice (core/sing.ts).

```ts
export declare const SING_INSTRUMENT = "sing";
```

## `SingPresetName`

Sing presets (core/sing.ts SING_PRESET_NAMES).

```ts
export type SingPresetName =
  | "aah"
  | "ooh"
  | "choir"
  | "oohchoir"
  | "chorale"
  | "airy"
  | "glass"
  | "lament"
  | "soprano"
  | "basso"
  | "drone"
  | "khoomei"
  | "sygyt"
  | "kargyraa"
  | "robot"
  | "speak";
```

## `SingParams`

Sing overrides (core/sing.ts SING_PARAMS).

```ts
export type SingParams = Readonly<{
  voice?: "auto" | "soprano" | "alto" | "tenor" | "bass";
  /** `"a"`, `"e"`, `"i"`, `"o"`, `"u"` or a morph `"a>o"`. */
  vowel?: string;
  morph?: number;
  formant?: number;
  bright?: number;
  breath?: number;
  jitter?: number;
  shimmer?: number;
  attack?: number;
  release?: number;
  vib?: number;
  vibmod?: number;
  vibdelay?: number;
  voices?: number;
  spread?: number;
  ring?: number;
  /** Throat drone: a note name (`"D3"`) or MIDI 36..67. */
  drone?: string | number;
  overtone?: number;
  /** Throat melody harmonic range `[lo, hi]`, 2..24. */
  harmonics?: readonly [number, number];
  sub?: number;
  /** Machine vox (SDK 1.37.0): consonant strength 0..1 (0 sings vowels only). */
  articulate?: number;
  gain?: number;
}>;
```

## `SingSpec`

Result of `sing()`; pass it as a track's `instrument`.

```ts
export type SingSpec = Readonly<
  {
    kind: "sing";
    preset?: SingPresetName;
  } & SingParams
>;
```

## `sing`

The built-in singing voice (SDK 1.32.0): an LF glottal source through
SATB formants, choirs, and Tuvan throat singing. A preset word alone
(`instrument: "choir"`) is the same as `sing("choir")`. Notes sing their
`vowel` (`note("A3", 0, 2, 0.8, { vowel: "a>o" })`), else their lyric's
vowel, else the track's.

```ts
instrument: sing("choir", { vowel: "o" });
instrument: sing("khoomei", { drone: "D3" }); // notes pick the overtone
instrument: sing({ voices: 4, breath: 0.3 }); // default preset (aah)
```

```ts
export declare function sing(
  preset?: SingPresetName | SingParams,
  params?: SingParams,
): SingSpec;
```

## `VOX_ENGINE_WORDS`

Vox engines (core/vox.ts VOX_ENGINES); only `formant` is built in.

```ts
export declare const VOX_ENGINE_WORDS: readonly string[];
```

## `VOX_DEFAULT_BREATH`

A breath a `,` in lyrics() writes (core/vox.ts DEFAULT_BREATH).

```ts
export declare const VOX_DEFAULT_BREATH = 0.2;
```

## `NoteVoxInput`

`note(..., { vox })` as written: `ph` may be one string of phones.

```ts
export type NoteVoxInput = Readonly<{
  /** Phones replacing letter-to-sound, `"hh eh l"` (ARPAbet, stress dropped). */
  ph?: string | readonly string[];
  /** Language for letter-to-sound, `"en-us"`. */
  lang?: string;
  /** Onset consonants: a share of the note 0..0.9, or `{ s }` seconds. */
  cons?:
    | number
    | Readonly<{
        s: number;
      }>;
  /** Seconds the onset starts before the note, 0..0.25. */
  lead?: number;
  /** Syllable timing offset in seconds, -0.25..0.25. */
  shift?: number;
  /** A breath before this note, seconds 0.05..1. */
  breath?: number;
  /** Loudness over the note: `{ at, v }` points. */
  dyn?: readonly Readonly<{
    at: number;
    v: number;
  }>[];
  /** Engine params, at most 8. */
  p?: Readonly<Record<string, number>>;
}>;
```

## `NoteVoxSpec`

A stored note `vox`: `ph` as an array; DAWN checks the ranges.

```ts
export type NoteVoxSpec = Readonly<
  Omit<NoteVoxInput, "ph"> & {
    ph?: readonly string[];
  }
>;
```

## `TrackVoxSpec`

A track's `vox`: engine, voice and optional language, fit and params.

```ts
export type TrackVoxSpec = Readonly<{
  engine: string;
  voice: string;
  lang?: string;
  fit?: "psola" | "world" | "none";
  p?: Readonly<Record<string, number>>;
}>;
```

## `VoxSpec`

Result of `vox()`; pass it as a track's `vox`.

```ts
export type VoxSpec = Readonly<
  {
    kind: "vox";
  } & TrackVoxSpec
>;
```

## `vox`

Machine vox (SDK 1.36.0): the engine and voice that sing a track's
lyrics. `formant` is built in; the rest are external engines.

vox: vox("formant", "formant:robot")
vox: vox("kokoro", "kokoro:af_heart", { lang: "en-us", fit: "psola" })

```ts
export declare function vox(
  engine?: string,
  voice?: string,
  opts?: Readonly<{
    lang?: string;
    fit?: "psola" | "world" | "none";
    p?: Readonly<Record<string, number>>;
  }>,
): VoxSpec;
```

## `AutotunePresetName`

Autotune presets, gentle to hard (core/autotune.ts AUTOTUNE_PRESETS).

```ts
export type AutotunePresetName =
  | "hard"
  | "robot"
  | "warble"
  | "trap"
  | "pop"
  | "natural"
  | "gentle"
  | "guided"
  | "locked";
```

## `AutotuneParams`

Autotune fields; DAWN checks the ranges (core/autotune.ts AUTOTUNE_PARAMS).

```ts
export type AutotuneParams = Readonly<{
  /** Targets: `scale` (song or track key, else chromatic), `chromatic`, `chord`, `notes`. */
  to?: "scale" | "chromatic" | "chord" | "notes";
  /** Guide track id for `to: "notes"` (a vocal track may use its own notes). */
  from?: string;
  /** Scale for this track, e.g. `"D bayati"`; default the song key. */
  key?: string;
  /** Retune time in ms, 0..400; 0 is instant and stepped. */
  speed?: number;
  /** 0..1 slower retune on held notes. */
  relax?: number;
  /** ms 50..1000 before a note counts as held. */
  hold?: number;
  /** 0..100: higher only pulls notes already near a target. */
  flex?: number;
  /** Seconds 0..0.5 to move between targets. */
  glide?: number;
  /** 0..1 correction strength. */
  amount?: number;
  /** Added vibrato rate in Hz, 0..12 (0 off). */
  vib?: number;
  /** Added vibrato depth in semitones, 0..1. */
  vibmod?: number;
  /** Notes mode: 0..1 how far each note's middle moves to the written pitch. */
  center?: number;
  /** Notes mode: 0..1 share of slow drift removed. */
  drift?: number;
  /** Tracker range: `auto`, `bass`, `tenor`, `alto`, `soprano`. */
  voice?: "auto" | "bass" | "tenor" | "alto" | "soprano";
}>;
```

## `AutotuneSettings`

Stored autotune settings: a preset and any fields that override it.

```ts
export type AutotuneSettings = Readonly<
  {
    preset?: AutotunePresetName;
  } & AutotuneParams
>;
```

## `AutotuneSpec`

Result of `autotune()`; pass it as a track's `autotune`.

```ts
export type AutotuneSpec = Readonly<
  {
    kind: "autotune";
  } & AutotuneSettings
>;
```

## `autotune`

Pitch correction (SDK 1.33.0), from `gentle` to `hard`; the preset word
alone also works as a track's `autotune`. Fields override the preset.

autotune: "hard"
autotune: autotune("pop", { speed: 40, key: "D bayati" })
autotune: autotune("guided", { from: "lead" })

```ts
export declare function autotune(
  preset?: AutotunePresetName | AutotuneParams,
  params?: AutotuneParams,
): AutotuneSpec;
```

## `slices`

`count` equal slices of one file as voices `prefix0 … prefixN-1`, for
chopped breaks: `sampler(slices("samples/break.wav", 8, "brk"))`, then
`hit("brk3", 1.5)`.

```ts
export declare function slices(
  src: string | SampleSpec,
  count: number,
  prefix?: string,
): Record<string, SampleSpec>;
```

## `sample`

One sample file with options (SDK 1.20.0), for `sampler({ brk: ... })`:
`sample("samples/break.wav", { bpm: 174, fitmode: "beats" })` plays a
174 BPM break in time with the song, cut at its hits.

```ts
export declare function sample(
  src: string,
  options?: Omit<SampleSpec, "src">,
): SampleSpec;
```
