Songs and arrangement
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.
SongInput
Section titled “SongInput”Input to song().
export type SongInput = Readonly<{ /** BPM 20..300, default 120. */ tempo?: number; /** * `[beatsPerBar, noteValue]` or just `beatsPerBar`; default `[4, 4]`. * A note value other than 4 is stored as a meter change at bar 1, so * `[6, 8]` is six eighths (three quarter-note beats) per bar. */ meter?: readonly [number, number] | number; /** Loop length in bars, 1..256, default 4. */ bars?: number; /** * Free text such as `"A minor"`, or null. A scale name after the tonic * picks a scale: `"D dorian"`, `"E hijaz"`, `"C yaman"`, `"C messiaen-3"`. */ key?: string | null; /** * Song tuning (SDK 1.16.0), default 12-TET at A4 = 440 Hz: a library name * (`"19-edo"`, `"just"`, `"pelog"`, `"yaman"`) or `{ edo, ratios, cents, * scl, kbm, ref, root, map }`. See `TuningInput`. */ tuning?: TuningInput | null; /** Integer ticks per beat, default 480. Leave it alone unless you know why. */ ticksPerBeat?: number; /** * Tempo changes, meter changes and fermatas (SDK 1.14.0), in any order: * `tempo()`, `ramp()`, `rit()`, `accel()`, `fermata()` and `meter()`. * `tempo` above stays the opening tempo and `meter` the opening meter. * `rit()` and `accel()` return two marks; list them as they come. */ time?: readonly (TimeMark | readonly TimeMark[])[]; /** Tracks in score order; each from `track()`. */ tracks: readonly TrackSpec[]; /** Master chain and loudness target after every track and orbit bus (SDK 1.17.0); omit for none. */ master?: MasterInput; /** * Which style and seed made the song (SDK 1.33.0), from `style()`: * `style: style("deep-house", { seed: 3, bars: 8 })`. A record only: the * notes are the tracks above; `/style` in DAWN generates them. */ style?: StyleSpec; /** * The song's music video (SDK 1.52.0), from `video()`: the places, cast, * props and money shot the derived video would otherwise choose. A * record only: it changes no sound; `dawn render x.score.json` checks * it against the video catalog and writes it into the score. */ video?: VideoSpec; /** * Named bar ranges (SDK 1.18.0): `{ name: "chorus", startBar: 8, bars: 8 }`, * optionally with `mute: ["pad"]` and `vary: { lead: { transpose: 12 } }`. */ sections?: readonly SongSection[]; /** * The order sections play, with repeats (SDK 1.18.0): `"intro verse * chorus*2 outro"`, or `["intro", { section: "chorus", repeat: 2 }]`. * Absent plays the bars straight through. */ form?: string | readonly (string | SongFormEntry)[]; /** The section playback loops (SDK 1.18.0); `loop: "chorus"` says the same. */ loopSection?: string; /** * What playback loops (SDK 1.34.0): bars `"5-6"` (1-based, as the prompt * shows them) or a section `"chorus"`. Export ignores it. */ loop?: string; /** * Sound calibration (SDK 1.32.0): `1` renders the 0.7 level, pitch and * drum-kit fixes (hat choke, tuned toms, crash and ride, level keys, * steady brass). Omit it to keep an older song's sound byte-identical; * `dawn init` writes the latest. */ calibration?: number; /** * The project patch library (SDK 1.35.0): patches tracks play by name * with `patch({ ref: "acid-bass", macros: { cutoff: 900 } })`. */ patches?: readonly PatchSpec[];}>;SongSection
Section titled “SongSection”A song section (SDK 1.18.0); bars are 0-based like beats.
export type SongSection = Readonly<{ /** `intro`, `verse`, `chorus 2`, `A`: 1..32 characters, unique ignoring case. */ name: string; /** First bar, 0-based. */ startBar: number; /** Length in bars, at least 1. */ bars: number; /** Track ids silent in this section. */ mute?: readonly string[]; /** Per-track changes in this section: semitones and a velocity multiplier. */ vary?: Readonly< Record< string, Readonly<{ transpose?: number; gain?: number; }> > >;}>;SongFormEntry
Section titled “SongFormEntry”One step of the song form (SDK 1.18.0).
export type SongFormEntry = Readonly<{ section: string; repeat?: number;}>;MasterInput
Section titled “MasterInput”The song master (SDK 1.17.0), processed in the fixed order
trim → eq → tone → mseq → glue → multiband → tape → width → clip →
limiter after the tracks and orbit buses are
summed. Each unit present is on; {} takes every default. target is
an integrated loudness in LUFS (ITU-R BS.1770-4), -40..-3: renders drive
the limiter (or, without one, a clean gain) to reach it. Streaming is
-14, club -8, loud hyperpop or gabber -6, classical -20, broadcast -23.
The SDK takes LUFS numbers only: a target name such as master target club in the prompt also sets a limiter preset, so write that unit out.
DAWN.md “Master and loudness” lists every parameter with its range.
master: { glue: { ratio: 2 }, limiter: { ceiling: -1 }, target: -14 }export type MasterInput = Readonly<{ /** Gain staging first: `lufs`, the raw mix's loudness before eq, glue and tape (SDK 1.41.0); `monitor`, `dcblock` (SDK 1.46.0). */ trim?: EffectParams; /** `low`/`high` shelves and `bell1`/`bell2` gains in dB, with `…freq` and `…q`. */ eq?: EffectParams; /** Octave graphic EQ: `b31` `b63` `b125` `b250` `b500` `b1k` `b2k` `b4k` `b8k` `b16k`, each a gain in dB at that centre (SDK 1.46.0). */ tone?: EffectParams; /** Mid/side EQ: a low shelf, bell and high shelf on each of mid and side (`midlow`, `sidebell`, `sidehighfreq`, …) (SDK 1.46.0). */ mseq?: EffectParams; /** Bus compressor: threshold, ratio, attack, release (ms), knee, makeup, mix, hpf. */ glue?: EffectParams; /** Four-band compressor: `lowfreq` `midfreq` `highfreq` crossovers; threshold, ratio, attack, release and gain per band (`lowthreshold`, `airgain`, …); `knee`, `range` (SDK 1.46.0). */ multiband?: EffectParams; /** Saturation: drive (dB), bias, tone (Hz), mix. */ tape?: EffectParams; /** Stereo width 0..2 (1 unchanged) and `mono` bass below this many Hz. */ width?: EffectParams; /** Soft clipper before the limiter: drive (dB), ceiling (dBFS), softness 0..1 (SDK 1.41.0); `oversample`, `target` (SDK 1.46.0). */ clip?: EffectParams; /** True-peak limiter: ceiling (dBTP), gain, release, lookahead (ms), truepeak; `dcblock` removes offset after limiting (off by default, SDK 1.47.0). */ limiter?: EffectParams; /** Integrated loudness target in LUFS (a negative number, -40..-3). */ target?: number;}>;ScoreNote
Section titled “ScoreNote”A stored note: integer ticks; expression fields only when set.
export type ScoreNote = Readonly<{ id: string; trackId: string; startTick: number; durationTicks: number; pitch: number; velocity: number; articulation?: Articulation; glide?: number; bend?: readonly Readonly<{ at: number; cents: number; }>[]; vibrato?: Readonly<{ rate: number; depth: number; delay?: number; }>; humanize?: Readonly<{ timing?: number; velocity?: number; length?: number; }>; /** Autotune guide drift share (SDK 1.32.0). */ drift?: number; /** Static cents offset (SDK 1.16.0); absent is 0. */ cents?: number; /** Sung vowel (SDK 1.32.0); absent sings the lyric's or the track's. */ vowel?: string; /** The sung syllable (SDK 1.32.0); a trailing `-` continues the word. */ lyric?: string; /** Machine vox voicing (SDK 1.36.0). */ vox?: NoteVoxSpec;}>;ScorePoint
Section titled “ScorePoint”A stored automation point: integer tick.
export type ScorePoint = Readonly<{ tick: number; value: number;}>;ScoreSampleRef
Section titled “ScoreSampleRef”A stored sample reference (project-relative src, MIDI root).
export type ScoreSampleRef = Readonly<{ src: string; sha256?: string; url?: string; license?: string; root?: number; begin?: number; end?: number; gain?: number; speed?: number; loop?: boolean; choke?: string; loopBegin?: number; loopEnd?: number; clip?: number; unit?: "r" | "c" | "s"; fit?: boolean; accelerate?: number; squiz?: number; bpm?: number; fitmode?: "repitch" | "beats" | "tones"; len?: number; shift?: number; formant?: number; fadeTime?: number; fadeInTime?: number; from?: SampleProvenanceSpec;}>;ScoreTrack
Section titled “ScoreTrack”A stored track; optional fields are present only when set.
export type ScoreTrack = Readonly<{ id: string; name: string; instrument: string; muted: boolean; volume: number; pan: number; volumeAutomation: readonly ScorePoint[]; panAutomation: readonly ScorePoint[]; solo?: boolean; filter?: TrackSpec["filter"] & object; delay?: TrackSpec["delay"] & object; filterAutomation?: readonly ScorePoint[]; resonanceAutomation?: readonly ScorePoint[]; delayFeedbackAutomation?: readonly ScorePoint[]; delayMixAutomation?: readonly ScorePoint[]; reverb?: TrackSpec["reverb"] & object; fx?: FxInput; fxAutomation?: Readonly<Record<string, readonly ScorePoint[]>>; synth?: SynthInput; keys?: KeysInput; sampler?: Readonly<{ voices: Readonly<Record<string, ScoreSampleRef>>; mode: "oneshot" | "keyed"; }>; /** Rhythm rows without `kind`; DAWN validates and expands them. */ rhythm?: readonly Readonly<Record<string, unknown>>[]; /** Synth kit name; DAWN validates it. */ kit?: string; /** `rate`, plus `phase` and `cycle` in ticks. */ time?: Readonly<{ rate?: number; phase?: number; cycle?: number; steps?: Readonly<{ shift: number; hold: number; drift: number; }>; }>; /** Track tuning; DAWN validates it (SDK 1.16.0). */ tuning?: ScoreTuning; wavetable?: Readonly< { table: ScoreSampleRef; } & WavetableParams >; wtAutomation?: readonly ScorePoint[]; /** String engine settings; DAWN validates them (SDK 1.21.0). */ string?: StringInput; /** Granular settings (SDK 1.23.0); present only when set. */ granular?: GranularInput; /** Modal settings (SDK 1.25.0). */ modal?: TrackSpec["modal"]; /** Texture settings (SDK 1.45.0). */ texture?: TrackSpec["texture"]; /** Guitar fretting (SDK 1.27.0). */ guitar?: GuitarSetup; /** Wind settings (SDK 1.30.0). */ wind?: TrackSpec["wind"]; /** Sing settings (SDK 1.32.0). */ sing?: TrackSpec["sing"]; /** Vocoder settings (SDK 1.32.0); `src` is a track id. */ vocoder?: TrackSpec["vocoder"]; /** Pitch correction (SDK 1.32.0). */ autotune?: AutotuneSettings; /** Machine vox (SDK 1.36.0). */ vox?: TrackVoxSpec; glide?: TrackSpec["glide"]; pedal?: readonly Readonly<{ tick: number; state: PedalState; }>[]; softPedal?: readonly Readonly<{ tick: number; state: PedalState; }>[]; sostenuto?: readonly Readonly<{ tick: number; state: PedalState; }>[]; velocityCurve?: TrackSpec["velocityCurve"]; humanize?: TrackSpec["humanize"];}>;What song() returns and song.ts default-exports: a track.loop/v1
document in integer ticks, ready for DAWN to validate and diff against
the session.
export type Song = Readonly<{ format: "track.loop/v1"; version: 1; tempoBpm: number; beatsPerBar: number; bars: number; ticksPerBeat: number; key: string | null; /** Present only when `song({ time })` has marks. */ time?: ScoreTime; /** Present only when the song sets one (SDK 1.16.0). */ tuning?: ScoreTuning; tracks: readonly ScoreTrack[]; notes: readonly ScoreNote[]; master?: MasterInput; /** Present only when the song names a style (SDK 1.33.0). */ style?: StyleSpec; /** Present only when the song authors its music video (SDK 1.52.0). */ video?: VideoSpec; /** Present only when the song has sections (SDK 1.18.0). */ sections?: readonly SongSection[]; /** Present only when the song has a form (SDK 1.18.0). */ form?: readonly SongFormEntry[]; /** Present only when a section loops (SDK 1.18.0). */ loopSection?: string; /** Present only when bars loop (SDK 1.34.0): 0-based `startBar`. */ loop?: Readonly<{ startBar: number; bars: number; }>; /** Present only when the song sets one (SDK 1.32.0). */ calibration?: number; /** Present only when the song has a patch library (SDK 1.35.0), by name. */ patches?: Readonly<Record<string, PatchSpec>>;}>;StyleSpec
Section titled “StyleSpec”A song’s style provenance (SDK 1.33.0); see style().
export type StyleSpec = Readonly<{ id: string; seed: number; bars: number; blend?: Readonly<{ id: string; weight: number; }>;}>;StyleOptions
Section titled “StyleOptions”export type StyleOptions = Readonly<{ /** Generator seed, integer 0..2147483647, default 1. */ seed?: number; /** Bars generated, 1..256, default 8. */ bars?: number; /** Blend partner and its weight 0..1: `blend: ["bebop", 0.3]`. */ blend?: readonly [string, number];}>;Which style and seed made a song (SDK 1.33.0), for song({ style }):
style("deep-house", { seed: 3, bars: 8 });style("bebop", { seed: 7, blend: ["bossa-nova", 0.3] });The id is a taxonomy id (dawn lists them with /style list). It is a
record of where the song came from; the notes live in the tracks.
export declare function style(id: string, options?: StyleOptions): StyleSpec;ScoreTime
Section titled “ScoreTime”A stored song time: ticks, and 0-based bar indexes.
export type ScoreTime = Readonly<{ tempo?: readonly Readonly<{ tick: number; bpm: number; ramp?: "linear" | "exp"; }>[]; meter?: readonly Readonly<{ bar: number; beatsPerBar: number; beatUnit?: number; }>[]; fermatas?: readonly Readonly<{ tick: number; beats: number; }>[];}>;VideoPlay
Section titled “VideoPlay”How a section of the music video plays (SDK 1.52.0).
@since 1.52.0
export type VideoPlay = | "run" | "build" | "glide" | "dance" | "roam" | "setpiece" | "chase" | "climb" | "ride";VideoTime
Section titled “VideoTime”The light of a music video world or section (SDK 1.52.0).
@since 1.52.0
export type VideoTime = "dawn" | "day" | "dusk" | "night";VideoWeather
Section titled “VideoWeather”Weather in a music video (SDK 1.52.0).
@since 1.52.0
export type VideoWeather = "clear" | "rain" | "snow" | "mist" | "motes";VideoGround
Section titled “VideoGround”What the ground of a music video world is (SDK 1.52.0).
@since 1.52.0
export type VideoGround = "plain" | "hills" | "dunes" | "water" | "floor" | "clouds" | "seabed";VideoCamera
Section titled “VideoCamera”A camera move (SDK 1.52.0).
@since 1.52.0
export type VideoCamera = | "follow" | "profile" | "orbit" | "crane" | "dolly" | "high" | "wide" | "low" | "overhead" | "push";VideoMoney
Section titled “VideoMoney”The one money shot a song gets at its biggest hook (SDK 1.52.0): fold
curls the road up like a page, swarm fills the sky with the motif,
title has the crowd stand as the title’s letters, rise lifts the
motif out of the ground into the sky, reveal pulls the camera back
over the whole road with a light at every place the song went.
@since 1.52.0
export type VideoMoney = "fold" | "swarm" | "title" | "rise" | "reveal";VideoMoment
Section titled “VideoMoment”A surprise a song plays besides its money shot (SDK 1.53.0): flip
rolls the world over, whale swims a whale across the sky (or through
the room), stairs builds a stair of light that plays the melody,
letters drops the sung words onto the road as steps, lanterns lets
lanterns go from the verges, bloom bursts the verges into flower and
meteors sends one across the night on each hit. Left out, a song gets
two or three from its words (a lamp brings lanterns, the sea a whale)
and its sections.
@since 1.53.0
export type VideoMoment = "flip" | "whale" | "stairs" | "letters" | "lanterns" | "bloom" | "meteors";VideoSectionInput
Section titled “VideoSectionInput”One section’s set in video({ sections }) (SDK 1.52.0).
@since 1.52.0
export type VideoSectionInput = Readonly<{ /** A place: `city`, `forest`, `kitchen`, `clouds`… (`dawn video places`). */ place?: string; play?: VideoPlay; time?: VideoTime; weather?: VideoWeather; /** A palette name (`dawn video places` lists them). */ palette?: string; camera?: VideoCamera; ground?: VideoGround; /** Catalog ids or tags added to the place's own kit as scenery. */ props?: readonly string[];}>;VideoCastInput
Section titled “VideoCastInput”Who plays whom (SDK 1.52.0): catalog ids or tags; dance a motion id.
@since 1.52.0
export type VideoCastInput = Readonly<{ hero?: string; companion?: string; crowd?: string; giant?: string; flock?: string; dance?: string;}>;VideoArchiveInput
Section titled “VideoArchiveInput”An archive.org item the video uses (SDK 1.52.0), as dawn video archive get records it: Prelinger footage on a screen, billboard or the sky in
the named sections, or a 78rpm music interlude after the song
(at: "end"). Identifier, title, date and licence are required.
@since 1.52.0
export type VideoArchiveInput = Readonly<{ kind: "footage" | "music"; id: string; url: string; title: string; date: string; licence: string; sections?: readonly string[]; as?: "screen" | "billboard" | "sky"; from?: number; at?: "end";}>;VideoInput
Section titled “VideoInput”video({...}) (SDK 1.52.0): the song’s music video, authored. Every
field is optional and overrides what the video derives from the lyrics:
video({ time: "dusk", motif: "lantern", money: "swarm", cast: { hero: "dawn.figure.robe", companion: "dawn.figure.paper" }, sections: { verse: { place: "kitchen" }, chorus: { place: "clouds", play: "glide" }, }, props: { cup: "kaykit.adventures.mug-full", rain: "weather:rain" },});sections keys are section names (chorus is every playing of it,
chorus 2 one playing). props maps a sung word to a catalog id or tag,
or to a cue: weather:, time:, palette:, camera:, move: or
world:. Names are checked against the catalog when the score is
rendered (dawn video catalog search <words> finds them).
@since 1.52.0
export type VideoInput = Readonly<{ palette?: string; time?: VideoTime; weather?: VideoWeather; ground?: VideoGround; /** 0..1: how thick the air is. */ fog?: number; /** Re-rolls the layout, a whole number. */ seed?: number; /** The thing the song keeps singing: a catalog id or tag. */ motif?: string; /** The money shot's kind, and optionally its section. */ money?: | VideoMoney | Readonly<{ kind: VideoMoney; section?: string; }>; /** The words a `title` money shot spells, at most 40 characters. */ title?: string; /** * The song's surprises, at most 6: each a kind in a section (by name; * a name played twice means its first playing), optionally `bar` bars * in. These replace the derived ones. * * @since 1.53.0 */ moments?: readonly Readonly<{ kind: VideoMoment; section: string; bar?: number; }>[]; cast?: VideoCastInput; sections?: Readonly<Record<string, VideoSectionInput>>; props?: Readonly<Record<string, string>>; archive?: readonly VideoArchiveInput[];}>;VideoSpec
Section titled “VideoSpec”A checked video() record (SDK 1.52.0).
@since 1.52.0
export type VideoSpec = VideoInput & Readonly<{ schema: "dawn.video/v1"; }>;VIDEO_MAX_BYTES
Section titled “VIDEO_MAX_BYTES”Largest video() record, in bytes of JSON (SDK 1.52.0).
@since 1.52.0
export declare const VIDEO_MAX_BYTES = 4096;Checks and freezes a song’s music video (SDK 1.52.0); see VideoInput.
@since 1.52.0
export declare function video(input: VideoInput): VideoSpec;/** * Assemble the song. Beats become ticks (`Math.round(beat * ticksPerBeat)`, * lengths at least one tick), and every note gets a deterministic id from * its track and content, so two evaluations of the same files agree. */SONG_CALIBRATION_LATEST
Section titled “SONG_CALIBRATION_LATEST”The newest song({ calibration }) (mirrors core CALIBRATION_LATEST).
export declare const SONG_CALIBRATION_LATEST = 1;Supporting type: Timed
Section titled “Supporting type: Timed”This type supports public signatures and is not an SDK export.
type Timed = Readonly<{ start: number; length: number;}>;Supporting type: RangeHelperOptions
Section titled “Supporting type: RangeHelperOptions”This type supports public signatures and is not an SDK export.
type RangeHelperOptions = Readonly<{ beatsPerBar?: number;}>;The notes (or hits) that start in bars from..to, re-based to beat 0
and cut at the range’s end: bars(chorus, 5, 6).
export declare function bars<T extends Timed>( notes: readonly T[], from: number, to?: number, options?: RangeHelperOptions,): readonly T[];Notes laid down at bar at, repeated times times end to end:
place(bars(bass, 5, 6), { at: 7, times: 2 }). Each repeat spans
bars bars (default: the whole bars the notes reach).
export declare function place<T extends Timed>( notes: readonly T[], options: Readonly<{ at: number; times?: number; bars?: number; }> & RangeHelperOptions,): readonly T[];reversed
Section titled “reversed”The notes mirrored in time over bars bars from beat 0 (a note ending
at the span’s end starts at 0): reversed(bars(lead, 5, 6), { bars: 2 }).
export declare function reversed<T extends Timed>( notes: readonly T[], options: Readonly<{ bars: number; }> & RangeHelperOptions,): readonly T[];insertBars
Section titled “insertBars”bars empty bars inserted before bar at of a song() result: later
notes, sections, the loop, tempo marks, fermatas, automation points and
clips move right; a note held across at sounds on through the gap.
export default insertBars(song({...}), { at: 7, bars: 2 }).
export declare function insertBars( input: Song, options: Readonly<{ at: number; bars: number; }>,): Song;export declare function song(input: SongInput): Song;noteIdFor
Section titled “noteIdFor”The id song() gives a note that has none (SDK 1.50.0): a hash of its
track, pitch, start and length in ticks and velocity, skipping ids already
taken on that track by the notes before it. The printer writes a note’s
id only when it is not this.
@since 1.50.0
export declare function noteIdFor( trackId: string, pitch: number, startTick: number, durationTicks: number, velocity: number, taken: ReadonlySet<string>,): string;Documentation drafted with AI and checked against the product source.