Composer plug-ins
For agents
Give your agent this page’s Markdown link, or choose a collection.
- Documentation indexFind a guide and its Markdown link.
- Full documentationRead all curated guides in one text file.
- Machine manifestFind page metadata, Markdown URLs and checksums.
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.
COMPOSER_PLUGIN_PROTOCOL
Section titled “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
export declare const COMPOSER_PLUGIN_PROTOCOL: "dawn.composer-plugin/v1";COMPOSER_SOUND_ROLES
Section titled “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
export declare const COMPOSER_SOUND_ROLES: readonly [ "bass", "bed", "lead", "keys", "texture",];ComposerSoundRole
Section titled “ComposerSoundRole”@since 1.51.0
export type ComposerSoundRole = (typeof COMPOSER_SOUND_ROLES)[number];ComposerSound
Section titled “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
export type ComposerSound = Readonly<{ id: string; title: string; role: ComposerSoundRole; range?: Readonly<{ min: number; max: number; }>; tags?: readonly string[];}>;ComposerSection
Section titled “ComposerSection”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;}>;ComposerBrief
Section titled “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
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
Section titled “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
export type Composition = Readonly<{ song: Song; voices?: Readonly<Record<string, string>>; /** Up to 500 characters. */ summary?: string;}>;ComposerFunction
Section titled “ComposerFunction”@since 1.51.0
export type ComposerFunction = (brief: ComposerBrief) => Composition | Song;composer
Section titled “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.
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;seededRandom
Section titled “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.
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.