Notewright

How Notewright works

What happens behind the buttons: how chords are represented and analysed, how progressions are generated, how voicings and guitar shapes are chosen, how the sound is made, and how the files are written. Everything described here runs in your browser.

The big picture

The whole app is one HTML file with no build step and no libraries. The page, the music theory engine, the synthesizer and the file writers are plain JavaScript, so it works offline once loaded and can be hosted anywhere, including GitHub Pages.

Chart (chords + beats)→Analysis→Swap ideas & explanations→Voicing planners→Sound, MIDI, MusicXML

State lives in the browser’s local storage under a few keys: changes-v1 (the current chart and settings), changes-library-v1 (saved progressions), changes-quiz-v1 (quiz score), and small layout preferences such as the view, open tabs and whether the text editor is open. Nothing is sent to a server.

How a chord is represented

Pitches are pitch classes 0–11 (C = 0). A chord in the chart is a root, a quality, an optional bass note (for slash chords) and a length in beats; a blank slot has no root. Sections, line breaks, locks, pinned shapes and key changes are extra fields on the same object.

Key changes. The chart has an opening key and mode; any chord that starts a bar can carry a new key and mode, which holds until the next change. The theory functions all read a single current key, so each one is run inside the key in force at the chord it is looking at: the current key is swapped in, the work is done, and the opening key is always put back, even if something goes wrong. That one rule gives spelling, Roman numerals, analysis, tension, swap ideas, explanations and the chord picker their local key without each needing to know about key changes. Recolouring and restyling run section by section in each section’s key, and Regenerate unlocked builds in the opening key and then moves each section’s new chords by the same distance as its key.

There are 55 qualities, each a list of intervals above the root (for example maj7 is 0, 4, 7, 11 and 13 is 0, 4, 7, 10, 14, 21), plus which notes may be left out when voicing (usually the 5th, and the 9th for 11ths and 13ths). They are grouped into the families you see in Chords allowed. About 190 spellings map onto them when reading text: Δ, -7, ø, 7(9), add2 and so on. Chord roots take their letter from the scale degree, so ♭VI in G is E♭, not D♯. A chord’s own notes, and a slash bass that is one of them, are then spelled up from its root: in C major, E7 is E G♯ B D and its first inversion is E7/G♯, even though G♯ alone would be A♭ in that key.

Note names follow the scale degree rather than a fixed sharp or flat table, so the ♭VI of G is written E♭, not D♯, and chord tones in explanations are named by their degree in that chord (the major 7th of E is D♯).

How a chord’s job is decided

Every chord is classified against the current key and mode. The first rule that matches wins:

  1. In the key: all its core tones (not counting upper extensions) are in the scale.
  2. Secondary dominant: a dominant-type chord whose resolution, a 5th below, is in the key (written V7/ii and so on), or a major triad doing the same.
  3. Borrowed: all core tones fit a parallel mode on the same tonic, tried in the order Aeolian, Dorian, Mixolydian, Phrygian, Lydian, Ionian, harmonic minor, melodic minor, Locrian.
  4. Tritone substitute: a dominant that slides down a half step into a chord of the key; leading-tone diminished: a diminished chord that climbs a half step into one.
  5. Chromatic: anything else, with special notes for augmented and diminished 7th chords.

Roman numerals use upper case for major and lower case for minor chords, with ♭ and ♯ for chords off the scale. The tension curve scores each chord from its category, its distance from the tonic (dominant chords score highest) and its quality (dominant, diminished, augmented and altered tones add tension).

How song form works

The chart stays one list of chords; a section label is stored on the chord that starts it (at a bar line), and a section runs to the next label. Each section gets a fingerprint: its chords’ roots, types, bass notes and lengths. A section whose name (ignoring a trailing number, so “Verse 2” is a Verse) and fingerprint match an earlier one, and, when the melody lane is showing, whose stretch of the tune matches too, is a repeat. Folding skips its bars when the chart is drawn and puts a single line in their place; playback and export never see the fold.

