The colour key

Colour = the note's job in the song. Every song has a home note it keeps coming back to — this app always calls it Do (like Do-Re-Mi). In a normal major song, home is yellow, the other six notes of the song get the other six colours, and notes the song doesn't use stay grey. Move home and the colours move with it — yellow means home, not any particular piano key. Only two pairs of coloured squares touch with no grey between: blue→purple and orange→yellow. That W-W-H-W-W-W-H climb is the ladder itself — start it on any note and it slides over unchanged. The two joins never move: spot them and you know where you are, in every view.

Happy songs are usually major — Do is yellow. Sad songs are usually minor — Do is red. There are seven flavours in all, with impossible Greek names (Lydian, Mixolydian…). Don't memorise the names — remember the colours: the seven colours always keep the same pattern, so the only thing to remember is which colour home lands on. And the flavours sort into three families you can see: Chords match the same families. A chord wears its root's colour — and a chord rooted on purple, yellow or pink is major; on green, red or blue it's minor; on orange, diminished. Colour and sound never disagree.

Can't go by the colours? Turn on 🔢 Numbers. Every note in the key gets its number printed on it — 1 is always home, 5 is always Sol — so the numbers tell you exactly what the colours tell you. It works on every view, alongside the colours or instead of them, and if you're colourblind it's worth switching on before anything else. Numbers are how most players talk to each other anyway: a 1–4–5 is a 1–4–5 in every key there is.

Basics

Three ways to get music in: Load music: drag a .ladder.json, MIDI, MusicXML, Ableton .als, or audio file anywhere on the page — or use 🎧 Listen to hear the room live.

