Building Chord Progressions

The chord palette knows your key, watches your melody, and ranks every suggestion by what fits the moment you're in. You pick. It adapts.

What you'll learn

• How the chord palette organizes chords into In Key, Borrowed, and Secondary Dominants
• How ghost chord slots and suggestion chips guide your next chord choice
• How melody-fit scoring ranks chords by the notes already on the grid
• How Auto Chords generates a full progression from your melody in one click
• How to add extensions (7th, sus4, add9) and browse voicings
• How to edit, move, resize, and roll chord boundaries on the timeline
• How voice leading optimization smooths piano voicings across a progression

---

The last four chapters built up the lyric side of the timeline: sections, the beat grid, writing words, word tools, and syllable splits. This chapter is about the other lane. Every section in Song Cage has a chord lane above its lyric lane, and the chord palette is how you fill it.

Chapter 2 introduced the palette at a glance. Chapter 4 showed how chords can be a starting point. This chapter covers the mechanics: how to place chords, how the palette ranks them, how to shape their sound with extensions and voicings, and how to edit a progression once it's on the grid.

9.1 The three tabs

The chord palette lives in the left sidebar, under the Chords tab. It organizes every chord into three sub-tabs based on their relationship to your current key.

In Key

The In Key tab shows the seven diatonic triads for your current key and mode. In A minor, that's Am, Bdim, C, Dm, Em, F, G. In C major, it's C, Dm, Em, F, G, Am, Bdim. Each chord chip displays a Roman numeral label (i, ii°, III, iv, v, VI, VII in minor; I, ii, iii, IV, V, vi, vii° in major) so you can think in scale degrees.

These are the chords that belong to the key without any borrowing or alteration. Most progressions stay mostly here.

Borrowed

The Borrowed tab shows chords drawn from parallel modes. In a major key, borrowing pulls from Aeolian, Mixolydian, Dorian, Lydian, and Phrygian. In a minor key, borrowing pulls from Ionian, Harmonic minor, and Phrygian.

Each borrowed chord is labeled with its source mode so you can see where it comes from. A bVII in C major is borrowed from C Aeolian. A iv in A major is borrowed from A Dorian. These chords add color without leaving the key entirely.

Secondary Dominants

The Secondary Dominants tab shows V chords that resolve to non-tonic targets. V/ii resolves to the ii chord, V/vi resolves to the vi chord, and so on. These create momentary key shifts that pull the listener toward a specific chord before the key reasserts itself.

Secondary dominants are labeled with both their chord name and their resolution target (e.g., "D7" labeled "V/vi" in C major, resolving to Am).

When a section is in Wander mode (no key locked in), these three tabs are replaced by a chromatic chord grid. See Chapter 11 for the Wander UI and how key inference works there.

Chord search

Click the search icon (🔍) in the palette header to open the chord search. A text input labeled "Type any chord... (e.g. Bbm7)" lets you enter any chord by name. This is for the moments when you want something specific that isn't in your current key's palette. Type "Eb" and it appears as a chip you can place on the timeline like any other chord.

9.2 Placing a chord

There are three ways to get a chord onto the timeline.

Ghost chord slots

Click an empty beat position in the chord lane and a ghost chord slot appears: a dashed-border box with a pulsing highlight. This is the pending target. The palette immediately recalculates its suggestions for that position, and suggestion chips appear inline near the ghost slot.

Click any suggestion chip to place that chord. Or click a chord chip in the palette. Or drag a chord chip from the palette onto the ghost slot. All three produce the same result: a chord block at that beat.

Drag from the palette

You can also drag a chord chip from the palette directly onto any position in the chord lane, bypassing the ghost slot step. The chord snaps to the beat grid when you drop it.

Sheet view

In Sheet view, small + markers appear between words in each lyric line. Click one to set a pending chord target at that word boundary, then pick a chord from the palette. Song Cage places the chord above the word and, if the lyric block spans multiple words, splits it at the nearest word boundary so the chord aligns cleanly.

Audition mode

When you place a chord (by any method), it enters audition mode. The chord block highlights, the mini fretboard or keyboard in the edit popover shows the default voicing, and you can preview the sound by clicking the speaker icon. A waveform icon next to the speaker toggles preview notes individually, which plays palette and timeline chord clicks one note at a time so you can hear each voice.

While a chord is in audition mode:

• Left/Right steps through the palette in render order (Fits Melody / Replace, then In Key, Borrowed, Secondary Dominants), one chip at a time. Clamps at the first and last chip — no wrap.
• Up/Down moves to the chord directly above or below in the palette grid. Same column, next or previous row in the current section, flowing into the next non-empty section at the same column when you reach a section's edge. Clamps at the top and bottom of the panel.
• Shift+Left/Right cycles extensions on the current chord (triad → 7 → maj7 → 9 → sus4 → sus2 → add9 → 6, filtered to what's valid for the chord's quality).
• Shift+Up/Down cycles voicings of the current chord (Up = next voicing).
• Enter commits the chord.
• Escape cancels (removes the chord if it was newly placed, or reverts to the previous chord if you were replacing an existing one).

