Fix scale_diagram enharmonic matching — v0.43.1

Scale notes spelled with flats (e.g. the Eb blue note in the blues
scale) were silently dropped from scale_diagram() because the fretboard
spells that pitch as D#, so the string comparison never matched. Match
notes enharmonically via the system's canonical name and display them
using the scale's own spelling. Pre-existing bug (also in 0.42.x),
surfaced while flipping the docs for the low-to-high release.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -7,3 +7,4 @@ t2.py
 __pycache__
 pytheory.egg-info
 docs/_build
+.claude/worktrees/

CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to PyTheory are documented here.
 
+## 0.43.1
+
+- **Fix `Fretboard.scale_diagram()` enharmonic matching.** Scale notes
+  spelled with flats (e.g. the `Eb` blue note in the blues scale) were
+  silently omitted from the diagram, because the fretboard spells that
+  pitch as `D#`. Notes are now matched enharmonically (by pitch) and
+  displayed using the scale's own spelling.
+
+## 0.43.0
+
+- **BREAKING — fingerings now read low-to-high by default.** `Fretboard`
+  string lists and `Fingering` positions/string-names now run from the
+  **lowest-pitched string first** (e.g. standard guitar reads `E A D G B E`),
+  matching how chord diagrams and tablature are conventionally written.
+  Previously they ran high-to-low (`E B G D A E`). This affects
+  `Fretboard.tones`, iteration over a fretboard, `repr`, `chord()`, `tab()`,
+  `chart()`, and `fingering()` output.
+
+  To restore the pre-0.43 high-to-low behavior, pass **`high_to_low=True`**
+  to any fretboard constructor — `Fretboard.guitar(high_to_low=True)`,
+  `Fretboard(tones=..., high_to_low=True)`, and likewise on every instrument
+  preset (`bass`, `ukulele`, `mandolin`, … `keyboard`).
+
+  The flip also applies to **input**: a custom tuning tuple passed to
+  `Fretboard.guitar(...)` and manual fret positions passed to
+  `fingering(*positions)` are now read in the board's orientation
+  (low-to-high by default).
+
+  `to_tab()` and `Part.strum()` are unaffected — they sort by pitch
+  internally and produce identical output regardless of orientation.
+
+## 0.42.1
+
+- **Fretboard tuning support** — `to_tab()` now accepts `Fretboard` objects as
+  the `tuning` parameter. Works with `Fretboard.guitar()`, `Fretboard.bass()`,
+  `Fretboard.ukulele()`, `Fretboard.mandolin()`, `Fretboard.banjo()`, and any
+  custom Fretboard with capo.
+
+## 0.42.0
+
+- **LilyPond export** — `Score.to_lilypond()` generates complete LilyPond source
+  files with multi-staff scores, key/time signatures, tempo markings, and
+  automatic bass clef detection. Output can be compiled to publication-quality
+  PDFs with LilyPond.
+- **MusicXML export** — `Score.to_musicxml()` generates MusicXML 4.0 documents
+  that can be opened in MuseScore, Sibelius, Finale, and any notation software.
+  Includes proper ties, chords, clef detection, and tempo/time signature metadata.
+- **Guitar/bass tablature** — `Part.to_tab()` and `Score.to_tab()` generate ASCII
+  tablature. Supports guitar (6-string), bass (4-string), drop D, and custom
+  tunings. Automatically maps notes to the best string/fret positions.
+
+## 0.41.4
+
+- **Fix** — `to_abc()` now ties long notes across barlines instead of emitting
+  oversized durations that abcjs can't render (e.g. 16-beat notes become four
+  tied whole notes).
+
+## 0.41.3
+
+- **Fix** — `to_abc()` now skips parts with only drum tones or rests (no pitched
+  notes), fixing "pitch is undefined" errors in abcjs. Chords are correctly
+  recognized as pitched content.
+
+## 0.41.2
+
+- **Auto bass clef** — `to_abc()` detects low-register parts (808, bass, timpani)
+  and assigns `clef=bass` automatically based on average note octave.
+
+## 0.41.1
+
+- **Fix** — `to_abc()` no longer crashes on parts containing drum tones.
+
+## 0.41.0
+
+- **ABC notation export** — `Score.to_abc()` converts scores to ABC notation
+  strings. Supports multi-voice scores (via `V:` directives), chords, rests,
+  accidentals, and all standard durations. Pass `html=True` to get a
+  self-contained HTML page that renders sheet music in the browser via abcjs.
+
 ## 0.40.9
 
 - **Mellotron synth** — tape-replay keyboard with wow/flutter, tape saturation,

docs/generate_audio.py

@@ -850,6 +850,56 @@ def gen_synth_ukulele():
         p.strum(ch, Duration.WHOLE, velocity=72)
     render("synth_ukulele", score)
 
+def gen_synth_hard_sync():
+    score = Score("4/4", bpm=120)
+    p = score.part("demo", instrument="sync_lead_bright", volume=0.5)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=90)
+    render("synth_hard_sync", score)
+
+
+def gen_synth_ring_mod():
+    score = Score("4/4", bpm=90)
+    p = score.part("demo", instrument="ring_mod_bell", volume=0.5)
+    for n in ["C5", "E5", "G5", "C6", "G5", "E5", "C5", "E5"]:
+        p.add(n, Duration.QUARTER, velocity=80)
+    render("synth_ring_mod", score)
+
+
+def gen_synth_wavefold():
+    score = Score("4/4", bpm=110)
+    p = score.part("demo", instrument="wavefold_warm", volume=0.5)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_wavefold", score)
+
+
+def gen_synth_drift():
+    score = Score("4/4", bpm=90)
+    p = score.part("demo", instrument="drift_saw", volume=0.5, reverb=0.35,
+                   reverb_type="taj_mahal")
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.HALF, velocity=75)
+    render("synth_drift", score)
+
+
+def gen_synth_karplus():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="pluck_synth", envelope="none",
+                   volume=0.5, reverb=0.2)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_karplus", score)
+
+
+def gen_synth_mellotron():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", instrument="mellotron_flute", volume=0.5)
+    for n in ["C4", "E4", "G4", "C5"]:
+        p.add(n, Duration.WHOLE, velocity=75)
+    render("synth_mellotron", score)
+
+
 def gen_synth_granular():
     score = Score("4/4", bpm=80)
     p = score.part("demo", instrument="granular_pad", volume=0.5, reverb=0.4)
