URL params reference

What the user does in the exercise: piano (live MIDI play), naming (multiple-choice naming), ear (audio recognition), jumper (metronome rhythm game).

Default: "piano"

Musical subject the exercise draws from. Tab order (chords → scales → progressions → songs → melodies) drives the /preferences segmented control.

Default: "chords"

Root key of the exercise. 12 chromatic spellings + 5 flat enharmonics (Db, Eb, Gb, Ab, Bb) for scale tonics that read more naturally with flats.

Default: "C"

Scale type built off the root key.

Default: "major"

Inversion indices to drill, comma-separated in the URL (e.g. inv=0,1,2).

Default: [0]

Chord voicing. singleNotes / triads / sevenths apply to both chord-pool and scales subjects; ninths is scales-only and drills the diatonic 9th on each degree (not available for harmonicMinor or the non-diatonic scales). intM2..int8 are 2-note interval voicings (scales subject only): the scale degree is the lower note, the named interval is added above. progression is reserved for the deferred Roman/Arabic custom progression mode.

Default: "triads"

Which hand the exercise practices. "any" accepts either one-hand or two-hand play (single chord or chord doubled across octaves).

Default: "right"

When hand="both", what the left hand plays alongside the right-hand chord: "same" = the chord doubled, "root" = only the chord root note (inversion-agnostic), "lowest" = only the bass (inversion-aware — in root position root IS the lowest), "octaves" = the root note doubled (two roots one octave apart), "fifths" = root + perfect fifth (two notes), "nothing" = only the right hand grades. Ignored unless hand="both".

Default: "same"

Metronome tempo in beats per minute.

Default: 60

Time signature driving the metronome strong-beat accent. 4/4 and 3/4 accent beat 1; 6/8 is compound — accent on beat 1 (strong) and beat 4 (medium). Subject-invariant (all tabs), like tempo.

Default: "4/4"

Black-key spelling: always sharps, always flats, random per render, or auto-derived from the current scale.

Default: "auto"

When true, the MIDI evaluator demands the played chord to match the asked inversion (bass note matters); when false, any inversion with the same notes counts as a hit.

Default: true

Quality ids the random-draw pool may pick from (e.g. 0 = major triad, 7 = m7, 49 = single note). At least one must be selected.

Default: [0]

Pitch classes (0..11, C=0) allowed as chord roots when drawing. At least one must remain selected.

Default: [0,2,4,5,7,9,11]

Ninja mode (chords subject, piano activity): the user picks the exact voicing per hand via the ninjaLeft/ninjaRight step sets. While on, chordTypes / inversions / hand are ignored by grading and by the exercise identity, the question label shows only the root, and the keyboard hint marks both hands.

Default: false

Ninja mode: left-hand steps as semitone offsets from the right-hand root (members of NINJA_STEPS in $lib/music/chord/ninja; 0=root … 21=13th). The left hand sounds two octaves below the right root, so its steps can never collide with right-hand pitches.

Default: []

Ninja mode: right-hand steps as semitone offsets from the root (members of NINJA_STEPS). At least one step across both hands must stay selected; the UI enforces it and the engine falls back to a bare root.

Default: [0]

Specific Voicing (all subjects, piano activity): the user assigns generic chord parts (root/3rd/5th/7th/9th/11th/13th) to each hand and the drawn chord decides the exact notes. While on, hand / leftPlays / requireInversion / rootless / one-note are bypassed by grading; a part the drawn chord lacks is skipped, a part ticked in neither hand is omitted, and a chord with no assignable part grades as a normal full chord. Ninja mode wins over this in the chords subject.

Default: false

Specific Voicing: parts the LEFT hand plays, as degree numbers (1=root, 3, 5, 7, 9, 11, 13 — see VOICING_PARTS in $lib/music/chord/specific-voicing). The hint places them two octaves below the right-hand root; grading is octave-free.

Default: [1]

Specific Voicing: parts the RIGHT hand plays, as degree numbers. At least one part across both hands must stay selected; the UI enforces it and an empty pair falls back to normal grading.