When you double-click an existing chord, audition opens at the first chip in the palette panel — the first Fits Melody or Replace suggestion if the strip is showing, otherwise the first In Key chord. Pressing Escape reverts to the block's original chord. Exactly one chip is highlighted at a time (the cursor), and the panel auto-scrolls so the cursor is always in view as you move between sections.

Audition mode is a try-before-you-commit step. Every arrow press previews the new chord, and the timeline chip, the highlighted palette chip, the fretboard, and the keyboard panels all update together so you can see the full impact of each change before it becomes permanent.

You can also arm a chord from the palette without placing it yet: click a chord chip and the same arrow keys take over. In palette-armed mode, Left/Right also carries the active extension across chord walks (so a 7-flavor stays a 7-flavor as you step through). Press Enter to insert the armed chord at the playhead (or the end of the last section if playback is stopped). This is useful when you want to hear a progression before adding to the timeline.

9.3 Suggestions and melody fit

Double-click an existing chord block to enter replace mode, or click an empty beat to enter place mode. Either way, the palette recalculates and two new sections appear at the top.

The Fits Melody section (top) ranks chords by how well their tones match the melody notes at this beat. The Place or Replace section (below it) ranks chords by how naturally they connect to the surrounding chords. Together, they answer two questions: what sounds good with the melody here? and what flows well in the progression?

Melody-fit scoring

Each melody-fit chip shows a score in the format 1/1 · 99%: one out of one melody notes in that beat range are chord tones, for a 99% fit score. The percentage is a weighted blend: root matches count more than fifth matches, thirds more than sevenths.

Hover a melody-fit chip for a detailed breakdown: which melody notes matched which chord tones, the progression context (if adjacency data is available), and a composite score explanation.

Melody-fit scoring updates live. Change a melody note at a beat and the chord rankings for that position reshuffle in real time. This is the mechanism behind the "everything talks to everything" behavior described in Chapter 4: the melody you wrote is actively shaping which chords the palette suggests.

Progression suggestions

The Place/Replace section ranks chords by weighted adjacency tables that model common progressions. Each scale degree has a list of weighted destinations. In a minor key, i tends toward iv (0.22), VII (0.18), and III (0.15). In a major key, I tends toward IV (0.22), V (0.20), and vi (0.18).

The ranking is context-aware: it considers both the chord before the target and the chord after it. The context label tells you exactly what's being evaluated: "C → ? between i and IV" means the palette is finding the best chord to sit between Am and D. Multi-chord patterns get additional boosts. A I-V sequence followed by a slot gets a strong boost for vi (the "Pop progression": I-V-vi-IV). A I-vi sequence boosts IV (the "50s progression": I-vi-IV-V).

Turnaround toggle

When you're placing or replacing a chord at the end of a section, a small loop icon appears next to the context label. Click it and the "chord after" target switches from whatever comes next (by default, the first chord of the next section) to the first chord of the current section. The context label updates to read something like "after V, looping back to I", and suggestions reshuffle to rank chords that lead naturally back to the top of the section: V7 turnarounds, ii-V cadences, secondary dominants of the section's tonic.

This is most useful when a verse or chorus repeats once before moving on, or when the section is the last one in the song and there's nothing to bridge into. The toggle is off by default and resets when you move to a different insertion point, so the standard "bridge to what's next" behavior stays the rule everywhere else.

Voice leading dots

Each suggestion chip shows a smoothness indicator: three filled dots (●●●) for very smooth voice leading (3 or fewer semitones of total hand movement), two filled and one empty (●●○) for moderate movement, and one filled and two empty (●○○) for larger jumps.

Suggestion tooltips

Hover any suggestion chip to see a tooltip explaining the ranking. The tooltip shows directional arrows: "← from Am" explains why this chord follows the preceding chord, and "→ to F" explains why it leads well into the following chord. When a multi-chord pattern triggered a boost, the tooltip names it ("Pop progression", "50s progression", "Andalusian cadence", and others).

9.4 Auto Chords (one-click harmonize)

The Fits Melody column ranks chords for a single beat. Auto Chords runs the same melody-fit logic across an entire section and produces a complete progression in one click.

The trigger is an Auto Chords button in the section nav, between the section's bars-per-line / beat-division controls and the right-side settings cluster. The button only appears when the section has enough melody notes on the grid to harmonize (a low single-digit minimum). If a preview is already open for that section, the button hides until you accept or cancel.

The preview bar

Clicking Auto Chords doesn't write anything to the grid. It opens a dashed-outline ghost progression in the chord lane and a preview action bar that mounts directly above the section's first line. The bar shows:

