1# songs
2
3One folder per song, grouped by theme: `songs/<theme>/<song>/`.
4
5Each song folder holds:
6
7- `SPEC.md` — the spec the song is generated from. Its frontmatter carries:
8  - `status` — `planned` (spec only) or `made` (`song.js` exists).
9  - `ideas` — where the idea came from, if it started as a pitch: date,
10    model, harness, the user's prompt verbatim, and the pitch verbatim.
11  - `pitch` — if a listener's pitch on the site (the jev panel's pitches)
12    gave the song its idea, that pitch's id (22 characters): the pitch then
13    shows "became" and this song. The song's maker says so, never the
14    pitch's author (`website/src/jev/pitches.mjs`); a malformed id fails
15    the build.
16  - `critic` — Jev's verdict on the song as it stands: the date, the
17    model, the `method` (the rubric's version), each criterion's score out
18    of 5, and `art`, their mean out of 5. Each is the mean of several
19    runs (three by default), and `artRuns` lists each run's own `art`: one
20    run moves by up to 0.06 on unchanged code. The rubric
21    (`website/src/jev/critic.mjs`) scores hook, development, structure,
22    concept, originality and craft like a harsh critic: 0 is not a song, 3
23    is good, 5 the best ever made in its genre. So 60% means good, 90% takes
24    peak work, and 100% is out of reach. The state is the title, the spec
25    body, the code and facts measured from it. Three notes scored 2% and a
26    one-bar loop 11%; the songs 57-66% (2026-09-24). The card shows "N%
27    art", and hovering its cover shows the criteria. `tools/critic/`
28    records it. (Until 2026-09-24 it was one yes/no question, "is this art?",
29    which every song passed at 93-96%.)
30  - `revisions` — every prompt that changed the music: date, model,
31    harness, the prompt, the file it produced, and `art`, Jev's score for
32    that revision's code, a mean over the runs listed in `artRuns`
33    (`null`, with a comment, where the code could not be recovered). A song made from a pitch has the pitch as its first
34    prompt; later prompts are the user's requests, written up as
35    instructions about the music. The spec view shows the scores and how
36    they changed.
37- `song.js` — the track, once made. Alternate takes sit beside it under their
38  own names.
39- `cover.webp` — the song's card image in the song browser, 512×512.
40- `README.md` — its first paragraph is the card's description.
41
42A song lets Jev arrange it live by declaring it at the top in TypeSafe's
43own shape, `jev({ state, questions })` with the SDK's `choice`, `score`
44and `noul` (`website/src/jev/jevCore.mjs`), and composing the answers in
45Strudel. Songs use two: `formJev` picks the next section, and `walk(section,
46…)` holds the form's rules in code; `djJev`, asked after it (`after: {
47section }`), sets a level per part (out, back or full; a `score`, or a `choice`
48narrowed per section with `allow`) for that
49section, how the song moves into it, and its energy; each part plays at
50its level.
51The site's Worker relays the calls with the site's own TypeSafe key
52(`worker/`), so visitors need none.
53
54Levels: each song sets its own master with `.mul(postgain(x))` so its
55peaks sit under -1 dBFS. superdough's master limiter
56(`packages/superdough/superdoughoutput.mjs`) holds everything that reaches
57the speakers to -1 dBTP, so a hot mix cannot clip, but it is a safety net,
58not the mix: a song whose measured peak is -1.0 is being limited, and
59should be turned down until it is not.
60
61The card's duration is read from `song.js` itself: the tempo from
62`setcps(bpm/60/4)` and the bar count from the play-once mask
63(`.mask("<1!bars 0!…>")`).
64
65Themes:
66
67- `jev/` — songs about Jev, TypeSafe AI's typed-decision model.