Skip to content

Pitches, notes and expression

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.

SDK release; DAWN refreshes the vendored copy when its own is newer.

export declare const SDK_VERSION = "1.53.0";

Major of SDK_VERSION; dawn.json records it as sdk.

export declare const SDK_MAJOR = 1;

Ticks per beat the score uses unless song({ ticksPerBeat }) says otherwise.

export declare const DEFAULT_TICKS_PER_BEAT = 480;

Velocity used when a note or hit omits it.

export declare const DEFAULT_VELOCITY = 0.8;

Length in beats used when a hit omits it (a sixteenth at 4/4).

export declare const DEFAULT_HIT_LENGTH = 0.25;

A MIDI number 0..127 or a pitch name such as "C4", "F#2", "Bb3".

export type Pitch = number | string;

Thrown by every builder when its input is malformed; the message names the field.

export declare class DawnSdkError extends Error {
constructor(message: string);
}

A field or export that no longer exists. tsc prints the message verbatim (Type 'number' is not assignable to type 'Removed<"volume was renamed to gain in SDK 1.44.0 · run dawn migrate --apply">'), so the type error itself says what to use instead. A stub stays for one SDK minor line.

@since 1.42.0

export type Removed<Message extends string> = {
readonly "dawn: removed": Message;
};

The runtime half of a removed export: a frozen object that is not callable, so a JavaScript project or an untyped call fails with the same text the type carries.

@since 1.42.0

export declare function removed<Message extends string>(
name: string,
since: string,
message: Message,
): Removed<Message>;

MIDI number for a pitch name ("A4" → 69, "C#3" → 49, "Bb2" → 46; octaves -1..9, case-insensitive). Numbers 0..127 pass through. Throws DawnSdkError otherwise.

export declare function midi(pitch: Pitch): number;

A pitch with an optional cents suffix (SDK 1.16.0): "E4-14c" is E4 fourteen cents flat, "A3+50c" a quarter tone sharp. The offset is static and sits on top of the song or track tuning; ±1200 at most.

export declare function pitchCents(pitch: Pitch): Readonly<{
pitch: number;
cents: number;
}>;

Drum voice names a kit track understands in hit().

export type DrumVoice =
"kick" | "snare" | "clap" | "rim" | "tom" | "hat" | "openhat";

GM pitch stored for each kit voice; hit("kick", 0) writes pitch 36.

export declare const DRUM_PITCHES: Readonly<Record<DrumVoice, number>>;

Instrument names DAWN treats as the synthesized drum kit.

export declare const KIT_INSTRUMENTS: readonly string[];

Instrument name that selects a track’s sampler.

export declare const SAMPLER_INSTRUMENT = "sampler";

First pitch slot given to one-shot sampler voices (voice names sorted).

export declare const SAMPLER_FIRST_SLOT = 36;

A pitched note in beats. Build with note() or seq().

export type NoteSpec = Readonly<{
kind: "note";
/** MIDI 0..127. */
pitch: number;
/** Start in beats from the loop start, ≥ 0. */
start: number;
/** Length in beats, > 0. */
length: number;
/** 0..1. */
velocity: number;
/** Static offset in cents from a `"E4-14c"` pitch (SDK 1.16.0); absent is 0. */
cents?: number;
}> &
NoteExpressionSpec;

A drum or sampler hit addressed by voice name; resolved to a pitch slot by track().

export type HitSpec = Readonly<{
kind: "hit";
voice: string;
start: number;
length: number;
velocity: number;
}> &
NoteExpressionSpec;

How a note is articulated (SDK 1.15.0).

export type Articulation =
"staccato" | "legato" | "accent" | "tenuto" | "marcato" | "ghost";
export declare const ARTICULATIONS: readonly Articulation[];

A pitch-bend point: [at, cents], at 0..1 through the note.

export type BendPoint = readonly [number, number];

How one note is played (SDK 1.15.0). Every field is optional.

