# Songs and arrangement

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.

## `SongInput`

Input to `song()`.

```ts
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`

A song section (SDK 1.18.0); bars are 0-based like beats.

```ts
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`

One step of the song form (SDK 1.18.0).

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

## `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.

```ts
master: { glue: { ratio: 2 }, limiter: { ceiling: -1 }, target: -14 }
```

```ts
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`

A stored note: integer ticks; expression fields only when set.

```ts
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`

A stored automation point: integer tick.

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

## `ScoreSampleRef`

A stored sample reference (project-relative `src`, MIDI `root`).

```ts
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`

A stored track; optional fields are present only when set.

```ts
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"];
}>;
```

## `Song`

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.

```ts
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`

A song's style provenance (SDK 1.33.0); see `style()`.

```ts
export type StyleSpec = Readonly<{
  id: string;
  seed: number;
  bars: number;
  blend?: Readonly<{
    id: string;
    weight: number;
  }>;
}>;
```

## `StyleOptions`

```ts
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];
}>;
```

## `style`

Which style and seed made a song (SDK 1.33.0), for `song({ style })`:

```ts
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.

```ts
export declare function style(id: string, options?: StyleOptions): StyleSpec;
```

## `ScoreTime`

A stored song `time`: ticks, and 0-based bar indexes.

```ts
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`

How a section of the music video plays (SDK 1.52.0).

@since 1.52.0

```ts
export type VideoPlay =
  | "run"
  | "build"
  | "glide"
  | "dance"
  | "roam"
  | "setpiece"
  | "chase"
  | "climb"
  | "ride";
```

## `VideoTime`

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

@since 1.52.0

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

## `VideoWeather`

Weather in a music video (SDK 1.52.0).

@since 1.52.0

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

## `VideoGround`

What the ground of a music video world is (SDK 1.52.0).

@since 1.52.0

```ts
export type VideoGround =
  "plain" | "hills" | "dunes" | "water" | "floor" | "clouds" | "seabed";
```

## `VideoCamera`

A camera move (SDK 1.52.0).

@since 1.52.0

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

## `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

```ts
export type VideoMoney = "fold" | "swarm" | "title" | "rise" | "reveal";
```

## `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

```ts
export type VideoMoment =
  "flip" | "whale" | "stairs" | "letters" | "lanterns" | "bloom" | "meteors";
```

## `VideoSectionInput`

One section's set in `video({ sections })` (SDK 1.52.0).

@since 1.52.0

```ts
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`

Who plays whom (SDK 1.52.0): catalog ids or tags; `dance` a motion id.

@since 1.52.0

```ts
export type VideoCastInput = Readonly<{
  hero?: string;
  companion?: string;
  crowd?: string;
  giant?: string;
  flock?: string;
  dance?: string;
}>;
```

## `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

```ts
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`

`video({...})` (SDK 1.52.0): the song's music video, authored. Every
field is optional and overrides what the video derives from the lyrics:

```ts
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

```ts
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`

A checked `video()` record (SDK 1.52.0).

@since 1.52.0

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

## `VIDEO_MAX_BYTES`

Largest `video()` record, in bytes of JSON (SDK 1.52.0).

@since 1.52.0

```ts
export declare const VIDEO_MAX_BYTES = 4096;
```

## `video`

Checks and freezes a song's music video (SDK 1.52.0); see `VideoInput`.

@since 1.52.0

```ts
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`

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

```ts
export declare const SONG_CALIBRATION_LATEST = 1;
```

## Supporting type: `Timed`

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

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

## Supporting type: `RangeHelperOptions`

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

```ts
type RangeHelperOptions = Readonly<{
  beatsPerBar?: number;
}>;
```

## `bars`

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

```ts
export declare function bars<T extends Timed>(
  notes: readonly T[],
  from: number,
  to?: number,
  options?: RangeHelperOptions,
): readonly T[];
```

## `place`

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

```ts
export declare function place<T extends Timed>(
  notes: readonly T[],
  options: Readonly<{
    at: number;
    times?: number;
    bars?: number;
  }> &
    RangeHelperOptions,
): readonly T[];
```

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

```ts
export declare function reversed<T extends Timed>(
  notes: readonly T[],
  options: Readonly<{
    bars: number;
  }> &
    RangeHelperOptions,
): readonly T[];
```

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

```ts
export declare function insertBars(
  input: Song,
  options: Readonly<{
    at: number;
    bars: number;
  }>,
): Song;
```

## `song`

```ts
export declare function song(input: SongInput): Song;
```

## `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

```ts
export declare function noteIdFor(
  trackId: string,
  pitch: number,
  startTick: number,
  durationTicks: number,
  velocity: number,
  taken: ReadonlySet<string>,
): string;
```
