# Composition styles

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.

## `Hard`

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

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

## `Soft`

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

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

## `Want`

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

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

## `StyleRange`

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

@since 1.43.0

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

## `SONG_ARCHETYPES`

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

@since 1.43.0

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

## `SongArchetype`

One of `SONG_ARCHETYPES` (SDK 1.43.0).

@since 1.43.0

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

## `GROOVE_FAMILIES`

Drum groove families (SDK 1.43.0).

@since 1.43.0

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

## `GrooveFamily`

One of `GROOVE_FAMILIES` (SDK 1.43.0).

@since 1.43.0

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

## `VOCAL_SPACES`

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

@since 1.43.0

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

## `VocalSpace`

One of `VOCAL_SPACES` (SDK 1.43.0).

@since 1.43.0

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

## `SONG_FORMS`

Song forms (SDK 1.43.0).

@since 1.43.0

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

## `SongForm`

One of `SONG_FORMS` (SDK 1.43.0).

@since 1.43.0

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

## `ENERGY_SHAPES`

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

@since 1.43.0

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

## `EnergyShape`

One of `ENERGY_SHAPES` (SDK 1.43.0).

@since 1.43.0

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

## `SongStyleInput`

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.

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

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

## `SongStyle`

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

@since 1.43.0

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

## `hard`

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

@since 1.43.0

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

## `soft`

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

@since 1.43.0

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

## `defineStyle`

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

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

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