Skip to content

Songs and arrangement

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.

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

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

One step of the song form (SDK 1.18.0).

export type SongFormEntry = Readonly<{
section: string;
repeat?: number;
}>;

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

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

A stored automation point: integer tick.

export type ScorePoint = Readonly<{
tick: number;
value: number;
}>;

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

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

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

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

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

The light of a music video world or section (SDK 1.52.0).

@since 1.52.0

export type VideoTime = "dawn" | "day" | "dusk" | "night";

Weather in a music video (SDK 1.52.0).

@since 1.52.0

export type VideoWeather = "clear" | "rain" | "snow" | "mist" | "motes";

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

A camera move (SDK 1.52.0).

@since 1.52.0

export type VideoCamera =
| "follow"
| "profile"
| "orbit"
| "crane"
| "dolly"
| "high"
| "wide"
| "low"
| "overhead"
| "push";

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

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

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

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

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

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

A checked video() record (SDK 1.52.0).

@since 1.52.0

export type VideoSpec = VideoInput &
Readonly<{
schema: "dawn.video/v1";
}>;

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.
*/

The newest song({ calibration }) (mirrors core CALIBRATION_LATEST).

export declare const SONG_CALIBRATION_LATEST = 1;

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

type Timed = Readonly<{
start: number;
length: number;
}>;

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[];

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[];

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;

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.