Pitches, notes and expression
For agents
Give your agent this page’s Markdown link, or choose a collection.
- Documentation indexFind a guide and its Markdown link.
- Full documentationRead all curated guides in one text file.
- Machine manifestFind page metadata, Markdown URLs and checksums.
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_VERSION
Section titled “SDK_VERSION”SDK release; DAWN refreshes the vendored copy when its own is newer.
export declare const SDK_VERSION = "1.53.0";SDK_MAJOR
Section titled “SDK_MAJOR”Major of SDK_VERSION; dawn.json records it as sdk.
export declare const SDK_MAJOR = 1;DEFAULT_TICKS_PER_BEAT
Section titled “DEFAULT_TICKS_PER_BEAT”Ticks per beat the score uses unless song({ ticksPerBeat }) says otherwise.
export declare const DEFAULT_TICKS_PER_BEAT = 480;DEFAULT_VELOCITY
Section titled “DEFAULT_VELOCITY”Velocity used when a note or hit omits it.
export declare const DEFAULT_VELOCITY = 0.8;DEFAULT_HIT_LENGTH
Section titled “DEFAULT_HIT_LENGTH”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;DawnSdkError
Section titled “DawnSdkError”Thrown by every builder when its input is malformed; the message names the field.
export declare class DawnSdkError extends Error { constructor(message: string);}Removed
Section titled “Removed”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;};removed
Section titled “removed”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;pitchCents
Section titled “pitchCents”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;}>;DrumVoice
Section titled “DrumVoice”Drum voice names a kit track understands in hit().
export type DrumVoice = "kick" | "snare" | "clap" | "rim" | "tom" | "hat" | "openhat";DRUM_PITCHES
Section titled “DRUM_PITCHES”GM pitch stored for each kit voice; hit("kick", 0) writes pitch 36.
export declare const DRUM_PITCHES: Readonly<Record<DrumVoice, number>>;KIT_INSTRUMENTS
Section titled “KIT_INSTRUMENTS”Instrument names DAWN treats as the synthesized drum kit.
export declare const KIT_INSTRUMENTS: readonly string[];SAMPLER_INSTRUMENT
Section titled “SAMPLER_INSTRUMENT”Instrument name that selects a track’s sampler.
export declare const SAMPLER_INSTRUMENT = "sampler";SAMPLER_FIRST_SLOT
Section titled “SAMPLER_FIRST_SLOT”First pitch slot given to one-shot sampler voices (voice names sorted).
export declare const SAMPLER_FIRST_SLOT = 36;NoteSpec
Section titled “NoteSpec”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;HitSpec
Section titled “HitSpec”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;Articulation
Section titled “Articulation”How a note is articulated (SDK 1.15.0).
export type Articulation = "staccato" | "legato" | "accent" | "tenuto" | "marcato" | "ghost";ARTICULATIONS
Section titled “ARTICULATIONS”export declare const ARTICULATIONS: readonly Articulation[];BendPoint
Section titled “BendPoint”A pitch-bend point: [at, cents], at 0..1 through the note.
export type BendPoint = readonly [number, number];Expression
Section titled “Expression”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 toneexport 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;}>;NoteExpressionSpec
Section titled “NoteExpressionSpec”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 beatnote("A1", 1.5, 0.5, 0.6); // off-beat eighth, softernote("A1", 2, 1, 0.8, { art: "staccato" });note("E4-14c", 2); // a just major third over C, 14 cents flatexport declare function note( pitch: Pitch, start: number, length?: number, velocity?: number, how?: Expression,): NoteSpec;SeqOptions
Section titled “SeqOptions”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[];EveryOptions
Section titled “EveryOptions”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.