note("C4", 0, 1, 0.8, { art: "staccato" });
note("E4", 1, 2, 0.8, { glide: 0.1, vibrato: { depth: 30, delay: 0.3 } });
note("G4", 3, 1, 0.8, {
bend: [
[0, -200],
[0.25, 0],
],
}); // scoop up a tone
export type Expression = Readonly<{
/**
* `staccato` (half length), `legato` (held into the next note),
* `accent` (louder), `tenuto` (full length, a little louder), `marcato`
* (two-thirds length, much louder) or `ghost` (half length, much softer).
*/
articulation?: Articulation;
/** Short alias of `articulation`. */
art?: Articulation;
/** Portamento into this note from the track's previous pitch, seconds (0..10). */
glide?: number;
/** Pitch curve in cents as `[at, cents]` points, `at` 0..1 through the note; linear between points. */
bend?: readonly BendPoint[];
/** Vibrato: `rate` Hz (default 5.5), `depth` cents either side (default 20), `delay` seconds before it fades in. */
vibrato?: Readonly<{
rate?: number;
depth?: number;
delay?: number;
}>;
/**
* This note's humanize (SDK 1.15.0), replacing the track's amounts:
* `{ timing ms, velocity %, length % }`; `{}` keeps the note exact.
* Humanize just bars 5-8 with `expr({ humanize: { timing: 10 } }, ...)`.
*/
humanize?: Readonly<{
timing?: number;
velocity?: number;
length?: number;
}>;
/** The sung vowel on a `sing()` track (SDK 1.32.0): `"a"` .. `"u"` or a morph `"a>o"`. */
vowel?: string;
/** The syllable sung on this note (SDK 1.32.0): no spaces, `_` holds the previous one. */
lyric?: string;
/**
* On an autotune guide note (SDK 1.33.0): the share of slow pitch drift
* removed, 0..1, overriding the track's `autotune` drift.
*/
drift?: number;
/**
* How this note is voiced on a vox track (SDK 1.36.0):
* `{ ph: "hh eh l", breath: 0.2 }`. `ph` takes phones as one string.
*/
vox?: NoteVoxInput;
/**
* This note's id (SDK 1.50.0), 1..64 characters. It seeds the note's
* humanize, noise and phase, so the same id renders the same sound.
* Absent, `song()` derives one from the note's content; the printer writes
* it only where it differs from that, to keep a score's exact render.
* Copies made by `bars()`, `place()` and `reversed()` drop it, and `expr()`
* cannot share one.
*/
id?: string;
}>;

The expression a built note carries; fields are present only when set.

export type NoteExpressionSpec = Readonly<{
id?: string;
articulation?: Articulation;
glide?: number;
bend?: readonly BendPoint[];
vibrato?: Readonly<{
rate: number;
depth: number;
delay?: number;
}>;
humanize?: Readonly<{
timing?: number;
velocity?: number;
length?: number;
}>;
vowel?: string;
lyric?: string;
drift?: number;
vox?: NoteVoxSpec;
}>;

The same expression on many notes or hits (SDK 1.15.0); a note’s own fields win.

notes: expr(seq("C2 C2 Eb2 C3", { step: 0.25 }), { art: "staccato" });
export declare function expr<T extends NoteSpec | HitSpec>(
notes: readonly T[],
expression_: Expression,
): readonly T[];

One note. pitch is a name or MIDI number, start and length are beats, velocity defaults to 0.8, and how adds expression (articulation, glide, bend, vibrato; SDK 1.15.0). A cents suffix detunes one note (SDK 1.16.0): "E4-14c" (see pitchCents).

note("A1", 0, 1); // A1 on the downbeat for one beat
note("A1", 1.5, 0.5, 0.6); // off-beat eighth, softer
note("A1", 2, 1, 0.8, { art: "staccato" });
note("E4-14c", 2); // a just major third over C, 14 cents flat
export declare function note(
pitch: Pitch,
start: number,
length?: number,
velocity?: number,
how?: Expression,
): NoteSpec;

Options for seq().

export type SeqOptions = Readonly<{
/** Beat of the first step, default 0. */
from?: number;
/** Beats between steps, default 1. */
step?: number;
/** Length of each note in beats, default `step`. */
len?: number;
/** Velocity of each note, default 0.8. */
vel?: number;
}>;

A step sequence: pitches separated by spaces (or an array), one per step beats starting at from. ., - or _ is a rest.

seq("E2 G2 A2", { from: 4, step: 0.5, len: 0.5 });
seq("C4 . E4 . G4", { step: 0.25 });
export declare function seq(
pattern: string | readonly Pitch[],
options?: SeqOptions,
): readonly NoteSpec[];

One drum or sampler hit. On a kit track voice is kick, snare, clap, rim, tom, hat or openhat (aliases bd, sd, cp, hh, oh work); on a sampler() track it is a voice name. length defaults to a sixteenth; how adds expression ({ art: "ghost" }, SDK 1.15.0).

export declare function hit(
voice: string,
start: number,
velocity?: number,
length?: number,
how?: Expression,
): HitSpec;

The same hit on several beats: hits("kick", [0, 1, 2, 3]) or hits("hat", every(0.5, { from: 0.25 }), 0.5).

export declare function hits(
voice: string,
beats: readonly number[],
velocity?: number,
length?: number,
): readonly HitSpec[];

Options for every().

export type EveryOptions = Readonly<{
/** First beat, default 0. */
from?: number;
/** Exclusive end in beats, default 16 (four bars of 4/4). Pass `bars * beatsPerBar`. */
until?: number;
}>;

Beats from from (default 0) up to but excluding until (default 16) every step beats: every(1) → [0, 1, …, 15], every(0.5, { from: 0.25, until: 4 }) → [0.25, 0.75, …, 3.75].

export declare function every(step: number, options?: EveryOptions): number[];

Documentation drafted with AI and checked against the product source.