# DAWN DAWN is a TypeScript music SDK and CLI. Write a score, check it and render audio or MIDI locally. DAWN is a Mac app with the `dawn` command inside it; a script installs the command alone on Linux or macOS and requires access to the private GitHub repository. The [first-song tutorial](/docs/first-song) takes you from installing to a rendered song. ## A song is a project `song.ts` holds the tempo, meter, key, sections and track list. Larger projects put each track in `tracks//track.ts`, with its samples beside it. The versioned TypeScript SDK lives in `.dawn/sdk/v1.ts`, so your editor and your coding agent read the same types and examples. Checking a project evaluates its TypeScript in a child process. Treat a song’s source as code you run on your machine. A saved project’s ordinary render runs locally without an account or network access. ## From an idea to a file | Work | DAWN interface | | ------------------------------------------------------------ | ------------------------------------------------------------- | | Compose notes, grooves, chords and arrangements | [TypeScript SDK](/docs/sdk) | | Choose instruments, effects, automation and a master chain | [TypeScript SDK](/docs/sdk) | | Check types, musical structure and a mix | [CLI reference](/docs/cli) | | Export audio, MIDI or a score preview | [CLI reference](/docs/cli) and [score JSON](/docs/score-format) | | Draft from a seed or an authored chart, or resume a song job | [Song workflows](/docs/workflows) | | Prepare singing, references and audio | [Song workflows and media](/docs/workflows) | | Edit through a coding agent | [Agent guide](/docs/agents) | | Publish a track and manage its visibility | [Publishing guide](/docs/publishing) | The web player previews an exported score alongside its audio. Composition uses the CLI and SDK. ## Desktop player The repository also includes a source-built macOS player for `dawn.score/v1` and audio. It shows notes and lyrics, opens a song project through the installed CLI and exports video through FFmpeg. The [desktop build and usage guide](https://github.com/hraness/dawn/blob/main/desktop/README.md) describes its pinned Rust and Rune toolchain. Repository access is needed for that source build. ## Keep a project portable Commit the song files, local assets and vendored SDK together. DAWN stores derived state under `.dawn/`. Updating DAWN keeps authored files; `dawn changes` explains SDK changes and `dawn migrate` previews format migrations before applying them. Source: https://dawnav.com/docs --- # Make your first song This exercise makes an eight-bar song with drums, bass and piano, then writes a WAV, a MIDI file and a score preview. It uses the `dawn` command in Terminal. ## Install DAWN On a Mac, [download DAWN](https://dawnav.com/install). The app needs macOS 13 or newer on a Mac with Apple Silicon, and the `dawn` command comes inside it: 1. Open the downloaded ZIP and move DAWN to your Applications folder. 2. Open DAWN and choose **Install dawn command**. It links `~/.local/bin/dawn` to the command inside the app. 3. In Terminal, check it: ```sh dawn --version ``` The app keeps itself up to date. Composing, checking and rendering work offline and need no account; the demo songs download the first time you open them. ### Linux, or the command alone A script installs `dawn` without the app, on Linux or macOS with Bun 1.3.14 or newer. It needs the GitHub CLI logged in to an account with read access to `hraness/dawn`, which is a private repository. Check that access: ```sh gh repo view hraness/dawn --json name ``` The installer is attached to the repository’s releases. Read it before running it: ```sh gh release download --repo hraness/dawn --pattern install.sh -O install-dawn.sh less install-dawn.sh sh install-dawn.sh dawn --version ``` It verifies the release archive against its checksums and build attestation, then installs DAWN under your local application directory. ## Create a project ```sh mkdir first-light cd first-light dawn init ``` Open the generated `song.ts` and replace its contents with this complete score: ```ts import { pattern, progression, seq, song, track } from "dawn"; export default song({ tempo: 120, meter: [4, 4], bars: 8, key: "A minor", sections: [ { name: "Verse", startBar: 0, bars: 4 }, { name: "Chorus", startBar: 4, bars: 4 }, ], tracks: [ track({ name: "Drums", instrument: "kit", rhythm: pattern("house") }), track({ name: "Bass", instrument: "bass", notes: seq("A1 . A1 . F1 . G1 . A1 . A1 . F1 . G1 .", { step: 2, len: 0.7, }), }), track({ name: "Keys", instrument: "piano", notes: progression("i VI III VII i VI III VII", { key: "A minor" }), }), ], }); ``` The score uses beats for note positions and zero-based bars for section starts. A period in `seq()` is a rest. ## Check and render ```sh dawn check dawn render first-light.wav --measure dawn render first-light.mid dawn render first-light.score.json --title "First light" --artist "DAWN" ``` A successful check reports the track and note counts. The WAV command prints the output file and measured loudness. Open `first-light.wav` in an audio player, import the MIDI file into another music tool, or read the score JSON to inspect the notes and sections in seconds. If checking reports a file and line, fix that source location and run `dawn check` again. A failed check leaves the authored files in place. Try changing the bass notes or tempo, then repeat the check and render. The [SDK reference](/docs/sdk) explains the builders; the [agent guide](/docs/agents) describes the same loop for a coding agent. Source: https://dawnav.com/docs/first-song --- # Work with a coding agent Any coding agent that can edit local files and run shell commands can work on a DAWN song. Give it the project directory and an outcome, then use the same check-and-render loop you would use yourself. ## Set up the project Install DAWN using the [first-song prerequisites](/docs/first-song#install-dawn), then run `dawn init` in a new song folder. It creates `AGENTS.md` with the current project workflow and a `CLAUDE.md` that refers to it. Existing notes outside the DAWN-owned markers are preserved. The agent should read `AGENTS.md`, `song.ts`, relevant track files and `.dawn/sdk/v1.ts` before editing. The SDK is a dependency-free TypeScript file with the exact types, defaults and JSDoc examples for the version this project uses. ## Give the agent a complete task > Add a quieter piano answer in the chorus. Keep the existing bass and drum parts. Run the project check, then render a new WAV and a MIDI file. Keep a copy or a commit of the project before a substantial edit. DAWN evaluates song source in a sealed engine with no file, network or process access, but a coding agent works with your own authority, so only run agents you trust. ## Use the edit loop 1. Edit `song.ts` or `tracks//track.ts`. 2. Run `dawn check --json` and fix the reported problems. 3. Run `dawn render review.wav --measure` and inspect the result. 4. Run `dawn render review.mid` when you need an editable MIDI export. `dawn check` exits zero after a successful check and one on a source problem. The JSON result carries diagnostics; ordinary text output also names the file, line and column. A project that needs a DAWN update or a format migration stops with exit three and a corrective command. Use the vendored SDK’s existing builders, or update DAWN and review the SDK changes. `dawn migrate` shows a proposed migration; `dawn migrate --apply` writes it and retains a backup. ## Record requests and decisions A project made by `dawn init` records a trace in `trace/`: each check, render and source change, including the edits the agent makes directly to `song.ts` and the track files, with the revision before and after. Ask the agent to add what only it knows: the request it was given, the decisions it made and a handoff before it stops. ```sh export DAWN_TRACE_AGENT="Claude Code" # or "Codex"; names the agent on captured commands dawn trace note --kind prompt --text "Add a quieter piano answer in the chorus" dawn trace note --kind decision --text "Piano an octave below the lead; bass and drums untouched" dawn trace note --kind heard --text "The answer is audible at bar 17 without masking the vocal" dawn trace note --kind handoff --text "Next: check the piano level against the pad, then render" ``` `dawn trace note` assigns the event ID and records against the project's current revision; it evaluates the project to learn that revision unless `--base` is given. Record concise reasons and observable results, not a whole conversation or internal reasoning. Credential-shaped text is replaced by `[redacted]`, but keep credentials out of notes in the first place. `trace/` is committed with the song, so a `git push` publishes every prompt, note and comment recorded there. Run `dawn trace enable . --no-text` to keep metadata only, or `dawn trace disable .` to stop recording. The [trace reference](/docs/traces) lists what each command records. ## Pick the interface for the task | Interface | Use | | -------------------------------------------- | -------------------------------------------------------------------- | | TypeScript SDK | Author notes, tracks, instruments, effects, automation and song form | | `dawn check --json` | Read structured project diagnostics | | `dawn lint --json` | Check musical structure and register | | `dawn measure --json`, `dawn mixqa --json` | Read audio measurements and mix checks | | `dawn render` | Export audio, MIDI, stems or score JSON | | `dawn workflow` | Inspect and resume durable song jobs | | `dawn changes --json`, `dawn migrate --json` | Inspect compatibility changes | | `dawn trace note`, `dawn trace read --json` | Record and read requests, decisions, handoffs and project history | Preserve a quality report and its rendered input together. Optional learned judges, local models, vocals and media helpers have their own setup and compute requirements; use the [workflow guide](/docs/workflows) before invoking them. The [CLI reference](/docs/cli), [SDK guide](/docs/sdk), complete [SDK API reference](/docs/sdk-index) and [score schema](/docs/score-format) describe these shared interfaces. The workflow uses local files and commands and works independently of an agent vendor. Source: https://dawnav.com/docs/agents --- # CLI reference Run `dawn --help` for the exact options in the installed release. DAWN runs on macOS and Linux with Bun 1.3.14 or newer. [Installation](/docs/first-song#install-dawn) requires private repository access. ## Collections `dawn collection init --id --title --curator [--template pack|artist|community] [--ci] [--json]` creates an empty catalog and contribution guide in a new directory; `--ci` adds a pull request check workflow. `dawn collection add [--id ] [--kind ] [--title ] [--credit ]... [--license =