# Time, tuning and harmony

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.

## `TimeMark`

One entry of `song({ time })`; build them with the helpers below.

```ts
export type TimeMark =
  | Readonly<{
      kind: "tempo";
      /** Beat the change lands on. */
      at: number;
      /** Absent: keep the tempo in effect there, so a ramp can start from it. */
      bpm?: number;
      /** Glide into `bpm` from the previous mark instead of stepping. */
      ramp?: "linear" | "exp";
      /** Set by `rit()`/`accel()`: the direction `song()` checks. */
      gradual?: "rit" | "accel";
      /**
       * Set by `aTempo()` (the tempo before the last rit/accel) and
       * `tempoPrimo()` (the song's opening tempo) instead of `bpm`.
       */
      back?: "a-tempo" | "primo";
    }>
  | Readonly<{
      kind: "meter";
      /** Beat of the bar line where the meter starts. */
      at: number;
      beatsPerBar: number;
      beatUnit: number;
    }>
  | Readonly<{
      kind: "fermata";
      at: number;
      /** Extra beats the held beat lasts. */
      beats: number;
    }>;
```

## `TempoCurve`

`ramp()` curves: `linear` adds the same BPM each beat, `exp` the same ratio.

```ts
export type TempoCurve = "linear" | "exp";
```

## `tempo`

Tempo change at beat `at`: `tempo(32, 140)`. Omit `bpm` to pin the tempo
in effect there, the start of a ramp.

```ts
export declare function tempo(at: number, bpm?: number): TimeMark;
```

## `aTempo`

`a tempo` at beat `at` (SDK 1.19.0): step back to the tempo in effect
before the last `rit()`/`accel()` (or ramp) ending before `at`.

```ts
export declare function aTempo(at: number): TimeMark;
```

## `tempoPrimo`

`tempo primo` at beat `at` (SDK 1.19.0): step back to `song({ tempo })`.

```ts
export declare function tempoPrimo(at: number): TimeMark;
```

## `ramp`