Linking compares the chart with its state just before the last edit (the top of the undo history). If sections are the same in number and name, and within a group of sections that matched before, exactly one has changed, its chords are copied over the others, keeping each copy’s own label, line break and key change. With a tune present the copy is made only if the edited section kept its length, since the tune is stored by beat and would otherwise shift. Undo restores the state before the edit, copies and all. Repeating a section copies its chords and its stretch of the tune, and inserts the tune at the same place, so everything after it moves along together.

How the melody is stored and coloured

A second list, alongside the first, holds the note on the “and” of each beat (the second half of a split beat), or nothing. Everything that works by beat (the colours, harmonizing, the arrangers’ moments, the piano parts’ gaps) reads the note on the beat, so an “and” acts as a passing note. Playback, the tune’s own line in an arrangement, MIDI and MusicXML (which counts in half beats) play and write it as written. Typed bars are fitted by ranking the beats: strongest first (the downbeat, then the meter’s accents in order, then the rest) to place fewer notes than beats; weakest first, from the end of the bar back, to choose which beats to split when there are more. Notes typed without octaves go in the octave nearest the note before, between E4 and G5.

The melody is a list with one entry per beat of the chart, counted from the start: a MIDI note number starts a note, a hold marker continues the note before, and an empty entry is a rest. It is kept apart from the chords, so editing chords never rewrites the tune. Each note is compared with the chord sounding on its beat, in the key in force there: a note in the chord’s triad or 7th (or its bass) is a chord tone; one of its upper extensions or another note of the key is a colour note; anything else is a clash if it falls on the downbeat or an accented beat of the meter, and a passing note otherwise. A newly entered note goes in the octave closest to the note before it, kept between G3 and C6. Harmonizing a selection runs the same harmonizer as the text box, on whole bars of the lane, and the result replaces exactly those bars, trimming any chord that runs into or out of them.

How melody paths are measured

Break away compares your tune with the original bar by bar, in five layers, and averages each. Every layer scores 0 to 1, and the panel shows it as a word: very close (.85 up), close (.6), some way off (.35) or far.

A layer is named as a giveaway when it is .8 or more and well above the rest. Paths are built from the original’s style, which is its note lengths, off-beat share, range, leap size, scale and phrase lengths. A path is listed only if its result fits that style and moves a layer it changes further away, so a tune of only quarter notes gets few rhythm paths.

How progressions are generated

Moods and genres each hold short progression templates written as Roman numerals, each tagged with the mode it lives in (for example Blues has I7 IV7 I7 V7 in Mixolydian). Generate then works in stages:

  1. Choose a template. With only a mood, from the mood’s templates. With genres, from the genres’ templates that sit in one of the mood’s modes and in its main major or minor family; if none fit, the mood’s templates are used and coloured in the genre’s style.
  2. Fill the slots with chords in the key, repeating the template to the chosen length and rhythm.
  3. Surprise. The Predictable ↔ Surprising dial sets how often a chord gives way to a secondary dominant or a borrowed chord, and at higher settings a tritone substitute or a chromatic mediant. The first chord and locked chords never change.
  4. Colour. Each genre has a style: how far it climbs the colour ladder (triads, 7ths, extended chords) and how readily it uses sus, add, extended, altered, power and slash chords. When several genres are picked, the one that supplied the template leads and the others add their colours at half strength. Jazz-like styles may also insert ii–V approaches and tritone substitutes.
  5. Respect the limits. Every chord is stepped down a fixed ladder until its type is in Chords allowed (13 → 9 → 7 → triad, add9 → triad, and so on). “Let the genre choose” swaps in the genre’s own families for this step only.

Regenerate unlocked builds 40 candidates with the chart’s slot lengths, pastes the locked chords back in, and keeps the candidate whose chords best fit the locked chords’ key and lead into and out of them (falling 5ths and half steps score highest; repeating the same chord twice scores lower).

