TypeScript SDK
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.
DAWN’s SDK builds frozen score data without I/O. Import builders from "dawn" in a song project; the TypeScript configuration maps that name to .dawn/sdk/v1.ts. Read that file’s signatures and JSDoc for the exact version in the project.
The API reference contains every current export, input type, overload and its original JSDoc, grouped by domain. It is generated from the source and checked for drift in the required test suite.
Build a score
Section titled “Build a score”song() takes the tracks, tempo, meter, key and arrangement. track() takes the instrument, notes or rhythm, effects and automation. Authors use beats; the SDK converts the score to integer ticks, with 480 ticks per beat by default.
import { note, song, track } from "dawn";
const bass = track({ name: "Bass", instrument: "bass", notes: [note("A1", 0, 1), note("E2", 2, 0.5, 0.6)],});
export default song({ tempo: 120, meter: [4, 4], bars: 4, tracks: [bass] });note(pitch, start, length = 1, velocity = 0.8) accepts a MIDI number or a pitch name. Positions and lengths are beats; velocity is zero to one. seq() makes a note sequence, and a period, hyphen or underscore in its pattern is a rest.
Compose and arrange
Section titled “Compose and arrange”| Builders and input | Use |
|---|---|
note, seq, chord, progression |
Individual notes, sequences and harmony |
hit, hits, grid, euclid, pattern |
Drum and sampler rhythm |
track, song |
Tracks and the complete score |
sections, form |
Zero-based bar ranges and section repeats |
time, tempo, ramp, rit, accel, fermata, meter |
The song clock and meter |
Track time, phasing, stepPhasing |
Track cycles, rates and phases |
Song or track tuning |
Equal divisions, ratios, cents or a supported tuning description |
The SDK validates inputs and throws DawnSdkError with the affected field when a value is malformed. dawn check connects those failures to the authored source.
Choose the sound
Section titled “Choose the sound”Tracks support synthesized voices, piano and organs, physical strings and winds, drums, modal instruments, wavetables, granular sound, samplers and texture beds. The instrument field accepts a supported name or an engine builder such as sampler(), wavetable(), granular(), modal(), wind(), sing() or texture().
audio() adds a timed audio region; repeatAudio() repeats regions. Sampler paths stay beside a track’s local assets. Preparing recorded or generated vocals can require the optional runtime described in workflows.
Shape the result
Section titled “Shape the result”Track inputs cover envelopes, filtering, delay, reverb, insert effects, panning and automation. Guitar rigs combine stomp, amp and cabinet settings. patch() and fxPatch() build typed signal graphs with named macros. Pattern signals such as sine, tri, rand and perlin provide repeatable modulation.
The song’s master chain follows the track and bus mix. Settings include EQ, compression, tape, stereo width and limiting. Export normalization is set on dawn render, so one output can have a loudness target without changing the song source.
Styles and composition constraints
Section titled “Styles and composition constraints”defineStyle() records composition constraints. hard() marks a required choice and soft() supplies a preference. Style inputs describe groove, harmony, form, energy and vocal space. The CLI’s seeded composer consumes these styles; the style record alone does not add notes.
Versions and interoperability
Section titled “Versions and interoperability”The vendored file declares SDK_VERSION and SDK_MAJOR. dawn check refreshes a compatible SDK and reports needed migrations while preserving authored song files. Use dawn changes to inspect added, renamed or removed interfaces before updating a project.
dawn render out.mid writes MIDI for other music tools. dawn render out.score.json writes the score JSON contract for visualization and inspection. A coding agent can read the same typed SDK and edit loop as a person.
Documentation drafted with AI and checked against the product source.