Glide from the previous tempo mark (or the song's opening tempo) to `bpm`
at beat `at`: `ramp(64, 90)`. `exp` changes by the same ratio each beat.

```ts
export declare function ramp(
  at: number,
  bpm: number,
  curve?: TempoCurve,
): TimeMark;
```

## `rit`

Ritardando: slow from the tempo at beat `at` to `bpm` over `beats` beats,
`rit(48, 16, 80)`. Same as `[tempo(at), ramp(at + beats, bpm, curve)]`.

```ts
export declare function rit(
  at: number,
  beats: number,
  bpm: number,
  curve?: TempoCurve,
): readonly TimeMark[];
```

## `accel`

Accelerando: like `rit()`, toward a faster `bpm`.

```ts
export declare function accel(
  at: number,
  beats: number,
  bpm: number,
  curve?: TempoCurve,
): readonly TimeMark[];
```

## `fermata`

Fermata: the beat at `at` lasts `beats` extra beats (default 2).

```ts
export declare function fermata(at: number, beats?: number): TimeMark;
```

## `meter`

Meter change on the bar line at beat `at`: `meter(16, [7, 8])` or
`meter(16, 3)` (quarter-note beats). It lasts until the next one.

```ts
export declare function meter(
  at: number,
  value: readonly [number, number] | number,
): TimeMark;
```

## `phasing`

Track time for continuous phasing, the tape drift of Reich's It's Gonna
Rain and Come Out: the track's first `cycle` beats repeat a little fast,
gaining `cycles` whole cycles every `over` beats, so it drifts away from
an identical track and lines up again. `over` should divide the song
loop. `track({ ..., time: phasing(3, 48) })`. For Piano Phase's
shift-and-hold, use `stepPhasing()`.

```ts
export declare function phasing(
  cycle: number,
  over: number,
  cycles?: number,
): TrackTimeInput;
```

## `stepPhasing`

Stepped phasing (SDK 1.19.0), as in Reich's Piano Phase: the track's first `cycle`
beats hold in step with a twin for `hold` cycles, then move `shift`
beats ahead over `drift` cycles, and repeat until a whole cycle ahead.
`track({ ..., time: stepPhasing(3, { hold: 8 }) })`.

```ts
export declare function stepPhasing(
  cycle: number,
  options?: Readonly<{
    shift?: number;
    hold?: number;
    drift?: number;
  }>,
): TrackTimeInput;
```

## `TuningInput`

A tuning for `song({ tuning })` or `track({ tuning })`: a library name or
an object with at most one table source (`edo`, `ratios`, `cents` or
`scl`). Library names: `12-tet`, `19-edo`, `24-edo`, `31-edo`,
`pythagorean`, `just` (5-limit), `7-limit`, `well-tuned-piano`, `pelog`,
`slendro`, `nyamaropa`, `thai`, `shruti`, maqam and dastgah sets (`bayati`,
`rast`, `saba`, `shur`, `homayoun`, `chahargah`) and raga intonations
(`yaman`, `bhairav`, `kafi`, `todi`, …); `dawn` lists them with
`/tuning list`. DAWN checks every value when the song loads.

```ts
export type TuningInput =
  | string
  | Readonly<{
      /** A library tuning, or a label for the table given here. */
      name?: string;
      /** Equal divisions of the octave, 1..128. */
      edo?: number;
      /** Ratios for degrees 1..n, the last the period: `["9/8", "5/4", "2/1"]`. */
      ratios?: readonly (string | number)[];
      /** Cents for degrees 1..n, the last the period: `[240, 480, 720, 960, 1200]`. */
      cents?: readonly number[];
      /** A Scala `.scl` file in the project, e.g. `"tunings/slendro.scl"`. */
      scl?: string;
      /** A Scala `.kbm` keyboard mapping in the project; it sets its own root and A4. */
      kbm?: string;
      /** A4 in Hz, 220..880, default 440. */
      ref?: number;
      /** Key of degree 0, `"D4"` or 62; default the song key's tonic in octave 4. */
      root?: Pitch;
      /** `linear` (default): one key per step. `nearest`: every key plays the step nearest its 12-TET pitch. */
      map?: "linear" | "nearest";
    }>;
```

## `ScoreTuning`

A stored tuning: `root` is a MIDI number, `ratios` are strings.

```ts
export type ScoreTuning = Readonly<{
  name?: string;
  edo?: number;
  ratios?: readonly string[];
  cents?: readonly number[];
  scl?: string;
  kbm?: string;
  ref?: number;
  root?: number;
  map?: "linear" | "nearest";
}>;
```

## `ChordOptions`

Options shared by `chord()` and `progression()`.

```ts
export type ChordOptions = Readonly<{
  /** Voicing dial: each step moves the lowest note up an octave (negative: the highest down), -12..12. */
  voicing?: number;
  /** `close` (default), `open` (drop 2) or `wide` (drop 2 and 4). */
  spread?: "close" | "open" | "wide";
  /** `block` (default), `strum-up`, `strum-down`, `arp-up`, `arp-down`, `arp-updown`, `arp-random`, `harp`, `slop`, `pattern` (SDK 1.7.0). */
  perform?:
    | "block"
    | "strum-up"
    | "strum-down"
    | "arp-up"
    | "arp-down"
    | "arp-updown"
    | "arp-random"
    | "harp"
    | "slop"
    | "pattern"
    | "guitar";
  /**
   * With `perform: "guitar"` (SDK 1.27.0): the stroke grid, a name (`down`
   * `folk` `pop` `punk` `funk` `reggae` `waltz` `jangle` `island`) or
   * characters D (down) U (up) d u (light) x (muted chuck) - . (rest).
   */
  strokes?: string;
  /** Guitar: grid step in beats, default 0.5 (8ths). */
  step?: number;
  /** Guitar: milliseconds a full six-string down stroke takes, default 22. */
  speed?: number;
  /** Guitar: the song tempo `speed` converts with, default 120. */
  tempo?: number;
  /** Guitar: tuning, capo, hand, ring and position (as a track's `guitar`). */
  guitar?: GuitarInput;
  /**
   * With `perform: "pattern"`: a rhythm pattern by name or 1-based number
   * (SDK 1.7.0): `eighths`, `sixteenths`, `offbeat`, `pop`, `charleston`,
   * `bossa`, `skank`, `gallop`, `half-time`, `tresillo`, `oom-pah`, `roll`,
   * `pick`. Default 1.
   */
  pattern?: string | number;
  /** Arpeggio step in beats, default 0.25. */
  rate?: number;
  /** Arpeggio/harp octaves 1..4, default 1. */
  octaves?: number;
  /** Strum gap between voices in beats, default 1/32. */
  strum?: number;
  /** Seed for `arp-random`, default 0. */
  seed?: number;
  /** Velocity, default 0.8. */
  vel?: number;
  /** Lowest root position: the root lands at or above this pitch, default C4. */
  anchor?: Pitch;
  /** `chords` (default), `bass` (root or slash bass in octave 2, one per chord) or `both`. */
  part?: "chords" | "bass" | "both";
  /**
   * Orchid bass mode (SDK 1.7.0; overrides `part`): `off` (chords only),
   * `chords` and `single` (chords plus root or slash bass), `unison`
   * (chords plus the chord's root, ignoring a slash) or `solo` (bass only).
   */
  bass?: "off" | "chords" | "unison" | "single" | "solo";
}>;
```

## `ProgressionOptions`

Options for `progression()`.

```ts
export type ProgressionOptions = ChordOptions &
  Readonly<{
    /** Key the numerals read in: `"C major"`, `"a minor"`, `"F# dorian"`; default C major. */
    key?: string;
    /** Beat of the first chord, default 0. */
    from?: number;
    /** Beats per chord, default 4. */
    each?: number;
    /** Voice-lead each chord to the inversion nearest the previous, default true. */
    lead?: boolean;
  }>;
```

## `chord`

One chord from a symbol (`"Cm7"`, `"F#dim"`, `"Bbmaj9"`, `"G7sus4"`,
`"C/E"`) as notes from `start` for `length` beats.

```ts
notes: [...chord("Am7", 0, 4), ...chord("D9", 4, 4, { perform: "strum-up" })];
```

```ts
export declare function chord(
  symbol: string,
  start?: number,
  length?: number,
  options?: ChordOptions,
): readonly NoteSpec[];
```

## `progression`

A voice-led progression: roman numerals in `key` (`"ii7"`, `"V"`,
`"bVII"`, `"V/V"`) or chord symbols, as an array or a space-separated
string, one chord per `each` beats from `from`. Each chord takes the
inversion nearest the previous one, so common tones hold. Same input,
same notes; DAWN's play mode and agent tools use the same engine.

```ts
notes: progression("ii7 V7 Imaj7 Imaj7", {
  key: "C major",
  perform: "arp-up",
  rate: 0.5,
});
notes: progression(["i", "VI", "III", "VII"], { key: "a minor", part: "bass" });
```

```ts
export declare function progression(
  chords: string | readonly string[],
  options?: ProgressionOptions,
): readonly NoteSpec[];
```

## `GuitarInput`

A track's guitar setup (SDK 1.27.0): see `TrackInput.guitar`.

```ts
export type GuitarInput = Readonly<{
  /** `standard` `dropd` `doubledropd` `dadgad` `openg` `opend` `opene` `halfdown` `nashville` `bass` `ukulele` `requinto`, or open-string pitches low to high. */
  tune?: string | readonly Pitch[];
  /** Capo fret 0..12. */
  capo?: number;
  /** Hand stretch in frets 3..6, default 4. */
  hand?: number;
  /** 0 closed shapes .. 1 ringing open strings, default 0.5. */
  ring?: number;
  /** Preferred fret position 0..12. */
  position?: number;
}>;
```

## `strum`

Strummed guitar chords (SDK 1.27.0): `progression()` with
`perform: "guitar"`. Each chord is fretted on the guitar (`tune`, `capo`,
no barre over an open string) and strummed with a stroke grid; a down
stroke sweeps the strings in `speed` ms. Pair with `guitar` on the track
so DAWN's prompt strums the same shapes.

```ts
notes: strum("G D Em C", { strokes: "folk", speed: 25, tempo: 96 });
notes: strum("i VI III VII", {
  key: "e minor",
  strokes: "D-DU-UDU",
  guitar: { capo: 2 },
});
```

```ts
export declare function strum(
  chords: string | readonly string[],
  options?: Omit<ProgressionOptions, "perform">,
): readonly NoteSpec[];
```

## Supporting type: `GuitarSetup`

This type supports public signatures and is not an SDK export.

How a guitar is set up for voicing chords (`Track.guitar`).

```ts
type GuitarSetup = Readonly<{
  /** A GUITAR_TUNINGS name or open-string pitches low to high. */
  tune?: string | readonly number[];
  /** Capo fret 0..12. */
  capo?: number;
  /** Hand stretch in frets 3..6 (default 4: one fret per finger). */
  hand?: number;
  /** 0 closed shapes (no open strings) .. 1 prefer ringing open strings. */
  ring?: number;
  /** Preferred fret position 0..12 (0 open position). */
  position?: number;
}>;
```
