Time, tuning and harmony
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.
TimeMark
Section titled “TimeMark”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; }>;TempoCurve
Section titled “TempoCurve”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;aTempo
Section titled “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.
export declare function aTempo(at: number): TimeMark;tempoPrimo
Section titled “tempoPrimo”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
Section titled “fermata”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;phasing
Section titled “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().
export declare function phasing( cycle: number, over: number, cycles?: number,): TrackTimeInput;stepPhasing
Section titled “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 }) }).
export declare function stepPhasing( cycle: number, options?: Readonly<{ shift?: number; hold?: number; drift?: number; }>,): TrackTimeInput;TuningInput
Section titled “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.
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
Section titled “ScoreTuning”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";}>;ChordOptions
Section titled “ChordOptions”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";}>;ProgressionOptions
Section titled “ProgressionOptions”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[];progression
Section titled “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.
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[];GuitarInput
Section titled “GuitarInput”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[];Supporting type: GuitarSetup
Section titled “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).
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.