Default: [3,5]

Draw order. `random` picks a random pick each draw (scales subject: natural degree order, random inversion per cell); `inOrder` walks the pool in order; `inOrderUpDown` / `inOrderUpDownPeak` walk up then back down (scales subject); `allInversions` drills every inversion of each degree (scales subject). `harmonized` is reserved and falls back to inOrder. `circleFifthsCW`/`circleFifthsCCW`/`chromaticUp`/`chromaticDown` are RETIRED (still parsed for old links/data): they normalize to `inOrder` + the matching `scaleAfterRepeats` direction.

Default: "random"

Scale mode for subject=scales — slug from the 20-mode V1 taxonomy (major..chromatic). Non-diatonic slugs (pentatonic*, blues, bebop*, chromatic) force voicing=singleNotes.

Default: "major"

For subject=scales, sequence=inOrder. `end` appends the tonic after the last degree before looping (resolves the scale). `top` (deferred, used by inOrderUpDown) repeats the peak before descent. `both` does both. `none` plays the bare degree list.

Default: "end"

Scales subject, sequence=allInversions only: play each degree's inversion run N times before moving to the next degree (per-degree loop). Absent/1 = one run per degree. 1..100. Optional so it stays absent on the vast majority of exercises. (Passes before the "Then" action are `scaleAfterRepeatsCount`.)

Default:

Legacy (scales subject): the old all-keys "only flawless" flag. Migrated into `scaleAfterRepeatsFlawlessOnly` when it arrives with a retired all-keys sequence; otherwise ignored.

Default:

Scales subject only: what happens after `scaleAfterRepeatsCount` completed passes through the scale (any sequence). done = mark the exercise as done (records a completion, once per session); cofCW = next key around the circle of fifths clockwise (C→G→D→…); cofCCW = counter-clockwise (C→F→Bb→…); chromaticUp = semitone up; chromaticDown = semitone down. Independent of the progressions `advanceAfterRepeats*` fields.

Default: "done"

Scales subject only: how many completed passes trigger `scaleAfterRepeats`. 1..99. Default 1.

Default: 1

Scales subject only: when true (default), only FLAWLESS passes count toward `scaleAfterRepeatsCount` and a flawed pass restarts the count (N clean passes in a row). When false, every completed pass counts.

Default: true

Verbatim Roman/Arabic numeral progression text (e.g. "I vi IV V" or "1.2 5 6.2 4") for subject=progressions. Empty value triggers auto-seed to "ii V I" when subject flips to progressions. Per-chord dot-notation inversion overrides the global inversions option.

Default: ""

Verbatim chord-name list (e.g. "D, G, C" or "Am.1 Cmaj7 F#m7b5/A C/E") for subject=songs. Tokens split on whitespace, comma, or colon. Each token accepts dot-inversion (e.g. "Cm7.2") and slash-bass (e.g. "C/E"). The `|` token marks a bar boundary and is preserved in the parsed list. Reused by the V1-port chord-text parser (`parseSpecific`).

Default: "D, G, C"

Songs subject only: when true, each parsed chord in `specific` is graded as a single-note exercise on its root (quality=49, inversion=0). Lets a "C F.2 G" string drive a C → F → G single-note drill instead of full chord voicings. Ignored for other subjects.

Default: false

Songs subject only: when true, the chords from `specific` keep their root + quality but IGNORE any per-token inversion (C/E, C.2 → C) and are instead drilled through the selected `inversions` set. The play pool = {parsed chords} × {selected inversions} (a pair is skipped when the inversion exceeds the chord quality’s max), walked per `sequence` (random = uniform draw; in-sequence = inversion-major: all chords at the lowest inversion, then the next). Overridden by `songsSingleNotes`. Ignored for other subjects.

Default: false

Songs subject only: optional display title ("Artist - Song") carried from /songs or /editor via the ?title= param. Shown on the ExID card in place of the chord list. Display-only — deliberately excluded from the canonical exid hash (tab-fields) so it never changes an exercise’s identity, pet-name, or difficulty; it rides only in the ?d= slug. Optional so it stays absent (not "") on the vast majority of exercises.

