# Composer plug-ins

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.

## `COMPOSER_PLUGIN_PROTOCOL`

The composer plug-in interface (SDK 1.51.0). A composer plug-in is a
folder with a `dawn.composer.json` manifest and a TypeScript module whose
default export is `composer((brief) => ...)`. `dawn song --composer` (and
the SDK's `dawn-compose`) calls it in the sealed song engine, with no
file, network, process, clock or ambient randomness, validates what it
returns as a score and prints it as an ordinary project. The same brief
always gives the same song.

@since 1.51.0

```ts
export declare const COMPOSER_PLUGIN_PROTOCOL: "dawn.composer-plugin/v1";
```

## `COMPOSER_SOUND_ROLES`

The palette roles a composer can voice a track with: the instrument
roles of `dawn.palette/v1` (drum and effect sounds are not offered).

@since 1.51.0

```ts
export declare const COMPOSER_SOUND_ROLES: readonly [
  "bass",
  "bed",
  "lead",
  "keys",
  "texture",
];
```

## `ComposerSoundRole`

@since 1.51.0

```ts
export type ComposerSoundRole = (typeof COMPOSER_SOUND_ROLES)[number];
```

## `ComposerSound`

A palette sound the brief offers: name a track after it in
`Composition.voices` and DAWN plays the track with that sound's patch.
`range` is its playable MIDI range.

@since 1.51.0

```ts
export type ComposerSound = Readonly<{
  id: string;
  title: string;
  role: ComposerSoundRole;
  range?: Readonly<{
    min: number;
    max: number;
  }>;
  tags?: readonly string[];
}>;
```

## `ComposerSection`

One section the user asked for, in order (`--form "intro:4 verse:8"`). @since 1.51.0

```ts
export type ComposerSection = Readonly<{
  name: string;
  bars: number;
}>;
```

## `ComposerBrief`

What the user asked for. Only `protocol`, `prompt`, `seed` and `sounds`
are always present; every other field is the user's explicit choice and
absent otherwise, so the composer picks its own default.

@since 1.51.0

```ts
export type ComposerBrief = Readonly<{
  protocol: typeof COMPOSER_PLUGIN_PROTOCOL;
  /** The words the user wrote, up to 4,000 characters; may be empty. */
  prompt: string;
  /** 0..4294967295. Derive every choice from it: `seededRandom(brief.seed)`. */
  seed: number;
  /** A key such as `"A minor"` or `"Eb major"`. */
  key?: string;
  /** Beats per minute, 20..300. */
  tempo?: number;
  /** Length in bars, 1..256. */
  bars?: number;
  /** Sections in order; their bars add up to `bars` when both are given. */
  form?: readonly ComposerSection[];
  /** One word or a short phrase, up to 64 characters. */
  mood?: string;
  /** 0 (still) .. 1 (full). */
  energy?: number;
  /** The palette's instrument sounds; empty without `--palette`. */
  sounds: readonly ComposerSound[];
  /** The song to vary (`--vary`), as `song()` returns it. */
  score?: Song;
}>;
```

## `Composition`

What a composer returns: the song, which DAWN validates exactly like a
`song.ts` result, optional palette voices (track id → `ComposerSound.id`)
and a one-line summary DAWN prints.

@since 1.51.0

```ts
export type Composition = Readonly<{
  song: Song;
  voices?: Readonly<Record<string, string>>;
  /** Up to 500 characters. */
  summary?: string;
}>;
```

## `ComposerFunction`

@since 1.51.0

```ts
export type ComposerFunction = (brief: ComposerBrief) => Composition | Song;
```

## `composer`

Declares a composer plug-in: `export default composer((brief) => ...)`.
The function runs synchronously and may return the `song()` alone or a
`Composition`; the wrapper checks the brief's protocol and always hands
DAWN a composition.

```ts
import { composer, seededRandom, song, track, euclid } from "dawn";
export default composer((brief) => {
  const random = seededRandom(brief.seed);
  return song({
    tempo: brief.tempo ?? 120,
    bars: brief.bars ?? 4,
    tracks: [
      track({
        name: "Drums",
        instrument: "kit",
        rhythm: [euclid("kick", 3 + Math.floor(random() * 3), 16)],
      }),
    ],
  });
});
```

@since 1.51.0

```ts
export declare function composer(
  compose: ComposerFunction,
): (brief: ComposerBrief) => Composition;
```

## `seededRandom`

A deterministic random source in [0, 1) from a 32-bit seed (mulberry32):
the same seed gives the same sequence on every machine. Song and composer
source have no `Math.random`; use this instead.

```ts
const random = seededRandom(brief.seed);
const pulses = 3 + Math.floor(random() * 4);
```

@since 1.51.0

```ts
export declare function seededRandom(seed: number): () => number;
```
