# TypeScript SDK

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](/docs/sdk-index) 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

`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.

```ts
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

| 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

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](/docs/workflows).

## 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

`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

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](/docs/score-format) for visualization and inspection. A coding agent can read the same typed SDK and [edit loop](/docs/agents) as a person.