@@ -1139,6 +1189,12 @@ GENERATORS = [
     gen_synth_banjo,
     gen_synth_mandolin,
     gen_synth_ukulele,
+    gen_synth_hard_sync,
+    gen_synth_ring_mod,
+    gen_synth_wavefold,
+    gen_synth_drift,
+    gen_synth_karplus,
+    gen_synth_mellotron,
     gen_synth_granular,
     gen_synth_crotales,
     gen_synth_tingsha,

docs/guide/chords.rst

@@ -94,11 +94,11 @@ PyTheory includes 144 pre-built chords (12 roots x 12 qualities):
 
    >>> fb = Fretboard.guitar()
    >>> fb.chord("C")
-   Fingering(e=0, B=1, G=0, D=2, A=3, E=x)
+   Fingering(E=x, A=3, D=2, G=0, B=1, e=0)
    >>> fb.chord("Am")
-   Fingering(e=0, B=1, G=2, D=2, A=0, E=x)
+   Fingering(E=x, A=0, D=2, G=2, B=1, e=0)
    >>> fb.chord("G7")
-   Fingering(e=1, B=0, G=0, D=0, A=2, E=3)
+   Fingering(E=3, A=2, D=0, G=0, B=0, e=1)
 
 You can also build chords directly with ``Chord.from_name()``:
 
@@ -503,9 +503,16 @@ are standard arranging techniques for spreading chord tones across registers:
    >>> cmaj7 = Chord.from_symbol("Cmaj7")
    >>> cmaj7.close_voicing()
    <Chord C major 7th>
+   >>> cmaj7.open_voicing()
+   <Chord C major 7th>
    >>> cmaj7.drop2()
    <Chord C major 7th>
 
+``open_voicing()`` takes the close voicing and raises every other
+non-root tone by an octave, spreading the chord across two octaves.
+The result is a wider, more spacious sound — common in orchestral
+writing and piano ballads where you want the harmony to breathe.
+
 Chord Extensions
 ----------------
 
@@ -596,6 +603,23 @@ music that doesn't follow traditional harmony, this is the tool.
 Major and minor triads share the same prime form — they're inversions
 of each other in pitch class space.
 
+The **normal form** is the intermediate step — the most compact ascending
+arrangement of pitch classes before transposition. It preserves the
+actual pitch classes (not transposed to 0), so it tells you which
+specific notes are in the set:
+
+.. code-block:: pycon
+
+   >>> Chord.from_tones("C", "E", "G").normal_form
+   (0, 4, 7)
+
+   >>> Chord.from_tones("A", "C", "E").normal_form
+   (9, 0, 4)
+
+Normal form keeps the original pitch classes; prime form transposes to 0
+for comparison. Use ``normal_form`` when you care about which notes,
+``prime_form`` when you care about the abstract shape.
+
 .. code-block:: pycon
 
    >>> Chord.from_tones("C", "E", "G").forte_number

docs/guide/cookbook.rst

@@ -111,19 +111,19 @@ Generate fingerings for guitar and ukulele with
 
    >>> fb = Fretboard.guitar()
    >>> fb.chord("C")
-   Fingering(e=0, B=1, G=0, D=2, A=3, E=x)
+   Fingering(E=x, A=3, D=2, G=0, B=1, e=0)
    >>> fb.chord("G")
-   Fingering(e=3, B=0, G=0, D=0, A=2, E=3)
+   Fingering(E=3, A=2, D=0, G=0, B=0, e=3)
    >>> fb.chord("Am")
-   Fingering(e=0, B=1, G=2, D=2, A=0, E=x)
+   Fingering(E=x, A=0, D=2, G=2, B=1, e=0)
    >>> fb.chord("D")
-   Fingering(e=2, B=3, G=2, D=0, A=x, E=x)
+   Fingering(E=x, A=x, D=0, G=2, B=3, e=2)
 
    >>> uke = Fretboard.ukulele()
    >>> uke.chord("C")
-   Fingering(A=3, E=0, C=0, G=0)
+   Fingering(G=0, C=0, E=0, A=3)
    >>> uke.chord("G")
-   Fingering(A=2, E=3, C=2, G=0)
+   Fingering(G=0, C=2, E=3, A=2)
 
 Explore an Interval
 -------------------

docs/guide/fretboard.rst

@@ -18,19 +18,28 @@ positions are just semitone steps along the fingerboard.
 Guitars
 -------
 
-`Standard guitar tuning <https://en.wikipedia.org/wiki/Guitar_tunings>`_
-(high to low)::
+`Standard guitar tuning <https://en.wikipedia.org/wiki/Guitar_tunings>`_::
 
-    String 1: E4  (highest)
-    String 2: B3
-    String 3: G3
-    String 4: D3
-    String 5: A2
     String 6: E2  (lowest)
+    String 5: A2
+    String 4: D3
+    String 3: G3
+    String 2: B3
+    String 1: E4  (highest)
 
 This tuning uses intervals of a perfect 4th (5 semitones) between most
 strings, except between G and B which is a major 3rd (4 semitones).
 
+.. note::
+
+   Since **v0.43.0**, fingerings and string lists read **low to high**
+   (lowest-pitched string first) by default — matching how chord
+   diagrams and tab are conventionally written. To get the pre-0.43
+   high-to-low order, pass ``high_to_low=True`` to any fretboard
+   constructor, e.g. ``Fretboard.guitar(high_to_low=True)``. A custom
+   tuning tuple and manual ``fingering()`` positions are likewise read
+   in the board's orientation.
+
 .. code-block:: pycon
 
    >>> from pytheory import Fretboard
@@ -192,12 +201,12 @@ on any instrument. It scores each possibility by:
    >>> fb = Fretboard.guitar()
    >>> f = fb.chord("C")
    >>> f
-   Fingering(e=0, B=1, G=0, D=2, A=3, E=x)
+   Fingering(E=x, A=3, D=2, G=0, B=1, e=0)
 
    >>> f['A']
    3
    >>> f[1]
-   1
+   3
 
    >>> f.identify()
    'C major'
@@ -210,11 +219,11 @@ You can also go from fret positions to chord identification:
 
 .. code-block:: pycon
 
-   >>> # "What chord am I playing?"
+   >>> # "What chord am I playing?" (positions read low to high)
    >>> fb = Fretboard.guitar()
-   >>> f = fb.fingering(0, 0, 0, 2, 2, 0)
+   >>> f = fb.fingering(0, 2, 2, 0, 0, 0)
    >>> f
-   Fingering(e=0, B=0, G=0, D=2, A=2, E=0)
+   Fingering(E=0, A=2, D=2, G=0, B=0, e=0)
    >>> f.identify()
    'E minor'
 
@@ -223,14 +232,14 @@ Reading Fingerings
 
 Each position is labeled with its string name. Duplicate string names
 are disambiguated — on a standard guitar, high E appears as ``e`` and
-low E as ``E``::
+low E as ``E``. Strings read low to high (lowest first)::
 
-    e|--0--    (open — E)
-    B|--1--    (fret 1 — C)
-    G|--0--    (open — G)
-    D|--2--    (fret 2 — E)
+    E|--x--    (muted — low E)
     A|--3--    (fret 3 — C)
-    E|--x--    (muted)
+    D|--2--    (fret 2 — E)
+    G|--0--    (open — G)
+    B|--1--    (fret 1 — C)
+    e|--0--    (open — high E)
 
 A value of ``x`` (``None``) means the string is muted (not played).
 
@@ -243,12 +252,12 @@ For a more visual representation, use ``tab()``:
 
    >>> print(fb.tab("C"))
    C major
-   e|--0--
-   B|--1--
-   G|--0--
-   D|--2--
-   A|--3--
    E|--x--
+   A|--3--
+   D|--2--
+   G|--0--
+   B|--1--
+   e|--0--
 
 Generating Full Charts
 ----------------------
@@ -261,7 +270,7 @@ Generate fingerings for every chord at once:
    >>> chart = fb.chart()
 
    >>> chart["C"]
-   Fingering(e=0, B=1, G=0, D=2, A=3, E=x)
+   Fingering(E=x, A=3, D=2, G=0, B=1, e=0)
 
    >>> # Works with any instrument
    >>> uke_chart = Fretboard.ukulele().chart()
@@ -303,19 +312,19 @@ Any instrument can be modeled with custom string tunings:
 
    >>> from pytheory import Tone, Fretboard
 
-   >>> # Baritone ukulele (DGBE — top 4 guitar strings)
+   >>> # Baritone ukulele (DGBE — top 4 guitar strings, low to high)
    >>> bari_uke = Fretboard(tones=[
-   ...     Tone.from_string("E4"),
-   ...     Tone.from_string("B3"),
-   ...     Tone.from_string("G3"),
    ...     Tone.from_string("D3"),
+   ...     Tone.from_string("G3"),
+   ...     Tone.from_string("B3"),
+   ...     Tone.from_string("E4"),
    ... ])
 
-   >>> # Tres cubano (Cuban guitar, 3 doubled courses)
+   >>> # Tres cubano (Cuban guitar, 3 doubled courses, low to high)
    >>> tres = Fretboard(tones=[
-   ...     Tone.from_string("E4"),
-   ...     Tone.from_string("B3"),
    ...     Tone.from_string("G3"),
+   ...     Tone.from_string("B3"),
+   ...     Tone.from_string("E4"),
    ... ])
 
 If it has strings, you can model it. Define the tuning, and PyTheory handles the rest -- fingerings, charts, scale diagrams, all of it. Got a weird instrument or a custom tuning? That's what the ``Fretboard`` constructor is for.

docs/guide/nashville-blues-tabs.rst

@@ -0,0 +1,407 @@
+Nashville Numbers, Blues Scales, and Tablature
+===============================================
+
+Three tools that work together: the Nashville number system for writing
+chord charts, blues scales for improvisation, and tablature for seeing
+where to put your fingers. This guide covers all three and shows how
+they connect.
+
+The Nashville Number System
+---------------------------
+
+The `Nashville number system <https://en.wikipedia.org/wiki/Nashville_Number_System>`_
+replaces chord names with Arabic numerals (1, 2, 3...) so that a chart
+works in **any key**. It's the standard chart format in Nashville
+recording studios — a session musician can read a number chart and
+transpose on the fly without rewriting anything.
+
+The idea is simple: each number refers to a **scale degree**. In any
+major key, 1 is the tonic chord, 4 is the subdominant, 5 is the
+dominant, and so on. The chord quality (major, minor, diminished) is
+determined by the key — you don't need to write it out.
+
+In C major::
+
+    1 = C major      5 = G major
+    2 = D minor      6 = A minor
+    3 = E minor      7 = B diminished
+    4 = F major
+
+In G major::
+
+    1 = G major      5 = D major
+    2 = A minor      6 = E minor
+    3 = B minor      7 = F# diminished
+    4 = C major
+
+Same numbers, different key, different chords — but the same harmonic
+relationships.
+
+Using Nashville Numbers in PyTheory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Both :class:`~pytheory.scales.Key` and :class:`~pytheory.scales.TonedScale`
+support the ``nashville()`` method:
+
+.. code-block:: pycon
+
+   >>> from pytheory import Key
+
+   >>> key = Key("C", "major")
+   >>> [c.identify() for c in key.nashville(1, 4, 5, 1)]
+   ['C major', 'F major', 'G major', 'C major']
+
+   >>> # Same progression, different key — just change the Key
+   >>> key_g = Key("G", "major")
+   >>> [c.identify() for c in key_g.nashville(1, 4, 5, 1)]
+   ['G major', 'C major', 'D major', 'G major']
+
+Nashville numbers and Roman numerals produce the same result — they're
+two notations for the same concept:
+
+.. code-block:: pycon
+
+   >>> key = Key("G", "major")
+   >>> nash = [c.identify() for c in key.nashville(1, 5, 6, 4)]
+   >>> roman = [c.identify() for c in key.progression("I", "V", "vi", "IV")]
+   >>> nash == roman
+   True
+
+Seventh Chords
+~~~~~~~~~~~~~~
+
+Suffix ``"7"`` to get seventh chords — essential for jazz and blues
+charts:
+
+.. code-block:: pycon
+
+   >>> key = Key("C", "major")
+   >>> [c.identify() for c in key.nashville("17", "47", "57")]
+   ['C major 7th', 'F major 7th', 'G dominant 7th']
+
+Nashville vs. Roman Numerals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When should you use which?
+
+- **Nashville numbers** — faster to type, easier to read at a glance,
+  standard in studio sessions. Use ``key.nashville(1, 4, 5, 1)``.
+- **Roman numerals** — encode chord quality (uppercase = major,
+  lowercase = minor), standard in theory textbooks. Use
+  ``key.progression("I", "IV", "V", "I")``.
+
+Both are fully supported. Use whichever fits your workflow.
+
+Blues Scales
+------------
+
+The `blues scale <https://en.wikipedia.org/wiki/Blues_scale>`_ is a
+six-note scale built from the minor pentatonic plus one chromatic
+passing tone — the **blue note** (flat 5th). That single added note
+gives the blues its tension and character.
+
+The blues system in PyTheory includes several related scales:
+
+====================  =====  ==================================
+Scale                 Notes  Character
+====================  =====  ==================================
+minor pentatonic      5      Foundation of rock and blues soloing
+major pentatonic      5      Bright, country, pop
+blues                 6      Minor pentatonic + blue note (b5)
+major blues           6      Major pentatonic + blue note (b3)
+dominant              7      Mixolydian — dominant 7th sound
+minor                 7      Dorian-like — minor with natural 6th
+====================  =====  ==================================
+
+Building Blues Scales
+~~~~~~~~~~~~~~~~~~~~~
+
+Use ``system="blues"`` when creating a :class:`~pytheory.scales.TonedScale`:
+
+.. code-block:: pycon
+
+   >>> from pytheory import TonedScale
+
+   >>> c = TonedScale(tonic="C4", system="blues")
+
+   >>> c["minor pentatonic"].note_names
+   ['C', 'Eb', 'F', 'G', 'Bb', 'C']
+
+   >>> c["blues"].note_names
+   ['C', 'Eb', 'F', 'Gb', 'G', 'Bb', 'C']
+
+   >>> c["major pentatonic"].note_names
+   ['C', 'D', 'E', 'G', 'A', 'C']
+
+   >>> c["major blues"].note_names
+   ['C', 'D', 'Eb', 'E', 'G', 'A', 'C']
+
+The Anatomy of a Blues Scale
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The blues scale in C::
+
+    C  Eb  F  Gb  G  Bb  C
+    1  b3  4  b5  5  b7  8
+
+    Root ──┐
+           ├── minor 3rd (3 semitones)
+           ├── perfect 4th (5 semitones)
+           ├── diminished 5th (6 semitones) ← the "blue note"
+           ├── perfect 5th (7 semitones)
+           ├── minor 7th (10 semitones)
+           └── octave (12 semitones)
+
+The blue note (Gb/F#) sits between the 4th and 5th — a dissonant,
+unstable pitch that resolves up or down. It's what makes blues sound
+like blues.
+
+The 12-Bar Blues
+~~~~~~~~~~~~~~~~
+
+The `12-bar blues <https://en.wikipedia.org/wiki/Twelve-bar_blues>`_ is
+the most important chord progression in American music. It uses the
+Nashville numbers 1, 4, and 5::
+
+    | 1  | 1  | 1  | 1  |
+    | 4  | 4  | 1  | 1  |
+    | 5  | 4  | 1  | 5  |
+
+In the key of A:
+
+.. code-block:: pycon
+
+   >>> from pytheory import Key
+
+   >>> key = Key("A", "major")
+   >>> bars = key.nashville(1,1,1,1, 4,4,1,1, 5,4,1,5)
+   >>> [c.identify() for c in bars]
+   ['A major', 'A major', 'A major', 'A major', 'D major', 'D major', 'A major', 'A major', 'E major', 'D major', 'A major', 'E major']
+
+For an authentic blues sound, use dominant 7th chords:
+
+.. code-block:: pycon
+
+   >>> bars_7 = key.nashville("17","17","17","17", "47","47","17","17", "57","47","17","57")
+   >>> [c.identify() for c in bars_7]
+   ['A major 7th', 'A major 7th', 'A major 7th', 'A major 7th', 'D major 7th', 'D major 7th', 'A major 7th', 'A major 7th', 'E dominant 7th', 'D major 7th', 'A major 7th', 'E dominant 7th']
+
+Or use the built-in named progression:
+
+.. code-block:: pycon
+
+   >>> key = Key("A", "major")
+   >>> blues = key.common_progressions()["12-bar blues"]
+   >>> [c.identify() for c in blues]
+   ['A major', 'A major', 'A major', 'A major', 'D major', 'D major', 'A major', 'A major', 'E major', 'D major', 'A major', 'E major']
+
+Blues Scale on the Fretboard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Visualize the blues scale on guitar to see the patterns:
+
+.. code-block:: pycon
+
+   >>> from pytheory import Fretboard, TonedScale
+
+   >>> fb = Fretboard.guitar()
+   >>> blues = TonedScale(tonic="A4", system="blues")["blues"]
+   >>> print(fb.scale_diagram(blues, frets=12))
+       0   1   2   3   4   5   6   7   8   9  10  11  12
+   E| E | - | - | G | - | A | - | - | C | - | D | Eb| E |
+   A| A | - | - | C | - | D | Eb| E | - | - | G | - | A |
+   D| D | Eb| E | - | - | G | - | A | - | - | C | - | D |
+   G| G | - | A | - | - | C | - | D | Eb| E | - | - | G |
+   B| - | C | - | D | Eb| E | - | - | G | - | A | - | - |
+   E| E | - | - | G | - | A | - | - | C | - | D | Eb| E |
+
+The minor pentatonic (same scale without the Eb) is the most-played
+scale in rock guitar. Add the blue note and you have the full blues
+scale — the same shapes, one extra fret.
+
+Tablature
+---------
+
+`Tablature <https://en.wikipedia.org/wiki/Tablature>`_ (tab) shows
+**where to put your fingers** rather than what notes to play. Each line
+represents a string; numbers indicate fret positions. PyTheory generates
+tabs at three levels:
+
+1. **Chord tabs** — single chord fingerings
+2. **Part tabs** — full melody/sequence notation
+3. **Score tabs** — extract a part from a multi-part score
+
+Chord Tablature
+~~~~~~~~~~~~~~~~
+
+Get the tab for any chord on any instrument:
+
+.. code-block:: pycon
+
+   >>> from pytheory import Fretboard
+
+   >>> fb = Fretboard.guitar()
+   >>> print(fb.tab("C"))
+   C major
+   E|--x--
+   A|--3--
+   D|--2--
+   G|--0--
+   B|--1--
+   e|--0--
+
+   >>> print(fb.tab("Am"))
+   A minor
+   E|--x--
+   A|--0--
+   D|--2--
+   G|--2--
+   B|--1--
+   e|--0--
+
+   >>> print(fb.tab("E7"))
+   E dominant 7th
+   E|--0--
+   A|--2--
+   D|--0--
+   G|--1--
+   B|--0--
+   e|--0--
+
+Works with any instrument:
+
+.. code-block:: pycon
+
+   >>> uke = Fretboard.ukulele()
+   >>> print(uke.tab("C"))
+   C major
+   G|--0--
+   C|--0--
+   E|--0--
+   A|--3--
+
+Reading Tab Notation
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    E|--x--    ← muted (don't play this string)
+    A|--3--    ← press fret 3
+    D|--2--    ← press fret 2
+    G|--0--    ← open string
+    B|--1--    ← press fret 1
+    e|--0--    ← open string (don't fret, just pluck)
+
+- Each line is a string. Chord tab from ``fb.tab()`` lists strings
+  low-to-high (lowest pitch at top) by default since v0.43.0; pass
+  ``high_to_low=True`` to the fretboard for the traditional
+  highest-pitch-on-top layout.
+- Numbers are fret positions (0 = open, 1-24 = fretted)
+- ``x`` means the string is muted / not played
+- ``|`` marks measure boundaries in sequence tabs
+
+Part Tablature
+~~~~~~~~~~~~~~~
+
+Generate tab from a composed part using ``to_tab()``:
+
+.. code-block:: python
+
+   from pytheory import Score, Key, Duration
+
+   score = Score("4/4", bpm=120)
+   lead = score.part("lead", synth="saw")
+
+   # A simple blues lick
+   for note in ["A4", "C5", "D5", "Eb5", "E5", "G5", "A5"]:
+       lead.add(note, Duration.QUARTER)
+
+   print(lead.to_tab())
+
+This outputs standard ASCII tab with measure lines, mapping each note
+to the most playable string and fret position.
+
+Tuning Options
+~~~~~~~~~~~~~~
+
+The ``to_tab()`` method supports multiple tunings:
+
+.. code-block:: python
+
+   # Standard guitar (default)
+   lead.to_tab(tuning="guitar")
+
+   # 4-string bass
+   lead.to_tab(tuning="bass")
+
+   # Drop D guitar
+   lead.to_tab(tuning="drop_d")
+
+   # Any Fretboard object — use any of the 25+ instrument presets
+   from pytheory import Fretboard
+   lead.to_tab(tuning=Fretboard.mandolin())
+   lead.to_tab(tuning=Fretboard.banjo())
+
+   # Custom tuning as MIDI note numbers (low string first)
+   lead.to_tab(tuning=[40, 45, 50, 55, 59, 64])
+
+Score Tablature
+~~~~~~~~~~~~~~~~
+
+Extract tab from a multi-part score:
+
+.. code-block:: python
+
+   score = Score("4/4", bpm=120)
+   rhythm = score.part("rhythm", synth="saw")
+   lead = score.part("lead", synth="triangle")
+   bass = score.part("bass", synth="sine")
+
+   # ... compose parts ...
+
+   # Tab the lead part
+   print(score.to_tab("lead"))
+
+   # Tab the first non-drum part (if no name given)
+   print(score.to_tab())
+
+   # Bass tab
+   print(score.to_tab("bass", tuning="bass"))
+
+Putting It All Together
+-----------------------
+
+Here's a complete example that uses all three features — Nashville
+numbers for the chord progression, the blues scale for the melody, and
+tab export to see the fingering:
+
+.. code-block:: python
+
+   from pytheory import Key, TonedScale, Fretboard, Score, Duration
+
+   # 1. Nashville numbers for the progression
+   key = Key("A", "major")
+   chords = key.nashville(1, 1, 1, 1, 4, 4, 1, 1, 5, 4, 1, 5)
+
+   # 2. Blues scale for the melody
+   blues = TonedScale(tonic="A4", system="blues")["blues"]
+
+   # 3. Compose a score
+   score = Score("4/4", bpm=120)
+   rhythm = score.part("rhythm", synth="saw", envelope="pad")
+   lead = score.part("lead", synth="triangle", envelope="pluck")
+
+   for chord in chords:
+       rhythm.add(chord, Duration.WHOLE)
+
+   for note_name in blues.note_names[:-1]:  # walk up the scale
+       lead.add(f"{note_name}4", Duration.HALF)
+
+   # 4. See it as tablature
+   print(lead.to_tab())
+
+   # 5. See the scale on the fretboard
+   fb = Fretboard.guitar()
+   print(fb.scale_diagram(blues, frets=12))
+
+Nashville numbers tell you *what chords to play*. The blues scale tells you *what notes to solo with*. Tablature tells you *where to put your fingers*. Together, they're everything you need to play the blues.

docs/guide/playback.rst

@@ -3,19 +3,21 @@ Playback and Export
 
 This is the output layer. You've built your theory, composed your
 arrangement, shaped your sounds -- now you need to hear it. PyTheory
-gives you three ways to get your music out: speakers, WAV files, and
-MIDI files.
+gives you four ways to get your music out: speakers, WAV files, MIDI
+files, and sheet music.
 
 Use **speakers** for immediate feedback while you're sketching and
 experimenting. Use **WAV export** when you want to share actual audio
 -- post it, send it, drop it into a video. Use **MIDI export** when you
 want to bring your sketch into a real DAW and finish it with
-professional instruments, mixing, and mastering. Each output serves a
-different stage of the creative process.
+professional instruments, mixing, and mastering. Use **ABC notation
+export** when you want sheet music -- rendered in the browser or shared
+as plain text. Each output serves a different stage of the creative
+process.
 
-PyTheory can play audio through your speakers, save to WAV, or export
-to MIDI. Everything is synthesized from waveforms -- no samples or
-external audio files needed.
+PyTheory can play audio through your speakers, save to WAV, export to
+MIDI, or generate sheet music as ABC notation. Everything is synthesized
+from waveforms -- no samples or external audio files needed.
 
 .. note::
 
@@ -171,6 +173,154 @@ Score-based export (with time signature, tempo, and parts):
        score.add(chord, Duration.WHOLE)
    score.save_midi("progression.mid")
 
+to_abc() -- ABC Notation / Sheet Music
+---------------------------------------
+
+ABC notation is a human-readable text format for music that tools can
+turn into staff notation and MIDI. It's widely used for folk tunes,
+lead sheets, and quick sketches. PyTheory can export any Score as ABC
+notation -- and optionally wrap it in an HTML page that renders
+sheet music right in the browser using `abcjs <https://www.abcjs.net/>`_.
+
+Basic export:
+
+.. code-block:: python
+
+   from pytheory import Score, Duration, Key
+
+   score = Score("4/4", bpm=120)
+   lead = score.part("lead")
+   for chord in Key("C", "major").progression("I", "V", "vi", "IV"):
+       lead.add(chord, Duration.WHOLE)
+
+   print(score.to_abc(title="Pop Chords", key="C"))
+
+Output:
+
+.. code-block:: text
+
+   X:1
+   T:Pop Chords
+   M:4/4
+   Q:1/4=120
+   L:1/8
+   K:C
+   [CEG]8 | [GBd]8 | [Ace]8 | [FAc]8 |
+
+Open sheet music in the browser with ``html=True``:
+
+.. code-block:: python
+
+   html = score.to_abc(title="Pop Chords", key="C", html=True)
+
+   with open("chords.html", "w") as f:
+       f.write(html)
+
+   import webbrowser
+   webbrowser.open("chords.html")
+
+This generates a self-contained HTML page with an embedded
+``<script>`` tag that loads abcjs from a CDN and renders the notation
+as SVG -- no build steps, no dependencies, just open the file.
+
+Multi-part scores automatically get ``V:`` (voice) directives so each
+instrument appears on its own staff. Bass parts (average note below C4)
+get bass clef automatically. Drum-only parts are skipped. Notes longer
+than one measure are split into tied notes across barlines.
+
+Parameters:
+
+- **title** -- Tune title for the ``T:`` header (default ``"Untitled"``).
+- **key** -- ABC key signature string (default ``"C"``). Use ``"Am"`` for
+  A minor, ``"Bb"`` for B-flat major, ``"F#m"`` for F-sharp minor, etc.
+- **html** -- If ``True``, return a full HTML document instead of raw ABC
+  (default ``False``).
+
+to_lilypond() -- LilyPond Export
+---------------------------------
+
+`LilyPond <https://lilypond.org/>`_ is the gold standard for
+publication-quality music engraving. ``to_lilypond()`` generates
+complete LilyPond source files that you can compile to PDF:
+
+.. code-block:: python
+
+   score = Score("4/4", bpm=120)
+   lead = score.part("lead")
+   for note in ["C4", "D4", "E4", "F4"]:
+       lead.add(note, Duration.QUARTER)
+
+   ly = score.to_lilypond(title="My Score", key="C", mode="major")
+
+   with open("score.ly", "w") as f:
+       f.write(ly)
+
+Then compile with ``lilypond score.ly`` to get a PDF. Multi-part scores
+get separate staves in a ``StaffGroup``, bass clef is auto-detected,
+and long notes are split with ties across barlines.
+
+Parameters:
+
+- **title** -- Title for the ``\header`` block (default ``"Untitled"``).
+- **key** -- Key signature root (default ``"C"``). Use note names like
+  ``"Bb"``, ``"F#"``, ``"Eb"``.
+- **mode** -- LilyPond mode string (default ``"major"``). Use ``"minor"``
+  for minor keys.
+
+to_musicxml() -- MusicXML Export
+---------------------------------
+
+MusicXML is the interchange format for notation software. Export your
+score and open it in MuseScore, Sibelius, Finale, Dorico, or any
+other notation app:
+
+.. code-block:: python
+
+   xml = score.to_musicxml(title="My Score")
+
+   with open("score.musicxml", "w") as f:
+       f.write(xml)
+
+The output is a complete MusicXML 4.0 partwise document with proper
+time signatures, tempo markings, clef detection, tied notes across
+barlines, and chord notation. No external dependencies needed.
+
+to_tab() -- Guitar/Bass Tablature
+-----------------------------------
+
+Generate ASCII tablature from any Part or Score:
+
+.. code-block:: python
+
+   lead = score.part("lead")
+   lead.add("E4", Duration.QUARTER)
+   lead.add("B3", Duration.QUARTER)
+   lead.add("G3", Duration.QUARTER)
+   lead.add("D3", Duration.QUARTER)
+
+   print(lead.to_tab())
+
+Output::
+
+   e|---0---------|
+   B|------0------|
+   G|---------0---|
+   D|------------0|
+   A|-------------|
+   E|-------------|
+
+Works on Score too -- it picks the first melodic part automatically:
+
+.. code-block:: python
+
+   print(score.to_tab())                          # auto-pick part
+   print(score.to_tab(part_name="bass"))           # specific part
+   print(score.to_tab(tuning="bass"))              # 4-string bass tab
+   print(score.to_tab(tuning="drop_d"))            # drop D guitar
+
+Supports ``"guitar"`` (6-string standard), ``"bass"`` (4-string),
+``"drop_d"``, or a custom list of MIDI note numbers for any tuning.
+
 play_pattern() -- Drum Patterns
 -------------------------------
 

docs/guide/quickstart.rst

@@ -130,7 +130,7 @@ Guitar fingerings:
 
    >>> fb = Fretboard.guitar()
    >>> fb.chord("Am")
-   Fingering(e=0, B=1, G=2, D=2, A=0, E=x)
+   Fingering(E=x, A=0, D=2, G=2, B=1, e=0)
 
 All of the above works without PortAudio, without sounddevice,
 without any audio setup at all. It's pure Python music theory.

docs/guide/scales.rst

@@ -269,6 +269,23 @@ easy:
    ['G major', 'A minor', 'B minor', 'C major', 'D major', 'E minor', 'F# diminished']
    >>> key.seventh_chords
    ['G major 7th', 'A minor 7th', 'B minor 7th', 'C major 7th', 'D dominant 7th', 'E minor 7th', 'F# half-diminished 7th']
+
+Build a seventh chord on any individual degree with ``seventh()``:
+
+.. code-block:: pycon
+
+   >>> key.seventh(0)   # I7
+   G major 7th
+   >>> key.seventh(4)   # V7
+   D dominant 7th
+   >>> key.seventh(6)   # vii7
+   F# half-diminished 7th
+
+This is the single-degree version of ``seventh_chords`` — useful when
+you need one specific chord rather than the full list.
+
+.. code-block:: pycon
+
    >>> Key.detect("C", "E", "G", "A", "D")
    C major
 
@@ -440,7 +457,16 @@ alternative scales to improvise over:
    >>> Scale.recommend("C", "Eb", "F", "Gb", "G", "Bb", top=3)
    [('C', 'blues', 1.0), ...]
 
-Chromatic scales are deprioritized since they match everything.
+How it works: ``recommend()`` tests your notes against every scale in
+every key (all 12 tonics times all scale types in the Western system).
+Each candidate is scored using ``fitness()`` — the fraction of your notes
+that belong to that scale (1.0 = perfect match). Results are ranked by
+fitness, with chromatic scales deprioritized since they match everything.
+Scales whose length is closer to the number of input notes are preferred
+when fitness scores tie.
+
+Returns a list of ``(tonic, scale_name, fitness)`` tuples. Pass ``top=``
+to control how many results you get back (default 5).
 
 Parallel Modes
 ~~~~~~~~~~~~~~

docs/guide/synths.rst

@@ -277,6 +277,10 @@ of the Prophet-5, Moog Prodigy, and every screaming analog lead since
    from pytheory import play, Synth, Tone
    play(Tone.from_string("C4"), synth=Synth.HARD_SYNC, slave_ratio=2.5)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_hard_sync.wav" type="audio/wav"></audio>
+
 Ring Modulation
 ~~~~~~~~~~~~~~~
 
@@ -296,6 +300,10 @@ soundtrack.
    # Non-integer ratios = more inharmonic
    play(Tone.from_string("C4"), synth=Synth.RING_MOD, mod_ratio=2.1)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_ring_mod.wav" type="audio/wav"></audio>
+
 Wavefolding
 ~~~~~~~~~~~
 
@@ -322,6 +330,10 @@ the wave. Pairs beautifully with a lowpass filter after the fold.
    # Direct control over fold amount
    play(Tone.from_string("C4"), synth=Synth.WAVEFOLD, folds=3.0)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_wavefold.wav" type="audio/wav"></audio>
+
 Drift Oscillator
 ~~~~~~~~~~~~~~~~
 
@@ -351,6 +363,10 @@ that needs to feel "alive."
    play(Tone.from_string("C4"), synth=Synth.DRIFT,
         shape="triangle", drift_amount=0.25)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_drift.wav" type="audio/wav"></audio>
+
 Drift amount controls how unstable the oscillator is:
 
 - **0.05** = studio-grade (Sequential, Oberheim)
@@ -514,6 +530,10 @@ It sounds genuinely like a real guitar, harp, or koto.
    guitar = score.part("guitar", synth="pluck_synth")
    harp = score.part("harp", instrument="harp")  # uses pluck_synth
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_karplus.wav" type="audio/wav"></audio>
+
 Hammond Organ
 ~~~~~~~~~~~~~
 
@@ -633,7 +653,11 @@ Three tape banks are available via the ``tape`` parameter:
 
    # Or select the tape directly
    from pytheory import play, Synth, Tone
-   play(Tone.from_string("C4"), synth=Synth.MELLOTRON, tape="choir", t=3000)
+   play(Tone.from_string("C4"), synth=Synth.MELLOTRON, tape="flute", t=3000)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_mellotron.wav" type="audio/wav"></audio>
 
 Vibraphone Synth
 ~~~~~~~~~~~~~~~~

docs/guide/tones.rst

@@ -357,6 +357,32 @@ every tone knows its enharmonic spelling:
    >>> Tone.from_string("C4", system="western").enharmonic is None
    True
 
+Accidental Properties
+~~~~~~~~~~~~~~~~~~~~~
+
+Check whether a tone is natural, sharp, or flat:
+
+.. code-block:: pycon
+
+   >>> c = Tone.from_string("C4", system="western")
+   >>> c.is_natural
+   True
+   >>> c.is_sharp
+   False
+
+   >>> cs = Tone.from_string("C#4", system="western")
+   >>> cs.is_sharp
+   True
+   >>> cs.is_natural
+   False
+
+   >>> bb = Tone.from_string("Bb4", system="western")
+   >>> bb.is_flat
+   True
+
+Useful for filtering — for example, finding all natural notes in a
+scale, or counting accidentals in a melody.
+
 Extended Enharmonics
 ~~~~~~~~~~~~~~~~~~~~
 

docs/index.rst

@@ -118,6 +118,7 @@ What's Inside
    guide/scales
    guide/chords
    guide/fretboard
+   guide/nashville-blues-tabs
    guide/systems
    guide/sequencing
    guide/synths

examples/chord_charts.py

@@ -1,17 +1,8 @@
-from pytheory import Tone, Fretboard, CHARTS
+from pytheory import Fretboard, CHARTS
 
-# Create standard tuning (from high E to low E)
-standard_tuning = [
-    Tone.from_string("E4"),  # High E
-    Tone.from_string("B3"),  # B
-    Tone.from_string("G3"),  # G
-    Tone.from_string("D3"),  # D
-    Tone.from_string("A2"),  # A
-    Tone.from_string("E2"),  # Low E
-]
-
-# Create fretboard with standard tuning
-fretboard = Fretboard(tones=standard_tuning)
+# Standard guitar fretboard. Since v0.43.0 fingerings read low to high
+# (low E first) by default — exactly how tab is conventionally written.
+fretboard = Fretboard.guitar()
 
 # Define flat to sharp note mappings (updated to include all possible flats)
 flat_to_sharp = {"Ab": "G#", "Bb": "A#", "Db": "C#", "Eb": "D#", "Gb": "F#"}
@@ -26,34 +17,6 @@ print("Standard Guitar Chord Charts:")
 print("-" * 30)
 
 
-def fingering_to_tab(fingering):
-    if not fingering:
-        return ""
-
-    # Create 6 strings of dashes, representing the guitar strings
-    strings = ["-" * 15 for _ in range(6)]
-
-    # For each string (starting from high E)
-    for string_num, fret in enumerate(fingering):
-        if fret is not None:
-            # Place the fret number at the correct position
-            if fret == 0:
-                strings[string_num] = "0" + strings[string_num][1:]
-            else:
-                strings[string_num] = (
-                    "-" * (fret - 1) + str(fret) + strings[string_num][fret:]
-                )
-
-    # Combine strings with newlines, and add string names
-    tab = "e|" + strings[0] + "\n"
-    tab += "B|" + strings[1] + "\n"
-    tab += "G|" + strings[2] + "\n"
-    tab += "D|" + strings[3] + "\n"
-    tab += "A|" + strings[4] + "\n"
-    tab += "E|" + strings[5] + "\n"
-    return tab
-
-
 for chord_name in all_chords:
     # Store original chord name for lookup
     lookup_name = chord_name
@@ -74,7 +37,7 @@ for chord_name in all_chords:
     try:
         fingering = chord.fingering(fretboard=fretboard)
         print(f"\n{display_name}:")
-        print(fingering_to_tab(fingering))
+        print(fingering.tab())
     except Exception as e:
         print(f"{display_name}: Unable to calculate fingering - {str(e)}")
         # Add more detailed debug information