Skip to content

Write a composer plug-in

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

A composer plug-in turns a brief (a prompt, a seed, and the key, tempo, length, form, mood, energy and sounds the user asked for) into a song. DAWN runs it in the same sealed engine as song source, checks what it returns like any song.ts, and writes an ordinary project the user can edit, render and share. A composer is data-safe by construction: it cannot read or write a file, reach the network, start a process or read the clock, and the same brief always gives the same song.

dawn song without --composer, or with --composer dawn, still runs DAWN’s own composer. Plug-ins are part of dawn and of the public, MIT-licensed DAWN SDK, which runs them as dawn-compose.

The SDK includes Euclid Pulse, a small composer in examples/composers/euclid-pulse/: Euclidean drums, a seeded four-chord loop, a root bass and a pentatonic top line.

Terminal window
dawn song night --composer examples/composers/euclid-pulse --prompt "a dark rainy groove" --seed 7 --bars 8
composed with euclid-pulse 1.0.0 (examples/composers/euclid-pulse, sha256 fd3821c905b0) · seed 7 · 4 tracks · 8 bars · 113 BPM C minor · 76 ms
i VII VI VII in C minor · 113 BPM · 8 bars · kick E(3,16) · hat E(8,16)
wrote night (song.ts, tracks/, composer.json)

night/ is a DAWN project: song.ts, one tracks/<name>/track.ts per part, and composer.json, which records the composer’s ID, version and the SHA-256 of the files that ran, and the brief. Edit it like any song, then dawn check and dawn render night.wav from the folder.

With the SDK alone, the same command is dawn-compose, and dawn-render renders what it writes:

Terminal window
bunx dawn-compose night --composer node_modules/@hraness/dawn-sdk/examples/composers/euclid-pulse --seed 7
bunx dawn-render night/song.ts --out night.wav

dawn-compose writes song.ts, tracks/ and composer.json without DAWN’s project files (dawn.json, the vendored SDK).

A composer is a folder with a manifest and at least one module:

my-composer/
dawn.composer.json
composer.ts
loops.ts any other .ts, .js or .json modules it imports
tsconfig.json optional: maps "dawn" to the SDK for your editor

dawn.composer.json:

{
"schema": "dawn.composer-plugin/v1",
"id": "my-composer",
"version": "1.0.0",
"title": "My composer",
"author": "Your name",
"license": "MIT",
"entry": "composer.ts",
"description": "What it writes, in a sentence."
}

id is a lowercase slug of up to 64 characters, version is major.minor.patch, and entry is a .ts or .js module inside the folder. description is optional. Unknown fields are refused. Put your own name and a license you can grant on the manifest.

The entry’s default export is composer() from dawn, called with the brief:

import { composer, euclid, progression, seededRandom, song, track } from "dawn";
export default composer((brief) => {
const random = seededRandom(brief.seed);
const key = brief.key ?? (random() < 0.5 ? "A minor" : "C major");
const bars = brief.bars ?? 8;
return {
song: song({
tempo: brief.tempo ?? 110,
key,
bars,
tracks: [
track({
name: "Drums",
instrument: "kit",
rhythm: [euclid("kick", 3 + Math.floor(random() * 3), 16)],
}),
track({
name: "Keys",
instrument: "piano",
notes: progression("i VI III VII", { key }),
}),
],
}),
summary: `${key} · ${bars} bars`,
};
});

Use every SDK builder: song, track, note, seq, progression, chord, euclid, grid, patches and effects. There is no Math.random; seededRandom(seed) is a deterministic generator that gives the same sequence on every machine. The function runs synchronously; a composer that returns a promise is refused.

For type checking in your editor, copy tsconfig.json from the example and point its paths entry for dawn at the SDK’s core/sdk/v1.ts. DAWN itself reads no tsconfig.json: dawn always resolves to the SDK the running DAWN ships.

Field Type Present
protocol "dawn.composer-plugin/v1" always
prompt string, up to 4,000 chars always; empty without --prompt
seed 0..4294967295 always; random when --seed is left out, and recorded in composer.json
key for example "A minor" with --key
tempo 20..300 BPM with --tempo
bars 1..256 with --bars
form [{ name, bars }] with --form "intro:4 verse:8 chorus:8"; with --bars, the bars must add up to it
mood up to 64 characters with --mood
energy 0..1 with --energy
sounds [{ id, title, role, range?, tags? }] always; the palette’s instrument sounds with --palette, otherwise empty
score a song as song() returns it with --vary: the project’s current song

A field the user did not set is absent, so the composer chooses its own default. The types are ComposerBrief, ComposerSound and ComposerSection in the SDK.