The melody harmonizer scores chords against each segment of the melody (triad tones count most, a 7th half as much, other notes against the chord count against it, and downbeats count double), then finds the best path through the segments with dynamic programming, rewarding a tonic start, a tonic ending and V→I. It repeats the search with penalties on chords already used, to find three to five different answers, and ranks them by how many strong-beat notes are chord tones.

How swap ideas explain themselves

Swap ideas come from several generators: chords in the key that share notes with the original, other qualities on the same root, chords borrowed from parallel modes, chords that point at the next chord (dominants, ii–V pairs, backdoor and diminished approaches), symmetrical diminished and augmented chords, chromatic mediants, and jazz reharmonizations. Each idea then gets:

How the arrangements are voiced

The chart is cut into moments: wherever a chord starts, a tune note starts, or the tune rests. For each moment the arranger lists the chord sets a style allows, each with a cost. String quartet and Choir use the chord as written. Barbershop uses the chord cut to four notes; a plain triad may also ring as a dominant 7th, and a tune note outside the chord brings in the four dominant 7ths that contain it, plus a diminished 7th. The cheapest of those is the chord’s own 7th, then its dominant, then the dominant of the next chord.

Every voicing of each set is then listed within the parts’ ranges: relative to the tune (violin 2 within an octave under it, the tenor up to a sixth above), and absolute for the cello and bass. Each voicing is costed for a missing 3rd, 7th or bass note, doubled notes, gaps wider than an octave between upper parts, minor 9ths between parts, and, for barbershop, a bass off the root or fifth or a stack wider than an octave and a fifth. Each move between moments is costed for how far every part moves (the bass is allowed bigger leaps) and for parallel fifths and octaves. As for the piano, a Viterbi search picks the cheapest path through the whole chart.

Each part has a comfortable range from its voice type (or its instrument for the strings). The search lets a part go up to three half steps outside it, at a cost that grows with every half step, and drops the limit only if nothing fits at all. Barbershop chooses men’s or women’s voices by which lead range leaves fewer tune notes outside it. The range check counts the notes still outside; it offers the tune an octave up or down when that leaves fewer outside, and the transposition from five half steps down to six up that leaves the fewest, assuming the parts move with the chart.

Explaining a moment. Every cost is recorded with its reason as a phrase (“leaves out the 3rd (E)”, “has parallel fifths between the Violin 1 and Cello”). With the chosen voicings around it held in place, the chosen voicing must be the cheapest in its spot, since otherwise swapping it would lower the total. So the card ranks the other candidates for that moment by their own cost plus the moves into and out of them, takes the cheapest as the next best, and compares the two reason by reason: the biggest differences against it become “it loses because…”, and the biggest one in its favour becomes “even though…”. In a Try another version the random noise can make the next best slightly cheaper, and the card says so. A dominant borrowed from another key is spelled in that key (E7 with G♯ in C major).

The two jazz styles are built rather than searched. The chord is cut to four notes keeping the 3rd and 7th, and a triad gets its 6th (major) or 7th (minor). A tune note that is a tension replaces the chord tone a whole step below it (a 9th replaces the root, a 13th the fifth). A tune note a half step above a chord tone is an avoid note, and is harmonized with the diminished 7th chord built on it. The other three notes are stacked straight down from the tune within its octave; drop 2 takes the second note from the top down an octave. Try another reruns the search with seeded random noise added to the costs (and, for the jazz styles, swaps between 6ths and 7ths), so each version can be heard again.

