# Score JSON format

`dawn render out.score.json` writes one JSON document a player can draw
without the engine: a piano roll per track, the section strip, the tempo and
meter, and the sung lines word by word and syllable by syllable, all in
seconds against the rendered audio's clock (`dawn render out.wav`, `.m4a`
or `.opus` of the same project). The writer is `src/score/export.ts`.

```sh
dawn render out.score.json --title "Redline" --artist "DAWN"
dawn render out.score.json --section "Chorus 1"   # one section, as it loops
```

The title defaults to the project folder's name (or the loop file's, with
`--import`). Audio flags (`--normalize`, `--measure`, `--rate`, `--stems`,
`--jobs`, `--cache`) do not apply.

## What "as it plays" means

- The form is flattened and track time baked (`exportScore`): a section the
  form plays twice appears twice, a second pass named as the flattened score
  names it (`chorus 2`), and a track with its own rate or phase is placed on
  the song timeline.
- Muted tracks are left out, and when any track is soloed only the soloed
  ones are kept. Tracks that play no notes are left out.
- Every time is seconds from the song's start through the tempo map
  (`secondsAtTick`): tempo steps, ramps and fermatas included.
- Sung syllables come from `songModel` (`core/lint/model.ts`), which places
  them in ticks as if the tempo were constant. The export times them again:
  - lyric notes (`lyric` on a note) and takes on voices fitted to the song
    (`bpm`, `len` or `fit` on the sampler voice) go through the tempo map
    syllable by syllable;
  - any other sampler take plays at its recorded rate from the hit that
    triggers it, so a syllable is the hit's time (through the tempo map)
    plus its offset in the take at the book's tempo (`bpm` in the book, else
    the song's tempo at the hit). It is cut where the hit ends.
- The vocal books are the ones the project's `lint.json` lists in `books`
  (as `dawn lint` reads them). A sampler vocal track whose book is listed
  carries its sung notes in `notes`, not the sampler's slot numbers.

## Document

```
{ schema: "dawn.score/v1", title, artist?, duration, key, form?,
  audio?: { url, sha256, type },
  tempo: [{ t, bpm, ramp? }],
  meter: [{ t, num, den }],
  sections: [{ name, kind, t, dur, startBar?, bars?, source?: { name, index, startBar, bars } }],
  tracks: [{ id, name, role, icon, color, lo, hi }],
  notes: { <trackId>: [[t, dur, pitch, vel], ...] },
  lyrics: [{ line, track, t, dur, backing?, words: [{ text, t, dur, syls: [[t, dur, pitch], ...] }] }],
  palette: { bg, fg, accent, muted },
  video? }
```

| Field      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `duration` | Seconds of the song's bars (the audio file is longer by its ring-out). `dawn publish` sets it to the length of the audio it uploads, as the built-in catalog does.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `key`      | The song's key as written (`"Fm"`, `"A minor"`), or `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `form`     | Optional. The form as the source writes it (`"A×2 B A"`, comma separated when a name has a space), when it writes one. Absent when the song plays its bars straight through.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `audio`    | Optional. Not written by `dawn render` or `dawn publish`. dawnav.com never reads it: the publish service's database is the source of truth for a published track's audio URLs and hashes. Another player may use it to ship a score with its audio.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `tempo`    | The start tempo at `t: 0`, then each tempo event at the time it lands. `ramp` (`"linear"` or `"exp"`) means the tempo glides from the previous entry into this one, arriving at `t`; without it the tempo steps at `t`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `meter`    | The opening meter at `t: 0`, then each change. `num`/`den` as in 6/8.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `sections` | In playback order. `kind` is one of `intro verse pre chorus post bridge break outro other`, read from the name (`Drop 1` is a chorus). `dur` runs to the section's last bar, cut at `duration`. When the source writes a form, a section the form plays more than once is one entry per playing, named `A`, `A 2`, `A 3`; each entry then also has `startBar` and `bars` (the song bars it plays, from 0) and `source`: the written section it plays (`name`, its `index` in the source's sections, and the `startBar` and `bars` the source writes it in). Entries with the same `source.index` play the same written notes, so a note at bar `b` of the song is written at bar `source.startBar + b - startBar`. Without a form none of the three is written. |
| `tracks`   | In the song's track order. `role` is one of `lead vox bass drums pad keys fx other`. `icon` names a drawing in the instrument iconset (below). `color` is a `#rrggbb` for a dark background. `lo` and `hi` are the lowest and highest pitch in the track's `notes`, for the roll's range.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `notes`    | Per track, sorted by time: `[t, dur, pitch, vel]`. `pitch` is the sounding MIDI note (cents rounded). `vel` is 0..1. A hit (drums, risers, sliced oneshots) has `dur` 0 and its `pitch` is the drum or slot number, not a pitch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `clips`    | Optional. Per track, the one-shot sampler hits written a beat or longer: `[t, dur]`, where `t` is the hit's `t` in `notes` and `dur` the seconds it was written to last (cut at the song's end). A drawing can show such a hit as long as it sounds; a hit with no row here is a point. Absent when the song has none.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `lyrics`   | Every sung line, sorted by time. `line` is the words joined by spaces. `backing: true` marks lines a backing singer or double sings; the lead's lines have no `backing`. A word joins syllables written `ne- on`; a melisma note (`~`) adds a syllable to the word before it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `palette`  | The page colors: `bg` and `fg`, `muted` for secondary text, and `accent`, the lead vocal's track color (else the first vocal or lead track's).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `video`    | Optional. The music video the song authors with `video()` in `song.ts`: a `dawn.scene/v1` override (`site/player/video/scene.ts`) that the player lays over the scene it derives from the score, with catalog names already resolved to ids and section names to indices. At most 4 KB. `dawn render` writes it and `dawn publish` uploads it inside this file. Absent when the song authors none; readers that do not draw a video ignore it.                                                                                                                                                                                                                                                                                                                  |

