Skip to content

Time, tuning and harmony

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.

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

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

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

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

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

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

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.

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

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

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

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.

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

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

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

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

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

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

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

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.

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

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

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

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

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

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.

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

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

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

Options shared by chord() and progression().

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

Options for progression().

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

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

notes: [...chord("Am7", 0, 4), ...chord("D9", 4, 4, { perform: "strum-up" })];
export declare function chord(
symbol: string,
start?: number,
length?: number,
options?: ChordOptions,
): readonly NoteSpec[];

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.

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" });
export declare function progression(
chords: string | readonly string[],
options?: ProgressionOptions,
): readonly NoteSpec[];

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

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

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.

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 },
});
export declare function strum(
chords: string | readonly string[],
options?: Omit<ProgressionOptions, "perform">,
): readonly NoteSpec[];

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

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

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

Documentation drafted with AI and checked against the product source.