Orchestra runs the string quartet arrangement and builds on it. The tune and the quartet’s lines stay. The flute copies the tune an octave up, or in unison above C7. The violas’ line is split into one note per beat, and the double basses copy the cellos an octave down, or in unison below E1. The horn takes, at each moment, the chord’s 3rd or 7th (or 5th) nearest its last note, below the tune and not on a note the strings already hold, from F3 up if it can. The clarinet looks for the same gaps the piano parts use, at least two beats where the tune holds or rests, and steps through the key’s scale onto the next chord’s 3rd: up from below the tune when that stays above G3, otherwise down from above it. The explanation card runs the quartet’s explanation for the moment and adds each section’s note at the tapped beat, with its job and how it moved from the beat before.

Each part becomes a line of notes: the tune keeps its own rhythm; the strings join a repeated note into one held note, and the singers re-sing it with each new tune syllable. Playback uses one tone with a different envelope per style: a slow swell and long release for strings, a short decay and early release for close harmony.

How the Broadway and jazz piano parts are planned

Both piano parts are planned over the whole chart at once, as timed events for a bass hand, a left hand and a right hand, plus a list of “devices” with their reasons for the LH and RH lanes. For each chord, the left hand chooses the notes the style uses (3rd, 5th and 7th, a 6th on a Broadway major triad, a major 7th on a jazz one, the 9th, and the 13th on a dominant) and stacks them in the middle of the keyboard nearest the previous stack.

Broadway stride plays the bass (alternating root and fifth) on the meter’s accented beats and the chord on the others. If a chord lasts a bar or more, its last beat or two may join it to the next chord: a diminished 7th a half step under the next root when that root is a whole step up, a two-note bass walk-up when it is a third or fourth up, otherwise the next chord’s dominant 7th. The passing and approach chords are used only when the tune’s note on that beat belongs to them.

The jazz part plays the root low, then a rootless voicing in one of two orders: 3rd–5th(or 13th)–7th–9th from the bottom (A) or 7th–9th–3rd–5th(or 13th) (B), choosing whichever moves less from the previous voicing. A dominant falling a fifth is replaced over its second half by the dominant a tritone away (it shares the 3rd and 7th) unless the tune sits on the original 5th. A short dominant falling a fifth instead takes ♭9 and ♭13.

The right hand looks for gaps in the tune: after each tune note, the beats until the next one, if there are at least two. With no tune it uses the last two beats of every second bar. It fills the last two beats of a gap, landing on the next chord’s 3rd as that chord starts (briefly, if the singer comes back in on it). Broadway runs up through the current chord with a chromatic note just under the target. Jazz runs down the scale and then encloses the target: the scale note above, then the half step below. Jazz eighth notes are swung (the off-beat at two thirds of the beat), Broadway ones only a little. Broadway puts a growing tremolo under the tune’s highest note when it lasts two beats or more, and rolls the final chord across the keyboard.

How piano voicings are chosen

For each chord the planner lists candidate right-hand voicings: every rotation of the chord tones (dropping optional tones on big chords) starting from several octaves, plus drop-2 versions. Each candidate has a cost for sitting too high or too low, and each move between chords costs the total distance the voices travel. A Viterbi search (dynamic programming over the whole chart) picks the cheapest sequence; because the chart loops, it also accounts for the move from the last chord back to the first. The bass line takes the octave of each bass note closest to the previous one, near the middle of the bass range. A pinned voicing becomes the only candidate for its chord, and the planner works around it.

How guitar shapes are found

Shapes are searched, not looked up. For each four-fret window up the neck (frets 1 to 15) and each string, the search tries muting it, playing it open, or fretting a chord tone, then keeps shapes that:

Shapes are scored for position, missing strings, fingers, barres, stretch and open strings ringing against a high hand. Standard grips (open chords and their barre forms, plus each tuning’s own common shapes, 43 for standard tuning) get a bonus and always make the list, which then keeps the easiest shape for each bass string and region of the neck, up to 16.

The smoothest path runs the same Viterbi search over the chart’s shapes, with the hand’s movement along the neck as the cost between chords. Every tuning (11 of them) uses the same search, so a chord always has shapes in it.

Finding the easiest tuning