🟢 Setting Spotify up (once): the first time you open the Spotify panel there's a short bit of setup — about two minutes, free, never again. Spotify hands out a key so this page is allowed to see what you're playing: make an app on Spotify's developer page, paste this page's address in as the Redirect URI (there's a ⧉ button that copies it exactly right), then paste the app's Client ID back here and tap Connect. One catch — this needs the real website, not a file opened off your computer, because the sign-in has to redirect somewhere.

🟢 Spotify: play a track in the Spotify web player tab, open the Spotify panel, and tap 🎧 Capture this track — one tap restarts the song, records it from the tab, analyzes it, and saves its light show (plus the recording into the 🎉 library). From then on the app recognises that song whenever Spotify plays it — any playlist, even shuffled — and runs the lights in sync automatically. If a capture doesn't work it's almost always that the browser shared the wrong tab: tap 🩺 Capture check before you commit and it listens for two seconds, then tells you plainly whether the tab you picked is really making sound. And if a capture does come back silent, the app throws it away rather than saving you an empty show — fix the tab, capture again, nothing is lost.

🩺 Capture check: in the Spotify panel, next to 🎧 Capture. Tab recording only works if the tab you shared is the one actually making sound — this listens for two seconds and tells you plainly whether it's hearing the music, so you find out now instead of after a three-minute recording. If it hears silence it says exactly what to fix.

⇪ Backup / ⇩ Restore: the library panel packs every show and its recording into one .ladderlib file you can keep or move to another computer. Everything lives in this browser, so this is the only copy that survives clearing your browser data.

🔓 Lock Tonic: pins Do (home) to 12 o'clock and hums a steady home note under everything you play. Works on every view.

🎸 Chords: paste a progression (plain C G Am F or an Ultimate-Guitar sheet) before listening/uploading — it sets the key and guides chord detection.

⏺ Loop recorder: fold open the bar under the stage to record what you play into a quantized loop, or 🎸 Jam Along over the loaded loop — your live notes light the show too.

🔁 Build a loop sits beside the recorder and works the other way round: instead of playing a loop in, you tap chords onto a grid of bars and beats, hear it back straight away, and nudge until it sounds right. Save it and it becomes a named section — Verse, Chorus, whatever you call it — that the rest of the app treats as part of the song. Good for when you know the chords but don't fancy performing them.

New window: opens a synced mirror (up to 8) — same song, same playhead, its own view and its own 🔈 mutes. One window is ★ PRIMARY (controls); tap a mirror's badge to make it primary.

🎓 Tour: the fastest way in — tap 🎓 Tour in the toolbar and it loads a song, starts it playing, and walks you through every view with a caption on each one. About ninety seconds.

🎬 First time here? Upload → Demo song loads Shady Grove (the Garcia & Grisman arrangement of the traditional tune) so you can see everything working with nothing to upload. Songs you load land in 🕘 Recent songs automatically — reopen any with one tap.

🎯 Pentatonic: the five can’t-miss pentatonic notes stay bright on every view while the two spicy ones — the purple and orange (Fa & Ti) colours — fade back. The improviser's can't-miss palette — great when you're soloing and don't want to think.

🏋️ Practice: next to the Loop toggle — slow the song to 50–100%, loop a section, and with +5%/loop checked the tempo creeps back up every pass until you're at full speed.

🎵 Play a file into the show: pick any audio file — it plays out loud AND drives the live light show at the same time. Fully internal: no mic, no dialogs, works on iPhone/iPad too. The 🕐 sync slider nudges the speakers a hair later so the lights land exactly on the beat.

🎭 Performance mode: hides everything but the stage (great for gigs and wall displays) — tap ✕ to come back.

🦴 The Maestro: that's Bonethagoras in the bottom-left corner, and he keeps score — XP for playing, capturing and practicing, three quests a day, a 🔥 streak for showing up, and 🎖 badges to chase. Tap him for your rank, or read the 🦴 XP tab above for the whole thing. Nothing in the app is locked behind him; he's there for the fun of it.

🎉 Party (inside 🟢 Spotify): songs you split (or audit) keep their original recording — open the Spotify panel's light-show library and hit 🎉 ▶ Play all: the real songs play while their light shows run in sync, one after another. Each show remembers the view you watched it in; 🔀 shuffle and 🎭 performance mode make it a wall display. Spotify playlists: shows whose titles match link themselves as the playlist plays (or tap 🔗 on a row while the track plays) — from then on the lights follow the playlist automatically, even shuffled, each song in its remembered view. Taking it with you: the ⇪ and ⇩ buttons under the show list pack everything — every light show plus its recording — into one .ladderlib file, and unpack it again somewhere else. Carry a set to the venue's laptop, keep a backup, hand a friend your shows. Nothing goes to a server; the file lands in your Downloads and it's yours.

📲 Install it: on the real site, use your browser's Add to Home Screen / Install — The Ladder becomes a real app that works offline, on iPhone, iPad, Android, Mac, or PC. No app store needed.

🏛 Bonethagoras of Samos & your XP

The dog in the bottom-left corner is Bonethagoras of Samos — laurel crown, lyre, and the right triangle that bears his name. He watches what you do and hands out XP for it — playing a song, capturing one, practicing, exploring a view you've never opened. Tap him to see your rank, today's quests, and your badge shelf.

Ranks. XP adds up into fourteen ranks, starting at Tone-Deaf Pup and ending at The Maestro's Equal. The bar under his name fills toward the next one; when it tops out he spins, confetti falls, and he tells you something Pythagoras would have said. Nothing is locked behind a rank — it's just a record of how much music you've put through the thing.

📜 Daily quests. Three every day, 15 XP each: play a song, visit three different views, and add a show to your library. Do all three and the Perfect Day bonus lands on top. They reset at midnight, your time.

🔥 Streaks. Show up on consecutive days and the check-in bonus grows — a little more each day up to a week and a half out. Miss a day and it starts over, so the streak is really just "did you touch an instrument today."

🎖 Badges. Twelve of them, and the locked ones stay visible in the panel so you can see what's left — hover any badge to read how to earn it. A few are easy (Graduate: finish the 🎓 Tour · First Light: capture your first Spotify song), a few take real playing (Woodshedder: work a song back up to full speed in Practice · Blue Note: light up the 7th harmonic · Full Spectrum: light all eight partials at once), and two take patience (Week of Fetch and Moon Dog — 7- and 30-day streaks).

◎ Wheel

The main light show. Each ring is one layer of the music, centre → out: And it's live — here's how to read and steer it: With 🔓 Lock Tonic on, Do stays at 12 o'clock and everything is read relative to home.

🎧 "listening…" and the striped cells. Before the app is sure what key you're in, it doesn't guess — the readout says listening… and each note you've played splits into stripes, one for every flavour that note could still belong to. Play a few more notes and the impossible flavours drop away, the stripes thin out, and when one is left the key settles on its own. Already know the key? Drag the inner ring to your home note (or hit 🔓 Lock Tonic) and the stripes go away immediately.

✦ 5ths

The same wheel, reordered by the circle of fifths — neighbours are a fifth apart, so closely related chords and keys sit next to each other and progressions sweep around the circle instead of jumping. Colours don't change: a note keeps its job colour no matter where it sits on the wheel. All wheel gestures (drag rings, tap chord cells) work the same here.

⊞ Octave

One octave, Do (home) always leftmost, climbing to the right. Every octave folds into these same 12 columns. Rows light for key · chord · bass · melody — the same layers as the wheel, just unrolled into a line. Click a column to move Do; the dropdown picks the flavour. The clearest view of where the two touching joins (blue→purple, orange→yellow) sit inside the scale.

🎹 Piano

The full 88 keys, A0–C8. Every key wears its job colour (grey = not in the song), and the actual sounding notes light — melody, bass, and each voiced chord tone — at their real register. Use this when register matters: watch a bass line live in the left half while the melody works the right.

🎸 Guitar

A standard-tuning (EADGBE) fretboard, every position wearing its job colour. Labels pick one realistic hand position per string (X = nothing on that string). The 🎯 toggle switches what lights: Melody — exact pitch lights only the notes actually played; Chord lights every octave of each sounding note, so a C chord paints all the C·E·G up and down the neck — a live scale-shape map.

🎻 Strings

Same as the guitar view, for fifths-tuned instruments. The 🎯 Melody / Chord toggle is shared with the guitar view — set it once, both fretboards follow.

🎸 Band — every string instrument on one page

With a song loaded, every voicing gets its own neck — the banjo part on a banjo, the fiddle on a mandolin (guessed from the track name). Tap a part’s chips to move it to a different instrument, or onto several at once. No song → full-mix necks: bass · guitar · mandolin (+ mandola · banjo · uke). Each part’s row of chips picks its instrument(s): learn the banjo part on guitar, or show it on banjo and guitar side by side. ⊞ Merge collapses everything onto shared full-mix necks; each neck also keeps its own draggable capo.

🎶 Harmonics — why notes have colour

Every real note is a stack of overtones: the note itself (the root), an octave up, a fifth above that, and on up. This view draws that stack from the actual audio, left to right like recording software — live input gets one lane per instrument, playback shows the whole output. Each bar stands at its partial’s real measured frequency: height = how loud it actually is, colour = the note it lands on, grey = between the cracks. Labels say what each partial is (root · 8ve · 5th · 3rd · ♭7) and how many ¢ it drifts — the amber ties show the drift as a gap you can see. Watch h7 land famously flat. Reading the levels: the faint horizontal lines behind the bars are loudness marks — the same ones a recording engineer reads — so you can see how much quieter each overtone is than the root instead of guessing. The thin line resting on top of each bar is its loudest moment just gone: it hangs for a second, then sinks, which is how you catch a partial that flashed past too fast to see. Nothing to switch on, it's simply there. Touch it: tap any bar to hear that partial alone, or drag across the stack to arpeggiate the series. The readout counts your series N/8 — light all eight and it turns gold. Instruments differ exactly here: a banjo piles energy into the high partials, a flute keeps almost everything in the root — this view IS the sound of an instrument, drawn.

🌀 Spiral

The 88 keys wound into an octave-aligned spiral. Watch melodies climb the coil and chords light matching spokes at different radii — the clearest picture of “same note, different register.”

▭ Bands

The most condensed view: three big colour fields — melody · chord · key — each showing its current colour and name. No geometry, just the three layers at maximum size. Made for distance: a projector, a second window across the room, or ambient light while you play.

∿ Freq

A log-frequency ladder: each rung's height is its real pitch under the active tuning system — pick equal temperament, just intonation, Pythagorean, or meantone, and set the A4 reference. Each diatonic rung is labelled with raw Hz and its cents deviation from equal temperament; the dashed ghost is where ET would put it — above, just intonation tunes Mi 14¢ sweeter (lower) than ET. Turn on ◉ drone to hold the tonic and hear the temperament beat against the melody.

∑ Math

Left: a static reference — the spiral of fifths and the commas where the systems fail to close. Right: a live table of the intervals sounding right now: Each pair shows its ratio in the active tuning, its cents vs equal temperament, and its beat rate — where temperament stops being theory and becomes something you can hear. Updates every frame.