Skip to content

Score JSON format

View Markdown
For agents

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

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.

Terminal window
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.

  • 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.
{ 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.

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”).

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.

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.

Documentation drafted with AI and checked against the product source.