• Auto-chord preview — a label so you know what mode you're in.
• The inferred key the suggestions were ranked against (e.g. Sounds like A minor). Detected from the melody itself when the section has no key override.
• A flavor slider with three positions:
  • Held — one chord per phrase, slow harmonic rhythm. Good for ballads and sparse arrangements.
  • Steady — one chord per bar (or matching the section's natural pulse). The default.
  • Active — two or more chords per bar, more harmonic movement.
  • Switching flavor reshuffles the ghost progression instantly. The progression isn't randomized; it's deterministic given the same melody, key, and flavor.
• Regenerate — rerun the suggestion engine. Useful after editing a melody note while the preview is open.
• Cancel — discard the preview and leave the lane untouched.
• Accept — commit the ghost chords as real blocks. When the lane already has chords in it, the button reads Replace N so you know how many existing blocks the accept will overwrite.

Auditioning and swapping alternatives in the ghost

While the preview is open, the section's existing chord blocks are hidden so the dashed ghost progression has the lane to itself. The ghost blocks themselves are interactive:

• Hover a ghost block to open a popover with the chord name, a play button to audition it, a lock toggle, and a ranked list of alternatives for that beat range. The audition uses the same chord-preview path as palette chips, so it respects your guitar voicing or piano voice-leading settings.
• Click an alternative in the popover to swap the ghost to that chord without touching the rest of the progression. Each alternative has its own play button so you can hear it before picking. The same melody-fit + adjacency machinery used in the chord palette ranks the list.
• Click the ghost block itself to lock it (or click the lock toggle in the popover) so Regenerate keeps it in place while reshuffling the rest. Double-click is a shortcut to audition the current chord.

The chord lane's normal cell-hover, right-click context menu, and the empty-state hint all go inert while a preview is showing. The preview bar is the canonical action surface; the lane is read-only until you accept or cancel.

How accept interacts with existing chords

When you click Accept (or Replace N) on a section that already had chord blocks, every existing block whose beat range overlaps the new ghost progression is replaced atomically as a single undo step. Press Cmd+Z once if you don't like the result and you're back to the chords you had before the preview ran.

9.5 Extensions

Every chord starts as a triad. To add color, open the extension popover by clicking the three-dot button (⋯) on any chord chip in the palette or on any chord block on the timeline.

The popover shows a grid of extension buttons. The available extensions depend on the chord quality:

• Major chords get: 7, maj7, 9, sus4, sus2, add9, 6
• Minor chords get: 7, 9, add9, 6 (sus chords aren't offered on minor: sus chords replace the 3rd, which is what makes a chord minor, so "minor sus" collapses to a plain sus chord)
• Diminished chords get: 7 only

Each button shows the resulting chord name below it (e.g., clicking "7" on an Am chip shows "Am7"), so you can see the full name before committing.

Click an extension to apply it. The chord updates everywhere: on the timeline, in the palette, and in the voicing display. The extension popover stays open so you can compare extensions quickly.

9.6 Voicings

A chord name like "Am7" doesn't specify which octave, which inversion, or which fingering to use. The voicing controls let you make those choices.

Guitar voicings

When the instrument toggle in the toolbar is set to Guitar, chord blocks show a mini fretboard diagram: six horizontal lines representing the strings (E-A-D-G-B-E), with dots marking fretted positions, open-string markers, and X symbols for muted strings.

Song Cage ships with a database of real guitar chord shapes. When you place a chord, it picks a default voicing. To browse alternatives, open the chord edit popover (click the chord block, or right-click and choose Edit) and scroll through the voicing options.

If you've set a capo (via the toolbar), all guitar voicings transpose automatically. The fretboard diagram shows the shape relative to the capo position, and the sounding pitch stays correct.

Piano voicings

When the instrument toggle is set to Piano, chord blocks show a mini keyboard with highlighted chord tones.

Piano voicings have two axes of variation:

Voicing type controls the spread of the notes:

• Close: all notes within one octave, ascending
• Open: second-from-bottom note moved up an octave
• Spread: root in octave 3, remaining notes in octave 4 and above
• Drop-2: second-from-top note dropped down an octave (available for four-note chords and larger)

Inversion controls which note is in the bass:

• Root position
• 1st inversion (third in bass)
• 2nd inversion (fifth in bass)
• 3rd inversion (seventh in bass, for seventh chords)

An octave offset control (double-chevron up and down buttons on the outer flanks) shifts the entire voicing up or down by one or two octaves. The double chevrons read as a "bigger jump" so they stay distinct from the single-chevron voicing stepper next to the label.

Voicing carousel

The voicing carousel sits next to the chord label as a compact up/down stepper: the up chevron picks the next voicing, the down chevron picks the previous. The direction matches the keyboard shortcut (Up/Down) so you can cycle from mouse or keyboard without re-learning the mapping. Clicking the label itself opens a Browse all voicings popup that displays every available voicing in a grid, grouped by type, each rendered as a mini keyboard. Click any voicing to select it.

9.7 The Chord Tab lane

Every line on the timeline has a Chord Tab lane sitting directly under the chord lane. It's pre-collapsed by default; click the chevron next to the CHORDS TAB label to expand it. A six-string guitar staff appears (high e on top, low E on bottom) at the same width as the chord lane above, so each beat lines up vertically with the chord blocks.

Existing chord blocks render as a stack of fret numbers at the chord's downbeat, drawn from the block's stored guitar voicing. A capo offset is shown in the lane header when one is set.

Editing an existing voicing

Click a string at any beat inside an existing chord block, then type a fret number. The voicing updates live, and Song Cage re-runs chord detection on the new shape: if the fingering resolves to a different chord (say, you turn an Am into an Am7 by adding a fret), the chord lane's label updates with it. If detection can't classify the partial shape yet, the existing label is kept until you finish typing.

Multi-digit frets work the way you'd expect: type 1 then 2 for fret 12. Press X to mute a string. The cursor sits as a stripe across the active string, with the typed digit shown in orange until it commits.

Composing a new chord by typing frets

Click an empty beat (one with no chord block at it) to start a compose buffer. The cursor sits at that beat × string, and any frets you type are sketched in orange across the staff. Move between strings with Arrow Up / Down, type a fret per string, then press Enter to commit. The buffer lands as a new chord block with the auto-detected name and a duration matching the current snap (one beat at 1/4, half a beat at 1/8, and so on). Resize it on the chord lane afterward if you want it longer.

The compose buffer survives navigation: arrowing one beat over while the buffer is at the original beat commits the buffer first, so partial sketches don't get stranded. Click somewhere else on the timeline (or press Escape) to drop the buffer without committing.

Cursor and navigation

While the cursor is active on a tab lane, the keyboard takes over:

• Arrow Up / Down moves between strings.
• Arrow Left / Right moves between beats at the current snap.
• Tab / Enter advances and commits any in-flight digits.
• Backspace clears the digit buffer, then mutes the string on a second press.
• Escape dismisses the cursor and discards any compose buffer.

Clicking outside the tab lanes clears the cursor. The melody lane has its own tab counterpart with the same input model: see Chapter 10's Melody Tab lane section.

9.8 Editing chords on the grid

Once chords are on the timeline, you can reshape the progression directly.

Moving

Drag a chord block horizontally to reposition it within its section. The block snaps to the beat grid. To move a chord to a different section, drag it across the section boundary.

To move multiple chords at once, select them first (click one, then Shift-click or Cmd-click others, or Cmd+A to select all chords in the active section), then drag. All selected blocks move together by the same beat delta.

Resizing

Drag the right edge of a chord block to change its duration. Drag the left edge to change where it starts (the duration adjusts to compensate). Both edges snap to the beat grid.

Rolling boundaries

When two chord blocks sit directly next to each other, you can drag the boundary between them. This is a roll edit: one chord gets shorter, the other gets longer, and the transition point moves. No gap is created.

Copy, cut, paste

Standard shortcuts work on selected chord blocks:

• Cmd+C copies
• Cmd+X cuts
• Cmd+V pastes at the current pending target or playhead position

Pasted chords bring their voicings with them.

Deleting

Press Delete or Backspace to remove selected chord blocks.

Right-click menu

Right-click any chord block for a context menu with Copy, Cut, Paste, Delete, Smooth Voicings (see below), and a Chord Diagrams toggle that shows or hides the mini fretboard/keyboard display on all chord blocks.

9.9 Voice leading

When you build a progression one chord at a time, each chord gets an independent voicing. That's fine for exploring, but if you play the progression back on piano, the jumps between voicings can sound choppy: the right hand leaps around the keyboard instead of moving smoothly from one chord to the next.

The Smooth Voicings command fixes this. Select two or more chord blocks, right-click, and choose Smooth Voicings. Song Cage runs a Viterbi optimization that finds the voicing sequence with the least total hand movement across all selected chords. The first chord's voicing stays fixed as an anchor; subsequent chords switch to whichever inversion and voicing type minimizes the distance from the previous chord.

After optimization, a brief feedback message shows the improvement: something like "42 → 18 semitones," meaning the total voice-leading distance across the selection dropped from 42 semitones to 18.

Smooth Voicings only affects piano voicings. Guitar voicings are physical shapes on a fretboard and don't have the same invertibility, so the command is disabled when the instrument toggle is set to Guitar.

9.10 Chord shortcuts reference

---

That covers the chord palette and the mechanics of building a progression. The next chapter covers the other half of the harmony layer: writing melody, and how melody notes and chord suggestions feed into each other.