# Audio regions and vocals

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.

## `AudioOptions`

Options for `audio()`: times in beats, offsets and lengths in seconds.

```ts
export type AudioOptions = Readonly<{
  /** Stable clip id; defaults to `clip`, `clip2`, ... by position. */
  id?: string;
  /** Beat the clip starts on, default 0. */
  at?: number;
  /** Seconds into the file where the clip starts, default 0. */
  offset?: number;
  /** Seconds of the file it plays, default to the end. */
  dur?: number;
  /** Linear gain 0..4, default 1. */
  gain?: number;
  /** Equal-power fade in, seconds (default 5 ms). */
  fadeInTime?: number;
  /** Equal-power fade out, seconds (default 5 ms). */
  fadeTime?: number;
  /** Play the slice backwards. */
  rev?: boolean;
  /** The track take this clip plays from (its clock drift applies). */
  take?: string;
  mute?: boolean;
  /** The words sung in the clip, for the highway and lyrics. */
  text?: string;
  /** A text-to-speech clip's time map (0.7.1); kept as written. */
  say?: Readonly<Record<string, unknown>>;
  /** The file's pin; DAWN fills it from the file when absent. */
  sha256?: string;
}>;
```

## `AudioSpec`

One audio clip as `audio()` builds it.

```ts
export type AudioSpec = Readonly<
  {
    kind: "audio";
    src: string;
    at: number;
  } & Omit<AudioOptions, "at">
>;
```

## `audio`

An audio file on the track's timeline (SDK 1.32.0). `src` is relative
to the track folder (`samples/lead.wav`) or the project
(`tracks/vox/samples/lead.wav`).

```ts
clips: [audio("samples/verse.wav", { at: 16, gain: 0.8, fadeTime: 0.2 })];
```

```ts
export declare function audio(src: string, options?: AudioOptions): AudioSpec;
```

## `repeatAudio`

Copies of `clip` every `every` beats after it while they start before
`until` (SDK 1.32.0), the clip first: `...repeatAudio(hook, { every: 8,
until: 64 })`. Copies of a clip with an id get `<id>-r2`, `<id>-r3`, ...

```ts
export declare function repeatAudio(
  clip: AudioSpec,
  options: Readonly<{
    every: number;
    until: number;
  }>,
): readonly AudioSpec[];
```

## `TakeOptions`

Options for `take()`: `at`, `in` and `out` in beats, the rest in seconds.

```ts
export type TakeOptions = Readonly<{
  /** Beat the recording's first sample lines up with. */
  at?: number;
  /** Punch range in beats, default `at` to `at + 4`. */
  in?: number;
  out?: number;
  /** Seconds into the file where the take starts. */
  offset?: number;
  /** Round-trip latency compensated, seconds. */
  latency?: number;
  latencyAssumed?: boolean;
  /** Clock drift in parts per million (±1000). */
  ppm?: number;
  /** 0..1 fit of the alignment. */
  fit?: number;
  warn?: string;
  /** Manual nudge in milliseconds (±250). */
  nudge?: number;
  sha256?: string;
}>;
```

## `TakeSpec`

One take as `take()` builds it.

```ts
export type TakeSpec = Readonly<
  {
    kind: "take";
    name: string;
    src: string;
    at: number;
    in: number;
    out: number;
  } & Omit<TakeOptions, "at" | "in" | "out">
>;
```

## `take`

A take (SDK 1.32.0): one recorded or imported pass the track's clips can
play from (`audio(src, { take: "take-1" })`). Recording itself is 0.7.1.

```ts
export declare function take(
  name: string,
  src: string,
  options?: TakeOptions,
): TakeSpec;
```

## `lyrics`

Sings `text` on `notes` in time order (SDK 1.32.0): spaces split words,
`-` splits syllables, `_` holds the previous syllable over the next note
(melisma), `~` skips a note. With fewer syllables than notes, words typed
whole split by vowel groups and leftover notes hold the last syllable;
syllables past the last note are dropped. Same rules as `/lyrics`.
SDK 1.36.0: a syllable whose word goes on keeps a trailing `-`;
`hel[hh eh l]-lo` sets the note's `vox.ph`, `,` puts a breath
(`vox.breath` 0.2) before the next syllable, `/` is a line break.

```ts
notes: lyrics("sun-lit morn-ing glow", seq("C4 D4 E4 G4 E4"));
```

```ts
export declare function lyrics<N extends NoteSpec>(
  text: string,
  notes: readonly N[],
): readonly N[];
```

## `defaultClipId`

The id a clip without one gets: `clip`, `clip2`, `clip3`, ...

```ts
export declare function defaultClipId(index: number): string;
```
