SPEC.md1--- 2title: LIGHTNING IN A BOTTLE 3theme: jev 4status: made 5song: song.js 6measured: {"date":"2026-09-25","song":"9a02a6fdb1ff","total":{"loudnessDbfs":-21.8,"peakDbfs":-1.7},"parts":{"bass":{"loudnessDbfs":-29.1,"peakDbfs":-17.7},"chords":{"loudnessDbfs":-28.5,"peakDbfs":-9.7},"drums":{"loudnessDbfs":-28.9,"peakDbfs":-11},"other":{"loudnessDbfs":-41.2,"peakDbfs":-8.8},"riff":{"loudnessDbfs":-28.5,"peakDbfs":-15.1},"vocals":{"loudnessDbfs":-31,"peakDbfs":-8.1}},"sections":{"1-8":{"total":{"loudnessDbfs":-25.1,"peakDbfs":-6},"parts":{"bass":{"loudnessDbfs":-27.2,"peakDbfs":-17.7},"drums":{"loudnessDbfs":-40.1,"peakDbfs":-19},"vocals":{"loudnessDbfs":-29.8,"peakDbfs":-8.1}}},"9-16":{"total":{"loudnessDbfs":-25.4,"peakDbfs":-9.9},"parts":{"bass":{"loudnessDbfs":-69.6,"peakDbfs":-37.7},"drums":{"loudnessDbfs":-30.3,"peakDbfs":-11},"riff":{"loudnessDbfs":-27.1,"peakDbfs":-15.1},"vocals":{"loudnessDbfs":-209.5,"peakDbfs":-167.7}}},"17-24":{"total":{"loudnessDbfs":-21.5,"peakDbfs":-5.9},"parts":{"bass":{"loudnessDbfs":-28.2,"peakDbfs":-18},"drums":{"loudnessDbfs":-30.6,"peakDbfs":-16.9},"riff":{"loudnessDbfs":-27.1,"peakDbfs":-15.1},"vocals":{"loudnessDbfs":-25.7,"peakDbfs":-8.3}}},"25-32":{"total":{"loudnessDbfs":-19.2,"peakDbfs":-1.7},"parts":{"bass":{"loudnessDbfs":-28.2,"peakDbfs":-18},"chords":{"loudnessDbfs":-23.6,"peakDbfs":-9.7},"drums":{"loudnessDbfs":-28.7,"peakDbfs":-11},"riff":{"loudnessDbfs":-27.5,"peakDbfs":-15.8},"vocals":{"loudnessDbfs":-26.7,"peakDbfs":-8.3}}},"33-40":{"total":{"loudnessDbfs":-23.4,"peakDbfs":-8.1},"parts":{"bass":{"loudnessDbfs":-28.2,"peakDbfs":-18},"chords":{"loudnessDbfs":null,"peakDbfs":null},"drums":{"loudnessDbfs":-29.2,"peakDbfs":-12.2},"riff":{"loudnessDbfs":-27.4,"peakDbfs":-15.8},"vocals":{"loudnessDbfs":-89.8,"peakDbfs":-60.3}}},"41-48":{"total":{"loudnessDbfs":-19.6,"peakDbfs":-3.2},"parts":{"bass":{"loudnessDbfs":-28.3,"peakDbfs":-18},"chords":{"loudnessDbfs":-23.6,"peakDbfs":-9.7},"drums":{"loudnessDbfs":-25.3,"peakDbfs":-11.1},"riff":{"loudnessDbfs":-27.8,"peakDbfs":-16.9}}},"49-56":{"total":{"loudnessDbfs":-19.6,"peakDbfs":-3.2},"parts":{"bass":{"loudnessDbfs":-28.2,"peakDbfs":-18},"chords":{"loudnessDbfs":-23.8,"peakDbfs":-9.7},"drums":{"loudnessDbfs":-25.4,"peakDbfs":-11.2},"riff":{"loudnessDbfs":-27.7,"peakDbfs":-16.9},"vocals":{"loudnessDbfs":null,"peakDbfs":null}}},"57-64":{"total":{"loudnessDbfs":-24.3,"peakDbfs":-7.1},"parts":{"bass":{"loudnessDbfs":-31.2,"peakDbfs":-18.7},"drums":{"loudnessDbfs":-33.3,"peakDbfs":-15.4},"other":{"loudnessDbfs":-32,"peakDbfs":-8.8},"riff":{"loudnessDbfs":-30.1,"peakDbfs":-15.1},"vocals":{"loudnessDbfs":-31.5,"peakDbfs":-8.1}}}}} 7critic: 8 date: 2026-09-25 9 model: jev-1.13.0 10 method: rubric-1 11 art: 0.65 12 artRuns: [0.65, 0.65, 0.64] 13 criteria: 14 hook: 3.5 15 development: 3.2 16 structure: 3.1 17 concept: 3.9 18 originality: 3.2 19 craft: 2.5 20ideas: 21 - date: 2026-09-24 22 model: claude-opus-5-5 23 harness: claude-code 24 prompt: "Research Jev's real use cases; jab at people using Jev where deterministic code would do better, such as game bots." 25 brief: "An earnest anthem about using Jev properly. The intro is a robot voice reading founder Diogo Almeida's line, \"We have lightning in a bottle, and yet it is not useful\". Layer Doom's E1M1 riff and shotgun sounds as a nod to TypeSafe's launch demo, where Jev played Doom. Vocoder chorus: \"the code decides what code can decide, Jev takes the rest\". It builds to one big drop and a clean ending." 26revisions: 27 - rev: 1 28 date: 2026-09-24 29 model: claude-opus-5-5 30 harness: claude-code 31 prompt: "An earnest anthem about using Jev properly. The intro is a robot voice reading founder Diogo Almeida's line, \"We have lightning in a bottle, and yet it is not useful\". Layer Doom's E1M1 riff and shotgun sounds as a nod to TypeSafe's launch demo, where Jev played Doom. Vocoder chorus: \"the code decides what code can decide, Jev takes the rest\". It builds to one big drop and a clean ending." 32 output: null # overwritten by rev 2 33 art: 0.62 34 artRuns: [0.62, 0.62, 0.62] 35 - rev: 2 36 date: 2026-09-24 37 model: claude-opus-5-5 38 harness: claude-code 39 prompt: "Let Jev arrange the song as it plays. Split it into named parts, and at every 8-bar section have Jev pick the next section's move from a fixed menu (as written, no drums, a breakdown, riff and drums), called from the song's own code with .jev()." 40 output: null # overwritten by rev 3 41 art: 0.64 42 artRuns: [0.64, 0.63, 0.64] 43 - rev: 3 44 date: 2026-09-24 45 model: claude-opus-5-5 46 harness: claude-code 47 prompt: "Let Jev decide the song's form and when it ends, not just its layers. Name each 8-bar section and the sections allowed to follow it; at each section Jev picks the next section, its move, and how intense it is, and ends the song by choosing the outro, with a hard cap of 16 sections. Tell Jev the tempo, key, chords, lyrics and everything played so far, and how the listener reacted. Without Jev it plays as written." 48 output: null # overwritten by rev 4 49 art: 0.65 50 artRuns: [0.65, 0.65, 0.65] 51 - rev: 4 52 date: 2026-09-25 53 model: claude-opus-5-5 54 harness: claude-code 55 prompt: "Fix the mix and the form. The master must not clip, and the vocals must sit within about 3 dB of the drums. Make \"Jev\" read as Jev in every sung line. The quote, the outro hook line and the ending always play, outside Jev's levels, and the intro plays as written. The drop lifts through a sixteenth double-kick, the guitars opening up and crashes, not a kick 18 dB over the band; every crash is a real crash. Only one drop: no drop after drop2. The last bar of each section belongs to the transition, so written fills do not double it; the build rises across all 8 bars with a filter sweep, a noise riser and one snare-roll crescendo; the chorus gets a fuller beat and the octave riff; the intro pulse and bass get an audible harmonic; the ending is an E power chord that rings; a dropout gap is silent. Tell Jev only what plays: derive every part's and section's text from the masks." 56 output: song.js 57 art: 0.65 58 artRuns: [0.65, 0.65, 0.64] 59--- 60 61# LIGHTNING IN A BOTTLE — spec 62 63`song.js` is generated from this spec. Change the spec first, then the song. 64 65## Intent 66 67The right way to use Jev. Facts: 68- The quote is TechCrunch's report of Diogo Almeida's motivation 69 (`~/brains/personal/technology/artificial-intelligence/jev/jev.md`): "We have lightning in a bottle, and yet it is 70 not useful." 71- TypeSafe's launch demo was Jev playing Doom from structured game state 72 (`ecosystem/jev-doom-agent.md`). 73- The pattern the chorus sings is `jev-axi` (`ecosystem/jev-axi.md`): routine 74 commands are decided locally with zero Jev calls; only ambiguous or risky 75 ones go to Jev (44/44 on its own labeled safety set). 76- Almeida's assistance vs. automation split (`assistance-vs-automation.md`): 77 automation's goal is to remove the human from the loop. 78 79## Style 80 81- Metal-tinged anthem, 150 bpm, E minor: Em – C – G – D, two bars per chord, 82 so each vocoded line sits on one chord. 83- The E1M1 riff written as notes, in eighths over four bars, checked against 84 the Ultimate-Guitar tab ("DOOM - E1M1 Hangar - At Doom's Gate", by Ophion): 85 palm-muted E2 pairs answered by E3, D3, C3, A#2, then B2→C3; the second 86 pass ends on a held A#2. Distorted sawtooth plus a square an octave up. 87 - In the riff section (bars 9–16) it stays on its own E pedal. 88 - Under the verse, chorus, build, drop and outro it is transposed to follow 89 the chord root (Em 0, C −4, G +3, D −2). 90 - The square an octave up joins in the chorus and stays through the build 91 and the drop. 92- Power-chord stabs (root, fifth, octave) mark the chords in chorus and drop. 93- The intro's pulse and the bass are a sine sub on the root with an audible 94 harmonic: a filtered triangle an octave up, so small speakers hear them. 95- Doom shotgun sample as an accent on section starts. 96- Builds steadily to one drop; toms and crashes; no pad. 97- The crash is Dirt-Samples `hh27:1` (a real crash; `cr` is a ride), matched 98 to the drums by level. `cr` plays only as the drop's ride. 99- **Mix.** The master peaks at or under −1 dBFS, measured (superdough has no 100 limiter, so a master level sets it), and the vocals sit within about 3 dB 101 of the drums as measured. `measured:` in the frontmatter records the mix as 102 written. 103 104## Structure 105 10664 bars as written (~1:42); Jev plays 7–16 sections (1:30–3:25), and the 107cap narrows its choices from section 12. The last bar of every section 108belongs to the transition into the next one (see "Into the next section"). 109 110| Bars | Section | Contents | 111|---|---|---| 112| 1–8 | Intro | Sub pulse on E with an audible harmonic; the robot voice reads the quote from bar 3; a tom fill in bar 8 (when the move into the next section is a cut) | 113| 9–16 | Riff | E1M1 riff enters on its E pedal with a rock beat; shotgun and crash on bar 9 | 114| 17–24 | Verse | Riff follows the chords; vocoder lines 1–4, one per chord | 115| 25–32 | Chorus | Power chords, the riff an octave up, and a fuller beat: a busier kick and a crash on every chord (the one on bar 25 about 3 dB lower, under the sung "Th-"); "The code decides what code can decide" on Em, then on C; "Jev takes the rest" on G, then on D | 116| 33–40 | Build | Rises across all 8 bars: the riff's filter opens from dull to bright, a noise riser over bars 37–40, one snare-roll crescendo over bars 39–40 (when the move into the drop is a cut or a dropout); shotgun on bar 33 | 117| 41–56 | Drop | Instrumental: a sixteenth double-kick, a ride on the quarters, the guitars opening up (the riff's filter wide open, the octave square louder), power chords, a crash on every chord's downbeat; shotgun on bar 41 | 118| 57–64 | Outro | "The code decides…" once on Em; the riff plays bars 57–60; the ending: a final E power chord (E, B, E), a crash and a shotgun on bar 61, left to ring to the end | 119 120The sections already align with the 8-bar chord cycle: verse, chorus and 121outro start on bars 17, 25 and 57, each the first bar of an Em. 122 123## Vocals 124 125- Robot voice (plain `speak`): "We have lightning in a bottle, and yet it is 126 not useful." 127- Vocoder verse: "Remove the human from the loop" — Em; "Routine calls never 128 leave the machine" — C; "Only the residue goes to Jev" — G; "Forty-four out 129 of forty-four" — D. 130- Vocoder chorus: "The code decides what code can decide" — Em – C; "Jev takes 131 the rest" — G – D. Each line is sung twice, once on each chord of its pair, 132 so there are two renders of each. 133- Meme: Doom shotgun (fire + pump). 134- **Rendering "Jev".** A line with the name is rendered at speech rate −4 135 with a stop or comma after the name, then `vocode --dry 1.5 --seed 1` on 136 its chord; the name is typed "Jevv" (typed "Jev" or "Jehv", `small.en` 137 heard "Jeff"). The pause after the name is cut to 0.25 s so the line fits 138 its two bars. If the name still reads as "Jeff", spell it out. 139- **Every vocoded line's row** in `samples/README.md` records how `small.en` 140 and `medium.en` read it back, its length, loudness (LUFS) and true peak 141 (dBTP). 142 143## Jev in the booth 144 145Jev arranges the song as it plays, as two jevs declared at the top in 146TypeSafe's own shape (`jev({ state, questions })`, `website/src/jev/`), both 147given the song as state (subject, tempo, key, chords, lyrics): 148 149- **`formJev`** asks one choice: which **section** plays next, among the 150 song's eight 8-bar sections. 151- **`djJev`** asks, once that is decided, a level per part (riff, power 152 chords, bass, drums, vocals: out, back or full in this section), how the 153 song moves **into** it (a choice) and a score for the section's 154 **energy**. Questions in one request cannot see each other's answers, so 155 it is a second request, told the section just chosen (`after: { section 156 }`). 157 158Both are asked every 8 bars (`.every(8, …)`), and the answers are composed 159in ordinary Strudel at the bottom: `walk` holds the form's rules, each 160part plays at its level, the transition plays over the last bar before 161the section, and `energy.score` scales the parts' velocity. 162 163**What is not Jev's.** The brief makes the quote the intro, so bars 1–8 164always play as written: every part at its written level, at full energy, 165whatever the opening answers say. The story is outside Jev too, and always 166plays where the structure table puts it: the quote, the outro's hook line 167and the ending (the final E power chord, crash and shotgun). No level, no 168energy and no dropout touches them. 169 170**The form.** A section may be followed only by these: 171 172| Section | Bars as written | May be followed by | 173|---|---|---| 174| `intro` | 1–8 | riff | 175| `riff` | 9–16 | verse, chorus | 176| `verse` | 17–24 | chorus, riff | 177| `chorus` | 25–32 | build, verse; after the first drop, verse or outro | 178| `build` | 33–40 | drop | 179| `drop` | 41–48 | drop2 | 180| `drop2` | 49–56 | verse, chorus, outro | 181| `outro` | 57–64 | (the end) | 182 183The brief asks for one big drop, so drop2 never leads straight back into 184the drop, and after the drop has played the chorus no longer leads to the 185build. `walk()`'s `next` is a fixed list, so the history half of the 186chorus rule waits on a hook in `walk` (a shared change to `jevCore`); until 187it lands, the chorus's `next` stays build or verse at every visit. 188 189These rules are code (`walk`), not Jev: each request offers Jev only the 190sections allowed next. The written order is always allowed, and it is what 191plays when Jev can't be reached. The song ends when Jev picks the outro, whose ending always rings out; at 16 sections (about 3½ minutes) the outro is 192forced. A section plays its own bars, so a repeated chorus is the chorus. 193 194**The parts.** Jev sets each part **out** (silent for the section), **back** 195(quieter than written) or **full** (at its written level): the riff alone 196before the band returns, the vocals pulled back in the build, the chords 197out for a bare verse. The level is a Score, so it is Jev's 198probability-weighted answer: under 0.5 the part is silent, and above it the 199part plays at its nearest step: back at half velocity, full as written. A part that plays keeps its own masks, so vocals still appear 200only where the structure table puts them. Each part plays on its own orbit 201named for its question (`riff`, `chords`, `bass`, `drums`, `vocals`), so 202the browser's meter hears each one alone; the riser has its own 203(`riser`). When Jev can't be reached, every part plays full. 204 205**What Jev is told is derived from the masks.** Each part's question names 206the sections it plays in, and each section's option lists the parts that 207play in it, both computed from the same mask constants the parts play 208from, so the text cannot say a part plays where it does not. 209 210**Into the next section.** Jev also picks how the song moves into the 211section it is deciding, and it plays over the last bar of the section 212before it: **cut** (straight in), **fill** (down the toms, ending on a 213snare double on the last eighth), **riser** (white noise in sixteenths, 214its high-pass and level sweeping up) or **dropout** (every part stops for 215the last beat, a gap before the section hits; reverb already ringing rings 216into the gap, but no held note does). The last bar belongs to the 217transition: the intro's written fill plays only on a cut, and the build's 218snare roll only on a cut or a dropout. The build already rises into the 219drop, so the move into the drop is never a riser. The outro has no section after it, 220so its last beat always plays. When Jev can't be reached, it is a cut. 221 222**A little chance.** The section is sampled from Jev's 223probabilities at temperature 0.7 (`sample`), so two plays of the song can 224take different paths; the strip shows Jev's top pick beside the one 225sampled. A close call between 226sections is where sampling matters most, so there is no confidence 227threshold: an unsure Jev still picks, and the written order plays only 228when Jev can't be reached. 229 230**Energy** is a four-step ladder, from held back to all out. It scales 231every part's velocity together (0.55 to 1), so the mix keeps its balance; 232the intro is always at 1, and the story and the ending are never scaled. 233 234- Each call tells Jev the song's subject, tempo, key and chords, every 235 section's contents and lyrics, everything played so far, how loud each 236 finished section measured in the browser, the sections left before the 237 cap, and the 🔥/😴 reactions from the listener's tab. 238- This relaxes the constraints below that the song plays once in a fixed 239 order and never varies by chance: the arrangement varies with Jev's 240 choices, which are judgments, with a little sampled chance in the form. 241 242## Constraints 243 244- Plays once from bar 1 and ends; never loops. Sections are absolute-cycle 245 masks, so playback starts from stopped. 246- Structured: patterns vary by section, never by chance. (Random chopping 247 read as noise on the first song.) 248- No sustained background pad; harmony comes from rhythmic parts. 249- Vocals only where the structure table puts them; drops are instrumental. 250- Meme clips are the real audio (myinstants, or YouTube via yt-dlp), cut at 251 word timings measured with whisper.cpp. Vocoder lines are made with 252 `speak` + `vocode` on the chord they land on, and checked by transcribing 253 the result with whisper.cpp. Everything lands in `samples/<sound>/` with 254 a provenance row in `samples/README.md`. 255- Samples load from `samples('jev-samples/strudel.json')`; drums from 256 `github:tidalcycles/dirt-samples`.