Skip to content

Audio regions and vocals

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

SDK 1.53.0. Generated from the SDK source and its original JSDoc. See the API index for version and source provenance, or the SDK guide for a first composition.

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

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;
}>;

One audio clip as audio() builds it.

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

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).

clips: [audio("samples/verse.wav", { at: 16, gain: 0.8, fadeTime: 0.2 })];
export declare function audio(src: string, options?: AudioOptions): AudioSpec;

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, …

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

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

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;
}>;

One take as take() builds it.

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

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.

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

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.

notes: lyrics("sun-lit morn-ing glow", seq("C4 D4 E4 G4 E4"));
export declare function lyrics<N extends NoteSpec>(
text: string,
notes: readonly N[],
): readonly N[];

The id a clip without one gets: clip, clip2, clip3, …

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

Documentation drafted with AI and checked against the product source.