A Composition: { song, voices?, summary? }, or the song() alone.

  • song is validated exactly like the result of a song.ts: the same score format, the same limits (SCORE_LIMITS) and the same messages. An invalid score is refused with the reason.
  • The song names no file. Samples, wavetables, clips, impulse responses and granular sources must be builtin: sources or one of the bundled studio sounds; a tuning is written inline, not as a .scl or .kbm file; and a patch runs no WebAssembly device. A composer ships no audio and needs nothing beside the song.
  • voices maps a track ID to the ID of a sound the brief offered. DAWN replaces that track’s instrument with the sound’s patch, so the user’s palette plays the part, and copies any device the sound runs into the song’s devices/ folder. A voice must name a track of the song and an offered sound, and cannot voice a kit track. Drum and effect sounds are not offered in this version.
  • summary is up to 500 characters with no control or bidirectional-override characters; DAWN prints it and keeps it in composer.json. A composer’s error messages are printed with such characters escaped.

Anything else, more than 8 MiB of JSON, or unknown top-level fields are refused.

A composer runs in the sealed song engine: QuickJS compiled to WebAssembly.

  • No authority. The global object holds the standard JavaScript built-ins only. There is no process, Bun, require, fetch, console, timer, performance or WebAssembly, and Date and Math.random throw.
  • No file system. DAWN reads the composer’s .ts, .mts, .js, .mjs and .json files into memory before it runs; hidden files, node_modules and links are not read. The engine resolves imports against those files only: dawn (the SDK this DAWN ships) and relative paths inside the folder. node:*, bun:*, package names, absolute paths, URLs and paths that leave the folder are refused with the file and line of the import.
  • Deterministic. The same composer files and the same brief give the same song, byte for byte, on every machine.
Bound Value
Files 256 modules, 1 MiB each, 4 MiB together
Engine memory 256 MiB
Engine stack 1 MiB
Wall time 10 s (--timeout-ms, up to 60 s)
Brief 8 MiB of JSON, with the score to vary
What it returns 8 MiB of JSON

A composer that throws, loops, or runs out of memory or stack ends with a diagnostic naming the composer file and line, and nothing is written.

Terminal window
dawn song [dir] --composer <folder|collection/entry> [--prompt "<text>"] [--seed <n>] [--key "<key>"] [--tempo <bpm>] [--bars <n>] [--form "<name:bars ...>"] [--mood <word>] [--energy <0..1>] [--palette <palette.json|collection/entry>] [--vary] [--force] [--json]
  • --composer takes a folder, its dawn.composer.json, or an installed entry written <collection>/<entry>. A name of that shape is looked up in collections.lock.json first; write ./a/b for a folder that is spelled the same. dawn selects DAWN’s own composer, which takes its own options (dawn song --help).
  • --palette offers the palette’s bass, bed, lead, keys and texture sounds in the brief (Build a sound palette).
  • --vary passes the project’s current song as brief.score, for a composer that writes a variation of it. It replaces the song, so it needs --force.
  • A folder whose song.ts already has tracks is not replaced without --force.
  • --json prints the folder, seed, composer identity, track and note counts, bars, tempo, key, voices and summary.

Invalid arguments and a composer that fails or returns an invalid song exit with code 2 and say why on stderr; an existing song without --force exits with code 1.

Add the folder to a collection like any other entry. collection add recognizes a folder with dawn.composer.json as a composer and lists its files with their digests:

Terminal window
dawn collection add dawn.collection.json composers/my-composer --credit "Your name" --license software=MIT --apply

Others install it into a project and compose with it by name:

Terminal window
dawn collection install https://github.com/OWNER/REPOSITORY my-composer
dawn song . --composer my-library/my-composer --seed 3

An installed composer runs from its locked files only. Each must still hold the bytes collections.lock.json records, or the command refuses it and says how to restore it, and a file the lock does not list is never read, so nothing added beside the entry can be imported. Like a song, a locked composer changes on dawn collection update only when you name it.

DAWN has two sealed runtimes: the song engine for TypeScript and WebAssembly devices for sound. Composers use the song engine because a composer’s work is the SDK’s: chords, progressions, rhythms and tracks, written as TypeScript an author can read. A WebAssembly composer would have to rebuild those in another language and hand back raw score JSON. The engine already enforces what a composer needs, without a new runtime to review. A WebAssembly composer interface may follow if one is needed.

  • DAWN’s composer. The built-in composer is not a plug-in and is not in the SDK; it stays the default.
  • Cost. A valid song can still be expensive to render within the score limits.
  • Words. A composer writes notes, sounds and structure. DAWN’s lyric drafting, voicing level match and render checks belong to its own composer.
  • Trust in the author. Checksums identify bytes, not who wrote them. The sandbox bounds what a composer can do; it does not judge whether its music is any good.

Documentation drafted with AI and checked against the product source.