# Pitches, notes and expression

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.

## `SDK_VERSION`

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

```ts
export declare const SDK_VERSION = "1.53.0";
```

## `SDK_MAJOR`

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

```ts
export declare const SDK_MAJOR = 1;
```

## `DEFAULT_TICKS_PER_BEAT`

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

```ts
export declare const DEFAULT_TICKS_PER_BEAT = 480;
```

## `DEFAULT_VELOCITY`

Velocity used when a note or hit omits it.

```ts
export declare const DEFAULT_VELOCITY = 0.8;
```

## `DEFAULT_HIT_LENGTH`

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

```ts
export declare const DEFAULT_HIT_LENGTH = 0.25;
```

## `Pitch`

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

```ts
export type Pitch = number | string;
```

## `DawnSdkError`

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

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

## `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

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

## `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

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

## `midi`

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.

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

## `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.

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

## `DrumVoice`

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

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

## `DRUM_PITCHES`

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

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

## `KIT_INSTRUMENTS`

Instrument names DAWN treats as the synthesized drum kit.

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

## `SAMPLER_INSTRUMENT`

Instrument name that selects a track's sampler.

```ts
export declare const SAMPLER_INSTRUMENT = "sampler";
```

## `SAMPLER_FIRST_SLOT`

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

```ts
export declare const SAMPLER_FIRST_SLOT = 36;
```

## `NoteSpec`

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

```ts
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`

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

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

## `Articulation`

How a note is articulated (SDK 1.15.0).

```ts
export type Articulation =
  "staccato" | "legato" | "accent" | "tenuto" | "marcato" | "ghost";
```

## `ARTICULATIONS`

```ts
export declare const ARTICULATIONS: readonly Articulation[];
```

## `BendPoint`

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

```ts
export type BendPoint = readonly [number, number];
```

## `Expression`

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

```ts
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
```

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

## `NoteExpressionSpec`

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

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

## `expr`

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

```ts
notes: expr(seq("C2 C2 Eb2 C3", { step: 0.25 }), { art: "staccato" });
```

```ts
export declare function expr<T extends NoteSpec | HitSpec>(
  notes: readonly T[],
  expression_: Expression,
): readonly T[];
```

## `note`

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

```ts
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
```

```ts
export declare function note(
  pitch: Pitch,
  start: number,
  length?: number,
  velocity?: number,
  how?: Expression,
): NoteSpec;
```

## `SeqOptions`

Options for `seq()`.

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

## `seq`

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

```ts
seq("E2 G2 A2", { from: 4, step: 0.5, len: 0.5 });
seq("C4 . E4 . G4", { step: 0.25 });
```

```ts
export declare function seq(
  pattern: string | readonly Pitch[],
  options?: SeqOptions,
): readonly NoteSpec[];
```

## `hit`

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

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

## `hits`

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

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

## `EveryOptions`

Options for `every()`.

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

## `every`

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]`.

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