Every time and duration is in seconds rounded to 1 ms, velocities to 0.01.
The JSON is compact (no spacing) and ends with a newline.

## Roles, icons and colors

`core/track-look.ts` decides how a track looks, from the track alone, so the
same track looks the same in every song and in every player.

The role is the track's family, first match wins:

1. a drum kit (`kit`, or the `kit`/`drums` instrument), or drum words in the
   id or name (`kick`, `snare`, `hats`, `perc`): `drums`;
2. fx words (`riser`, `impact`, `sweep`, `sub drop`, `zaps`): `fx`;
3. vocal words (`vox`, `vocal`, `voice`, `double`, `chops`, `vocoder`), a
   track that sings a line, or a sampler playing a vocal take file: `vox`;
4. `bass`, `sub`, `reese`, `acid`, `rumble`: `bass`; `pad`, `strings`,
   `violin`, `cello`, `choir`, `stack`: `pad`; `piano`, `grand`, `organ`,
   `bells`, `guitar`, `stabs`: `keys`; `lead`, `hook`, `arp`, `whistle`:
   `lead`;
5. the instrument (`sing` and `vocoder` vox, `piano` keys, `supersaw` pad,
   `saw` and `pulse` lead, noise fx), else `other`.

The icon tells tracks of one family apart. Within the role, the icon word
that comes first in the name decides (then the id, then the instrument), so
"Clap" on the track `snare` is a clap and "Hats & rim" a hi-hat; a track with
no such word takes its role's own icon.

| Role  | Icons                                                                      |
| ----- | -------------------------------------------------------------------------- |
| vox   | `lead-vocal` `backing-vocal` `vocal-chop` `vocoder`                        |
| drums | `kick` `snare` `clap` `hi-hat` `cymbal` `tom` `percussion` `drum-kit`      |
| bass  | `bass-synth` `sub` `bass-guitar`                                           |
| keys  | `piano` `electric-piano` `organ` `harp` `pluck` `guitar` `bells` `mallets` |
| lead  | `lead-synth` `arp` `woodwind` `brass`                                      |
| pad   | `pad` `supersaw` `strings` `cello`                                         |
| fx    | `riser` `drop` `noise`                                                     |
| other | `generic` `sampler`                                                        |

The drawings are single paths on a 24 px grid, stroked and never filled:
`assets/icons/instruments/<name>.svg`, all of them in
`assets/icons/instruments/icons.json` and `core/icons/instruments.ts`. Edit
them in `scripts/build-instrument-icons.ts` and run it. A reader that meets
an icon name it does not know draws the role's own icon.

Each role has four hand-picked shades of one hue, mid saturation, tuned to
read as thin bars on `#0f1115`. Drums are bone, so rhythm reads as light
rather than as one more pitched color:

| Role  | Shades                                  |
| ----- | --------------------------------------- |
| vox   | `#e88aa2` `#f2a7b8` `#f7c6cf` `#c98a9c` |
| lead  | `#f2b866` `#e8995a` `#f5d08e` `#d9a441` |
| bass  | `#8f7ff0` `#a99df5` `#7f6fe0` `#c3baf9` |
| drums | `#e6dfd1` `#cfc8ba` `#b5afa3` `#9c968b` |
| pad   | `#5cc3b2` `#86d8ca` `#45a899` `#a8e3d8` |
| keys  | `#6fa8f0` `#98c2f5` `#5590dc` `#b9d4f7` |
| fx    | `#8f98a6` `#a7afbb` `#7b8492` `#bcc3cc` |
| other | `#9fc98c` `#bcdcad` `#82b070` `#cfe6c3` |

The icon asks for a shade (the lead vocal, the kick, the piano and the plain
pad take the first; a backing vocal, a snare, a sub and a supersaw the
second, and so on). A track takes that shade, or the next one no earlier
track of its role took; a fifth track of one role shares a shade. So a
kick is the same bone and a lead vocal the same pink in every song.

`name` is the track's own name, or its id spelled out when it has none
(`dblL` is "Double left").

## Size

The Redline demo (128 s, 20 tracks, about 4,000 notes, 53 sung lines)
writes 125 KB, 22 KB gzip. Drums as hits keep a busy groove small. The
golden test (`src/score/export.test.ts`) fails if that song passes 60 KB
gzip.

## Compatibility

Readers ignore fields they do not know. The schema stays `dawn.score/v1`
while changes only add fields; a change that removes or redefines one is
`v2`.
