Score JSON format
For agents
Give your agent this page’s Markdown link, or choose a collection.
- Documentation indexFind a guide and its Markdown link.
- Full documentationRead all curated guides in one text file.
- Machine manifestFind page metadata, Markdown URLs and checksums.
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.
dawn render out.score.json --title "Redline" --artist "DAWN"dawn render out.score.json --section "Chorus 1" # one section, as it loopsThe 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
Section titled “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 (
lyricon a note) and takes on voices fitted to the song (bpm,lenorfiton 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 (
bpmin the book, else the song’s tempo at the hit). It is cut where the hit ends.
- lyric notes (
- The vocal books are the ones the project’s
lint.jsonlists inbooks(asdawn lintreads them). A sampler vocal track whose book is listed carries its sung notes innotes, not the sampler’s slot numbers.
Document
Section titled “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
Section titled “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:
- a drum kit (
kit, or thekit/drumsinstrument), or drum words in the id or name (kick,snare,hats,perc):drums; - fx words (
riser,impact,sweep,sub drop,zaps):fx; - vocal words (
vox,vocal,voice,double,chops,vocoder), a track that sings a line, or a sampler playing a vocal take file:vox; 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;- the instrument (
singandvocodervox,pianokeys,supersawpad,sawandpulselead, noise fx), elseother.
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.
Compatibility
Section titled “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.
Documentation drafted with AI and checked against the product source.