Default:

Progressions subject only: when true, after `advanceAfterRepeatsCount` loops the exercise key auto-advances in the direction given by `advanceAfterRepeatsDirection`. When false ("Mark as done"), the same threshold records the exercise as done once per session instead. Ignored for other subjects.

Default: false

Progressions subject only: how many loops trigger the "Then" action (key advance when `advanceAfterRepeats` is true, mark as done when false). 1..99. Default 3.

Default: 3

Progressions subject only: how the key advances when the repeats threshold is hit. cofCW = circle of fifths clockwise (C→G→D→A→…); cofCCW = counter-clockwise (C→F→Bb→…); chromaticUp = semitone up (C→C#→D→…); chromaticDown = semitone down. Reuses the existing nextCofKey / nextChromaticKey helpers.

Default: "cofCW"

Progressions subject only: when true, only FLAWLESS loops count toward advanceAfterRepeatsCount — any miss resets the flawless progress, so the "Then" action fires after N clean loops in a row. Absent/false (default) = every completed loop counts regardless of mistakes. Optional so it stays absent on the vast majority of exercises.

Default:

When true, the metronome climbs ("tempo stepping") from progressiveTempoFrom to progressiveTempoTo in progressiveTempoStep increments, playing the current material progressiveTempoAfter clean repeats per rung before bumping up. On reaching the top rung it triggers the mode's natural advance (next key / scale) or a goal board (chords / songs) and resets to the bottom. Subject-invariant (all tabs). While on, it becomes the authority for rep-counting and advancement, suppressing advanceAfterRepeats / scaleLoopCount auto-advance.

Default: false

Progressive tempo: starting BPM (bottom rung of the ladder). 20..300.

Default: 60

Progressive tempo: target BPM (top rung, always played after the last full step). 20..300.

Default: 200

Progressive tempo: BPM increment between rungs. 1..200. Default 20.

Default: 20

Progressive tempo: how many clean (flawless) repeats to play at each rung before bumping up. 1..99. Default 1.

Default: 1

Progressive tempo: when a run of clean repeats is broken by a wrong chord, drop one rung (tempo -= step, floored at from) and restart the rep count for that rung. When false, a break only restarts the rep count without dropping the tempo. Default true.

Default: true

What the /app question label shows when subject is "scales" or "progressions". `chord` (default) keeps the chord long-name. `roman` shows the scale-degree Roman numeral ("ii", "V", "vi"; with a dot-inversion suffix like "V.1" when colorfulInversions is OFF). `romanQuality` adds the chord-quality glyph (UPPER for major, lower for minor, ° dim, + aug) when subject=scales AND the voicing is diatonic triads/sevenths; silently degrades to plain `roman` for progressions, single-note voicing, intervals, and non-diatonic scales. `arabic` shows the bare degree number. `function` shows the locale-aware function name. V1 had this as display-1/2/3 multi-checkboxes; V2 collapses them into one exclusive picker.

Default: "chord"

Melodies subject (/repeat): the level ladder, or the custom fields below. Ladder exercises ignore the other melody* fields.

Default: "levels"

Melodies custom mode: root key of the note pool. Own field, so a melody link never overwrites the Scales/Progressions key.

Default: "C"

Melodies custom mode: scale of the note pool.

Default: "major"

Melodies custom mode: note-pool width.

Default: "five"

Melodies custom mode: largest leap in scale steps, 1..7, or 999 for no limit.

Default: 4

Melodies custom mode: play by ear, hide the keys the app plays (doubles points).

Default: false

UI theme. `light` = Professional, `playful` = Playful. (The dark theme was removed; stored `dark` values fall back to light via catch.)

Default: "light"

Play a piano sample on every key click and MIDI noteOn.

Default: true

Piano-sample volume, 0–100. 0 silences the engine even when pianoSound is on.

Default: 70

Metronome click + visual-flash volume, 0–100. 0 silences the click; the visual flash still runs when metronomeStyle includes "visual".

Default: 50

Play a gong when an auto-advance changes the key (Scales all-keys walks + Progressions after-repeats).

Default: true

True once the user has explicitly picked a practice activity (preferences select or the J shortcut). While false, suggested-exercise cards may default to Naming on narrow/mobile screens with no MIDI; once true, the chosen activity is always honored.

Default: false

Keep the screen from dimming or locking while practicing (uses the Wake Lock API; silently ignored on unsupported browsers).

Default: true

Chord + note naming convention shown everywhere on screen.

Default: "american"

Keyboard-split point (MIDI note, inclusive) or null=off. When set, only MIDI notes on splitSide of this note are assessed; the other hand still sounds + records. Set via the / or \ shortcut.

Default: null

Which side of splitPoint is graded: right = notes >= splitPoint, left = notes <= splitPoint.

Default: "right"

Tint the chord-question block by quality (major, minor, dim, …) for visual recall.

Default: false

Show heart counter; lose a heart on miss, gain one every 5-streak. Reset on game-over.

Default: true

Simplified kid-friendly preferences UI (baby mode); advanced options hidden.

Default: false

When true, missing twice in a row only costs one purple heart; the second consecutive miss is forgiven (V1 strict-mode guard). Game-mode only.

Default: true

What extra HELD keys beyond the expected answer do to a match. The segmenter deliberately tolerates keys sustained across questions (common-tone legato); this decides how far that goes. any = a matching candidate wins regardless of what else is held (pre-2026-09 behavior); chordTones (default) = extras are fine while every held key is a correct pitch class (octave doublings, sustained chord tones) and one foreign pc fails as wrong-notes; strict = the held count must equal the expected count, any extra key fails as wrong-count. Applied to the graded side only — a keyboard split still exempts the other hand entirely.

Default: "chordTones"

V1 #o-20 parity. When true, the chord root is dropped from the expected pitch classes during evaluation, so a C major question accepts E + G alone. Single-note questions short-circuit (no-op). Inversion strictness is suspended in this mode — the bass becomes the lowest non-root note and the "wrong-inversion" outcome no longer fires.

Default: false

One-note mode. Whatever the exercise draws — a chord, a scale degree, a progression step, a song chord — the RIGHT hand only has to play the chord root; nothing else about the question changes (the same chord is drawn, named and hinted). The left hand is unaffected: `leftPlays` still decides what it owes. Wins over `rootlessMode` when both are on (rootless drops the note one-note keeps); a ninja pattern still overrides both. Single-note questions are unaffected.

Default: false

V1 #o-38 parity. When true and the subject is scales with sequence=inOrder, the chart is fed in growing chunks: a flawless full pass through the active chunk advances the chunk (per `chunkMode`). The chord-chart strip visualizes the active chunk via the existing selectedIndices highlight pipeline. User chart-clicks are suppressed while this mode is on.

Default: false

V1 #o-388 parity. Number of consecutive degrees in each chart chunk when `playInChunks` is on. Clamped to 2..7.

Default: 3

How the chart chunk advances per flawless loop. `cumulative` grows the chunk by one cell on each pass (V1 default — C → CD → CDE …). `window` slides a fixed-length window forward by `chunkLength` cells each pass (CDE → DEF → GAB …). Both wrap on overflow.

Default: "cumulative"

How a chart-chord selection survives key/scaleType changes. `any`: persist through manual and auto (loop) key/scaleType changes. `autoAdvance`: persist only through the loop auto-advance; a manual key/scaleType change clears it. `never`: clear on any key/scaleType change (legacy behavior). Selection always resets on voicing/scaleRepeat/progression changes that alter the cell set.

Default: "any"

Daily practice goal in minutes. The streak badge turns orange once today's practice time crosses this value. Set to 0 to disable the indicator.

Default: 15

Render inverted chords as slash bass (e.g. C/E) instead of "1st inv" pill. V1 parity with #o-23.

Default: false

Show inversion info in the chord chart labels: slash form (C/E) when slashInversions is on, else dot form (C.2). Off = plain chord names.

Default: true

Confetti burst on every correct chord, +1 heart gained, and level-over. V1 parity with #o-26. The library is lazy-loaded only when this is on. Default ON for everyone, but SUPPRESSED while the OS asks for `prefers-reduced-motion` and the user has not touched the toggle — see `fireworksChosen`.

Default: true

Set the first time the user works the fireworks toggle on /preferences (either direction), and by baby mode, which asks for the playful experience outright. Once set, the stored `fireworks` value is final and the OS `prefers-reduced-motion` setting stops suppressing the confetti.

Default: false

Chord-label rendering form. Short = "Cm7" / "Cmaj9"; long = "C minor 7" / "C dur9". V1 parity with #chord_names_0/1.

Default: "short"

"Mood" of the exid avatar. `identicon` = abstract geometric pattern (default); `bottts` = playful robot; `none` = hide the avatar/chip on every exid surface (cards, badges, footer). Same seed → same image per style.

Default: "identicon"

Show the human pet name (e.g. "Mighty Owl") on exid cards. Default on. When off, the card head-line drops the pet span and only the chord/scale info remains. The schema-driven slug + identicon are still computed; this only gates the visible label.

Default: true

Use per-inversion colors (root #111, 1st #82a905, 2nd #7952b3, 3rd orange) on the /app inversion pill, the chord-balls bass-note stroke, and the /preferences inversion buttons. When off, all inversions render in neutral black.

Default: true

How the /app metronome announces each beat: `audio` plays the click only, `visual` flashes the BPM number only, `audioVisual` (default) does both.

Default: "audioVisual"

When on, /app shows a row of upcoming chords (the queue) instead of just the current chord. The queue advances by one on every correct answer.

Default: false

How many slots the chord queue shows when chordQueueEnabled is on. Slot 1 is the currently-graded chord; the rest are the upcoming queue. 2..8.

Default: 4

Animate the queue shift after a correct answer (snappy ~120 ms slide-left + fade-in). Disable for a hard instant swap or to respect reduced-motion preferences manually.

Default: true

Repeat each chord N times before advancing (where N is `doubleModeValue`). Reinforces voicing + timing on the same chord before moving on.

Default: false

How many times each chord must be played in a row before advancing, when `doubleMode` is on. 2..10.

Default: 3

In `doubleMode`, count a wrong attempt as one of the N reps. Speeds up sessions by not punishing slips; off (default) means only correct answers count toward the rep target.

Default: false

Mark the chord root on the on-screen piano keyboard with the root color cue. Helps beginners locate the bass note at a glance.

Default: false

Show the chord name above the question on /app. Hide via the preferences toggle or by long-pressing the label.

Default: true

Show the ball-notes hint inside the answer panel on /app. Half of the hint TYPE pair behind the single Hints container on /preferences (B shortcut); at least one of the pair stays on, so the panel — and the Naming quiz question — is never empty. Hide via that control or by long-pressing the balls. Only consulted once `answerHintsChosen` is true — until then the screen width picks the default (narrow → off).

Default: true

Show the on-screen piano keyboard inside the answer panel on /app. The other half of the hint TYPE pair (K shortcut; see showAnswerBalls). Hide via the Hints container or by long-pressing the keyboard. Only consulted once `answerHintsChosen` is true — until then the screen width picks the default (narrow → off).

Default: true

True once the user has explicitly toggled either answer hint (balls / keyboard) on /preferences. While false, both default to OFF on a narrow screen and ON otherwise — a phone has no room to show the answer beside the question, and showing it there gave the answer away before the player had tried. Once true, the stored `showAnswerBalls` / `showAnswerKeyboard` values are honored on every device.

Default: false

In Scales / Progressions / Songs subjects, show the chord-chart strip — a horizontal row of every chord in the current cycle. Click a cell to restrict the draw pool to a subset (inOrder walks click-order, random picks within the subset). Hide via the /preferences toggle or by long-pressing the strip.

Default: true

Show the inversion pill (current chord inversion + hand icons) on /app across Chords, Progressions and Scales subjects, regardless of the notation/chord-label question mode. Colored by colorfulInversions when that option is on. Hide via the /preferences toggle or by long-pressing the pill.

Default: true

Keep the answer panel (balls + keyboard) visible at all times, not only after Space-to-reveal or a wrong attempt. The H shortcut toggles it; B / K choose WHICH surface the panel holds (at least one stays on). V1 `o-0` parity.

Default: false

Auto-show the answer panel once the player is NEAR DEATH — on the last purple heart, game mode only — and keep it up. Historic key name: the reveal-after-a-wrong-attempt it used to gate is now unconditional (a mistake always reveals the answer, V1 default behavior), so this box is the third of the three behaviors: default / always visible / auto on the last life. Renaming the key would break existing share links and synced states.

Default: true

When on, the random-draw weights drift toward chords you miss more often and away from chords you nail. Only effective when the exercise sequence is "random". See /chord-stats for the live ranking.

Default: true

Scale-note keyboard highlighting (scales subject only). `off` paints nothing; `keys` tints the whole white/black key behind every scale-degree pitch class; `bullets` marks each scale-degree key with a colored dot (green on non-root pitches, red on the tonic).

Default: "off"

Display piano fingerings (digits 1-5) on keyboard hints. Scales subject + singleNotes voicing only; mutually exclusive with hlType (engaging fingerings overrides scale tint).

Default: false

Visual instrument used by the chord-hint panel under the Q&A. `piano` (default) renders the existing PianoKeyboard SVG. `guitar` renders a 6-string fretboard via the svguitar library, with chord shapes sourced from @tombatossals/chords-db and matched to the exercise inversion. Both libraries are lazy-loaded so piano-only users pay zero bytes. Ukulele defers to Phase 2.

Default: "piano"

How the question is rendered on /app. `chordNames` (default) shows the chord label (e.g. "Am7"); `staff` shows the notes on a music staff (VexFlow renderer). Toggled with the N keyboard shortcut. When `staff`, see the staff* sub-options.

Default: "chordNames"

Staff layout when notationDisplay=staff. `off` = harmonic (notes stacked vertically as a chord); `asc`/`desc`/`random` = melodic (chord split into single notes laid out left-to-right in the chosen order).

Default: "off"

Staff notes rendered as quarter notes (default — filled noteheads with stems hidden) vs whole notes (open noteheads).

Default: false

When notationDisplay=staff, paint the root note of each chord in orange so the bass note stands out.

Default: false

Octave shift for staff rendering: -1 / 0 / +1. Default 0 anchors at middle C.

Default: 0

Show the clef glyph and the key-signature accidentals at the staff head. When on, per-note accidentals that the signature already covers are stripped, so diatonic chords read clean. Default ON — the per-key spelling pipeline relies on the user being able to see which signature they are in.

Default: true

Clef used for staff rendering. `auto` derives from the active hand (left → bass, right or both/any → treble). `treble` and `bass` force the choice.

Default: "auto"

Chord-naming (multiple-choice quiz) preferences — used when exercise.activity=naming.

Default: {"type":"chordName","keyClasses":"both","sort":"sorted","difficulty":"hard","distractorCount":5,"revealCorrectOnWrong":true}

Element-layout preferences for /app (3-column responsive grid).

Default: {"rotateStaff":false,"staffRotationDegrees":90,"chordInfoVisible":false,"autoHideNavFullscreen":true}

Reward-image preferences. V1 parity for `o-39 displayCats` + `o-40 rewardMilestones`.

Default: {"mode":"off","apiUrl":"","onlyMilestones":false,"milestoneInterval":100}

Ear-training (audio quiz) preferences — used when exercise.activity=ear.

Default: {"playbackStyle":"melodic","notePace":"normal","hideStyle":"question","allowMidiAnswer":true,"autoPlayOnDraw":true,"holdMs":1500}

Jumper-game preferences — used when exercise.activity=jumper.

Default: {"drawCues":true,"obstacleHeight":40,"beatsPerObstacle":4,"failureBehavior":"miss-only"}