Skip to content

Composition styles

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.

A style value that must hold (SDK 1.43.0): dawn song fails before composing rather than break it. hard(150) for an exact tempo.

@since 1.43.0

export type Hard<T> = Readonly<{
hard: T;
}>;

A style target (SDK 1.43.0): the composer ranks its choices by distance to it and reports a miss, never fails. weight scales its cost (default 1).

@since 1.43.0

export type Soft<T> = Readonly<{
soft: T;
weight?: number;
}>;

A style field value (SDK 1.43.0): a bare value takes the field’s default kind (DAWN.md lists them), hard() and soft() say it explicitly.

@since 1.43.0

export type Want<T> = T | Hard<T> | Soft<T>;

An inclusive [min, max] (SDK 1.43.0).

@since 1.43.0

export type StyleRange = readonly [min: number, max: number];

Song archetypes (SDK 1.43.0). banger and ballad have their own defaults; the others start from one of them.

@since 1.43.0

export declare const SONG_ARCHETYPES: readonly [
"banger",
"ballad",
"anthem",
"lullaby",
"interlude",
];

One of SONG_ARCHETYPES (SDK 1.43.0).

@since 1.43.0

export type SongArchetype = (typeof SONG_ARCHETYPES)[number];

Drum groove families (SDK 1.43.0).

@since 1.43.0

export declare const GROOVE_FAMILIES: readonly [
"four-floor-pop",
"trance-4x4",
"uk-2step",
"dnb",
"gallop",
"jersey",
"trap-halftime",
"brushed-halftime",
"breakbeat",
"drumless",
];

One of GROOVE_FAMILIES (SDK 1.43.0).

@since 1.43.0

export type GrooveFamily = (typeof GROOVE_FAMILIES)[number];

Lead vocal spaces (SDK 1.43.0): one delay and reverb treatment per song.

@since 1.43.0

export declare const VOCAL_SPACES: readonly [
"slapback",
"pingpong-8th",
"bone-dry",
"room-double",
"dotted-multitap",
"bright-plate",
"reverse-swell",
"quarter-trail",
"gap-bloom",
];

One of VOCAL_SPACES (SDK 1.43.0).

@since 1.43.0

export type VocalSpace = (typeof VOCAL_SPACES)[number];

Song forms (SDK 1.43.0).

@since 1.43.0

export declare const SONG_FORMS: readonly [
"verse-chorus",
"verse-chorus-bridge",
"build-drop",
"through-composed",
"lullaby-arc",
];

One of SONG_FORMS (SDK 1.43.0).

@since 1.43.0

export type SongForm = (typeof SONG_FORMS)[number];

Named energy shapes over a song’s sections (SDK 1.43.0).

@since 1.43.0

export declare const ENERGY_SHAPES: readonly [
"rise",
"build-drop-build",
"arc",
"flat-filter-arc",
];

One of ENERGY_SHAPES (SDK 1.43.0).

@since 1.43.0

export type EnergyShape = (typeof ENERGY_SHAPES)[number];

A song style (SDK 1.43.0): the values dawn song composes from. Every field is optional and lands on the archetype’s defaults; a list for a one-of field (groove, vocal.space, form) is a pool to pick from. dawn song --list prints the palette and trick ids a build knows.

export default defineStyle({
extends: "banger",
tempo: hard(174),
groove: "dnb",
key: "F minor",
vocal: { space: "bone-dry" },
tricks: { require: ["half-bar-stop"], forbid: ["riser-snare-roll"] },
});

@since 1.43.0

export type SongStyleInput = Readonly<{
/** The archetype these values override (default `banger`). */
extends?: SongArchetype | "house-hyperpop";
archetype?: Want<SongArchetype>;
/** BPM: a number (hard by default) or a range to pick in (soft). */
tempo?: Want<number | StyleRange>;
/** Offbeat 16th delay, 0..1 of a 16th's half. */
swing?: Want<number>;
/** "F minor", "Db", "C# minor"; absent: picked by seed. */
key?: Want<string>;
mode?: Want<"major" | "minor">;
modulation?: Want<"none" | "lift-last-chorus">;
groove?: Want<GrooveFamily | readonly GrooveFamily[]>;
drums?: Readonly<{
/** A synth kit name (`syn909`, `syn808`, `acoustic`…). */
kit?: Want<string>;
/** Sidechain pump depth on the bed, dB. */
pump?: Want<StyleRange>;
}>;
/** Palette ids: hard uses exactly these, soft is a pool. */
palette?: Want<readonly string[]>;
harmony?: Readonly<{
/** Share of chords with a 7th or 9th, 0..1. */
extensions?: Want<number>;
/** Chord changes per bar. */
changesPerBar?: Want<StyleRange>;
}>;
/** Lead register targets, MIDI. */
register?: Readonly<{
verseMidi?: Want<StyleRange>;
chorusMedianMidi?: Want<StyleRange>;
p90Max?: Want<number>;
}>;
vocal?: Readonly<{
space?: Want<VocalSpace | readonly VocalSpace[]>;
/** Lyric theme ids (`dawn song --list`). */
themes?: Want<readonly string[]>;
}>;
form?: Want<SongForm | readonly SongForm[]>;
/** Song length in seconds. */
seconds?: Want<StyleRange>;
energy?: Want<EnergyShape>;
density?: Readonly<{
/** Chorus score onsets per second. */
chorus?: Want<StyleRange>;
maxBarsWithoutNew?: Want<number>;
}>;
/** Bars of instrumental peak (a drop). */
instrumentalPeak?: Want<StyleRange>;
tricks?: Readonly<{
require?: readonly string[];
prefer?: readonly string[];
forbid?: readonly string[];
/** Featured tricks per song. */
featured?: Want<StyleRange>;
}>;
mix?: Readonly<{
/** Lead minus band median, dB (K-weighted). */
leadBand?: Want<StyleRange>;
sectionSpread?: Want<number>;
}>;
master?: Readonly<{
lufs?: Want<number>;
tpMax?: Want<number>;
}>;
/** `dawn lint` threshold overrides by group (`{ prosody: { maxSylPerSec: 5 } }`). */
lint?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
}>;

A checked song style (SDK 1.43.0), from defineStyle.

@since 1.43.0

export type SongStyle = SongStyleInput &
Readonly<{
schema: "dawn.style/v1";
}>;

A hard style value (SDK 1.43.0): tempo: hard(150).

@since 1.43.0

export declare function hard<T>(value: T): Hard<T>;

A soft style value (SDK 1.43.0): tempo: soft([140, 150], { weight: 2 }).

@since 1.43.0

export declare function soft<T>(
value: T,
options?: Readonly<{
weight?: number;
}>,
): Soft<T>;

Checks a song style and returns it frozen (SDK 1.43.0). dawn song --spec <style.json> reads the same shape as JSON:

import { defineStyle, hard } from "dawn";
export default defineStyle({
extends: "ballad",
tempo: hard(92),
vocal: { space: "gap-bloom" },
});

Unknown fields and enum values throw DawnSdkError naming the valid ones. Palette, theme and trick ids are checked when dawn song composes.

@since 1.43.0

export declare function defineStyle(input: SongStyleInput): SongStyle;

Documentation drafted with AI and checked against the product source.