Skip to content

Composer plug-ins

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.

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

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

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

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

@since 1.51.0

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

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

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

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

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

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

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

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

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

@since 1.51.0

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

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.

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

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

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.

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

@since 1.51.0

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

Documentation drafted with AI and checked against the product source.