Skip to content

TypeScript SDK

View Markdown
For agents

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

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.

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.

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.

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.

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.

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.

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.