For each tuning at each capo position from 0 to 7, the smoothest path is found again and scored for playing effort: fingers, barres (a one-finger barre across neighbouring strings counts as one), stretch, high positions, muted strings and hand movement. Retuning and using a capo add small fixed costs. Standard tuning is recommended unless another tuning is at least 12% easier; a capo is suggested only if it saves at least 10%.

How the sound is made

Sound is synthesized live with the Web Audio API; there are no recordings. The piano is a triangle wave with a quiet sine an octave up, through a filter that darkens as the note decays. The guitar is a sawtooth and a slightly detuned triangle through a filter that closes quickly, so each string starts bright and mellows, with low strings ringing longer. Chords are strummed by staggering the notes by a few milliseconds.

A playing style turns each chord into timed events: for example, the guitar strum pattern hits down on the beats and up on the off-beats (down, down-up, up-down-up in 4/4), and fingerpicking alternates the thumb between the two lowest notes under the treble strings. Playback adds a little random variation in timing and loudness; MIDI export writes the same events exactly on the grid.

Notes are scheduled slightly ahead on the audio clock for steady timing. When the chart loops, the next pass is queued half a second before the current one ends and starts on the exact same clock time, so there is no gap at the seam and notes still ringing carry over it. On iPhone and iPad, Safari normally treats web audio as “ambient” sound that the silent switch mutes, so the app marks its sound as media playback (through the audio session setting where Safari supports it, and a silent looping audio clip otherwise), and starts the audio engine inside your first tap.

MIDI in. Through Web MIDI the app listens to note-on and note-off messages from the chosen input. It keeps the set of keys held down and remembers the fullest set held since the keyboard was last silent; when every key is up, that set is the chord, so rolling into a chord or lifting fingers unevenly still gives the whole chord. It is named by the same matcher as the Chord finder, which scores every root and chord type against the notes (missing notes, a missing root, a bass that isn’t the root and rarer types all cost a little) and lists the best. Live MIDI out works the other way: during playback each chord’s played voicing goes out on channel 1.

Numerals in, the progression in words, ideas across the chart. Typed numerals are turned into chords in the key in force at that line: the numeral picks a degree of the major scale on the tonic (with ♭ or ♯ moving it a half step), case picks major or minor, and anything after it is read as a chord type; V7/V builds the V7 on the degree the second numeral names. A Nashville b7 could also be a B7 chord written in lower case, so it is read as a number only when the chart has other plain numbers. When chords typed by name start a chart, its key is guessed by scoring all 24 major and minor keys: 2 for each chord in the key, 1 for a secondary dominant, ½ for a borrowed chord, and 1½ for a tonic chord at the start or end. The sentence under the chart comes from the same per-chord analysis as the colours. The three ideas come from running the Swap ideas engine on every chord (each in its own key) and taking the top idea of each kind, mixed so that the three differ in kind and chord.

Tune ideas. The tune is read as notes (start, length, pitch). A note starting on a strong beat that is neither in its chord nor in the key is a clash: the nearest chord tones within a major 3rd above and below are offered, and so is moving the note to the “and” with the nearest chord tone on the beat. Two notes in a row a 3rd or more apart, where the first lasts until the second, get a note of the key on the “and” of the beat before: the one in between for a 3rd, the one nearest the middle for a wider leap. A note held two beats or more on a beat of its own gets the next note of the key above it on its “and”, then itself again. Ideas are worked out afresh each time the pad draws, so a used idea drops off the list.

How the files are written

Inside the claude.ai viewer, files go through the platform’s save dialog, which accepts only some file types, so MIDI and MusicXML are delivered inside a .zip there.

How it’s tested

An automated smoke test drives the app in headless Chromium and WebKit, including an emulated iPhone. It checks, among other things:

The MusicXML output, piano and arrangement scores alike, was also read back with the music21 library to confirm bar lengths, chord symbols, keys (including key changes), clefs, meters and pitches.

Honest limits