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,186 @@
 
 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,
+  bandwidth limiting, hiss, and 8-second tape fadeout. Three tape banks via the
+  `tape` parameter: `"strings"` (default), `"flute"`, and `"choir"`.
+- **Analog oscillator synths** — four new waveform generators for fat, alive,
+  analog-style sounds:
+  - `Synth.HARD_SYNC` — slave oscillator hard-synced to a master (Prophet-5
+    leads). `slave_ratio` parameter controls harmonic content.
+  - `Synth.RING_MOD` — two oscillators multiplied for metallic, bell-like
+    inharmonic tones. `mod_ratio` parameter.
+  - `Synth.WAVEFOLD` — west coast wavefolding (Buchla-style). `folds` parameter
+    sweeps from warm to gnarly.
+  - `Synth.DRIFT` — analog VCO with pitch drift, jitter, and noise floor.
+    `shape` parameter (`"saw"`, `"square"`, `"triangle"`, `"pulse"`) and
+    `drift_amount` for instability level.
+- **Synth kwargs passthrough** — `play()`, `save()`, and `_render()` now accept
+  `**synth_kw` for forwarding parameters to synth wave functions (e.g.
+  `play(tone, synth=Synth.MELLOTRON, tape="choir")`).
+- **14 new instrument presets** — `mellotron`, `mellotron_strings`,
+  `mellotron_flute`, `mellotron_choir`, `sync_lead`, `sync_lead_bright`,
+  `ring_mod_bell`, `ring_mod_metallic`, `wavefold_warm`, `wavefold_gnarly`,
+  `drift_saw`, `drift_square`, `analog_pad`, `analog_bass`.
+- **808 bass envelope fix** — changed from `pluck` (zero sustain, wrong for 808)
+  to `piano` (sharp attack with long decay tail).
+
+## 0.40.8
+
+- **Fix hold() inflating duration** — `Note.beats` was returning the full
+  duration for held notes (`_hold=True`), causing `Part.total_beats` and
+  `Score.duration_ms` to overcount. A part with `hold(Sa, WHOLE * 4)` followed
+  by `add(Pa, QUARTER)` would report 17 beats instead of 1. Now held notes
+  return 0 beats, matching the renderer which already skipped advancing the
+  timeline for held notes.
+
+## 0.40.7
+
+- **Expose missing Synth enum entries** — rhodes, wurlitzer, vibraphone,
+  pipe organ, and choir wave functions were already implemented but not
+  accessible via the Synth enum. Now available as `Synth.RHODES`,
+  `Synth.WURLITZER`, `Synth.VIBRAPHONE`, `Synth.PIPE_ORGAN`, `Synth.CHOIR`.
+
+## 0.40.6
+
+- **Saxophone presets cleaned up** — removed lowpass filters and vel_to_filter
+  from all sax instrument presets (saxophone, alto_sax, tenor_sax, bari_sax).
+  The saxophone wave function already shapes its own spectrum; the extra
+  filters were dulling the tone.
+
+## 0.40.5
+
+- **Saxophone synth overhaul** — reed nonlinearity (asymmetric soft clipping),
+  conical bore formant resonances, breath noise with attack envelope, separate
+  reed buzz, key click transient, and sub-harmonic warmth. Vibrato dialed back
+  to subtle, delayed onset.
+
+## 0.40.4
+
+- **Distortion overhaul** — multi-stage clipping (preamp → power amp →
+  asymmetric rectifier) replaces single-stage tanh. Crunch, distorted,
+  orange crunch, and metal guitar presets now sound properly driven.
+
+## 0.40.3
+
+- **Crotales synth** — tuned bronze discs with long ring and bright harmonics
+- **Tingsha synth** — paired Tibetan cymbals with beating from two detuned discs
+- **Rain stick** — cascading pebbles (steep and slow/shallow variants)
+- **Ocean drum** — steel beads rolling inside a frame drum, surf wash
+- **Cabasa** — metal bead chain on cylinder, bright metallic scrape
+- **Wind chimes** — multiple suspended metal tubes ringing at random offsets
+- **Finger cymbal** — single zill tap, bright metallic ping
+- `crotales`, `tingsha`, `singing_bowl`, `singing_bowl_ring` instrument presets
+- Audio demos in docs for all new sounds
+
+## 0.40.2
+
+- **Master compressor dialed back** — threshold raised from 0.5 to 0.7,
+  makeup gain capped at 3x. Sparse arrangements no longer get
+  over-amplified to clipping.
+
+## 0.40.1
+
+- **Singing bowl synth** — two variants: strike (mallet hit with chirp
+  and long decay) and ring (rim-rubbed sustained tone with slow build).
+  Inharmonic partials beat against near-degenerate mode pairs for
+  authentic Himalayan bowl shimmer.
+- `singing_bowl` and `singing_bowl_ring` instrument presets
+- Audio demos in docs for both variants
+
+## 0.40.0
+
+- **Rhodes electric piano synth** — tine + tonebar + electromagnetic
+  pickup model. `electric_piano` preset now uses dedicated `rhodes_synth`
+  instead of FM
+- **73 audio demos in docs** — every synth, every drum pattern, every
+  code example with `play_score()` now has an embedded audio player
+- Idiomatic demos: harp arpeggiates, guitars strum, cello bows, sitar
+  drones, strings use ensemble
+- Trailing silence trimming on all audio exports
+- Raw waveform demos (no envelope) for classic waveforms
+
 ## 0.39.3
 
 - **33 audio samples in documentation** — every `play_score()` example

demo_new_synths.py

@@ -0,0 +1,207 @@
+"""Demo the 5 new synths: Mellotron, Hard Sync, Ring Mod, Wavefold, Drift.
+
+Each synth gets a short musical phrase — not just a scale run — with
+reverb and rhythmic variety to show off its character.
+"""
+from pytheory import Score, Duration, play_score
+
+EIGHTH = Duration.EIGHTH
+QUARTER = Duration.QUARTER
+HALF = Duration.HALF
+DOTTED_Q = Duration.DOTTED_QUARTER
+WHOLE = Duration.WHOLE
+
+
+# ── Mellotron Strings ────────────────────────────────────────────────────────
+# Strawberry Fields vibes — slow, haunted, with rests that breathe.
+
+print("=== MELLOTRON STRINGS ===")
+s = Score("4/4", bpm=72)
+p = s.part("tape", instrument="mellotron_strings",
+           reverb=0.45, reverb_type="cathedral", reverb_decay=2.0)
+p.add("G4", HALF).add("B4", QUARTER).add("D5", QUARTER)
+p.add("C5", DOTTED_Q).add("B4", EIGHTH).add("A4", HALF)
+p.rest(QUARTER)
+p.add("G4", DOTTED_Q).add("F#4", EIGHTH).add("G4", WHOLE)
+play_score(s)
+
+
+# ── Mellotron Flute ──────────────────────────────────────────────────────────
+# Lonely, breathy, with space between phrases.
+
+print("\n=== MELLOTRON FLUTE ===")
+s = Score("3/4", bpm=84)
+p = s.part("flute", instrument="mellotron_flute",
+           reverb=0.5, reverb_type="taj_mahal", reverb_decay=2.5)
+p.add("E5", HALF).add("D5", QUARTER)
+p.add("C5", DOTTED_Q).add("B4", EIGHTH).rest(QUARTER)
+p.add("A4", HALF).add("G4", QUARTER)
+p.add("A4", HALF).rest(QUARTER)
+p.add("E5", QUARTER).add("D5", QUARTER).add("C5", QUARTER)
+p.add("B4", HALF + QUARTER)
+play_score(s)
+
+
+# ── Mellotron Choir ──────────────────────────────────────────────────────────
+# Ghostly pad — slow chords, big reverb.
+
+print("\n=== MELLOTRON CHOIR ===")
+s = Score("4/4", bpm=60)
+p = s.part("choir", instrument="mellotron_choir",
+           reverb=0.6, reverb_type="cathedral", reverb_decay=3.0)
+p.add("C4", WHOLE)
+p.add("E4", HALF).add("G4", HALF)
+p.add("A4", DOTTED_Q).add("G4", EIGHTH).add("F4", HALF)
+p.add("E4", WHOLE)
+play_score(s)
+
+
+# ── Hard Sync Lead ───────────────────────────────────────────────────────────
+# Aggressive, punchy — fast 16ths and syncopation.
+
+print("\n=== HARD SYNC LEAD ===")
+s = Score("4/4", bpm=128)
+p = s.part("sync", instrument="sync_lead",
+           reverb=0.25, reverb_type="plate")
+p.add("E4", EIGHTH).add("E4", EIGHTH).rest(EIGHTH).add("G4", EIGHTH)
+p.add("A4", QUARTER).add("G4", EIGHTH).add("E4", EIGHTH)
+p.add("D4", EIGHTH).rest(EIGHTH).add("E4", EIGHTH).add("G4", EIGHTH)
+p.add("A4", HALF)
+p.rest(QUARTER).add("B4", EIGHTH).add("A4", EIGHTH)
+p.add("G4", QUARTER).add("E4", QUARTER).add("D4", HALF)
+play_score(s)
+
+
+# ── Hard Sync Bright ─────────────────────────────────────────────────────────
+# Higher slave ratio — more harmonics, screaming lead.
+
+print("\n=== HARD SYNC BRIGHT ===")
+s = Score("4/4", bpm=138)
+p = s.part("sync2", instrument="sync_lead_bright",
+           reverb=0.2, reverb_type="plate")
+p.add("A4", EIGHTH).add("C5", EIGHTH).add("D5", QUARTER)
+p.rest(EIGHTH).add("E5", EIGHTH).add("D5", EIGHTH).add("C5", EIGHTH)
+p.add("A4", QUARTER).rest(QUARTER).add("G4", EIGHTH).add("A4", EIGHTH)
+p.add("C5", HALF)
+play_score(s)
+
+
+# ── Ring Mod Bell ────────────────────────────────────────────────────────────
+# Shimmery, metallic — sparse hits with long reverb tail.
+
+print("\n=== RING MOD BELL ===")
+s = Score("4/4", bpm=66)
+p = s.part("bell", instrument="ring_mod_bell",
+           reverb=0.6, reverb_type="cave", reverb_decay=3.0)
+p.add("C5", HALF).rest(QUARTER).add("G4", QUARTER)
+p.rest(HALF).add("E5", HALF)
+p.add("D5", QUARTER).rest(QUARTER).add("C5", HALF)
+p.rest(WHOLE)
+p.add("G4", QUARTER).add("A4", QUARTER).add("C5", HALF)
+play_score(s)
+
+
+# ── Ring Mod Metallic ────────────────────────────────────────────────────────
+# Alien, inharmonic — atonal stabs.
+
+print("\n=== RING MOD METALLIC ===")
+s = Score("4/4", bpm=100)
+p = s.part("metal", instrument="ring_mod_metallic",
+           reverb=0.4, reverb_type="parking_garage", reverb_decay=2.0)
+p.add("F4", EIGHTH).rest(EIGHTH).add("Ab4", EIGHTH).add("F4", EIGHTH)
+p.rest(QUARTER).add("Db5", QUARTER).rest(QUARTER)
+p.add("C5", EIGHTH).add("Ab4", EIGHTH).rest(QUARTER).add("F4", HALF)
+p.rest(HALF).add("Db5", QUARTER).add("C5", QUARTER)
+play_score(s)
+
+
+# ── Wavefold Warm ────────────────────────────────────────────────────────────
+# Gentle folds — round and musical, like a filtered saw with overtones.
+
+print("\n=== WAVEFOLD WARM ===")
+s = Score("4/4", bpm=108)
+p = s.part("fold", instrument="wavefold_warm",
+           reverb=0.3, reverb_type="plate")
+p.add("A3", QUARTER).add("C4", QUARTER).add("E4", QUARTER).add("A4", QUARTER)
+p.add("G4", DOTTED_Q).add("E4", EIGHTH).add("C4", HALF)
+p.add("D4", QUARTER).add("F4", QUARTER).add("A4", HALF)
+p.add("G4", WHOLE)
+play_score(s)
+
+
+# ── Wavefold Gnarly ──────────────────────────────────────────────────────────
+# Cranked folds — buzzy, aggressive, with syncopation.
+
+print("\n=== WAVEFOLD GNARLY ===")
+s = Score("4/4", bpm=130)
+p = s.part("gnarly", instrument="wavefold_gnarly",
+           reverb=0.2, reverb_type="spring")
+p.add("E3", EIGHTH).add("E3", EIGHTH).rest(EIGHTH).add("G3", EIGHTH)
+p.add("A3", EIGHTH).rest(EIGHTH).add("B3", EIGHTH).add("A3", EIGHTH)
+p.add("E3", QUARTER).add("G3", EIGHTH).add("A3", EIGHTH).add("B3", QUARTER)
+p.rest(QUARTER)
+p.add("E4", EIGHTH).add("D4", EIGHTH).add("B3", QUARTER).add("A3", HALF)
+play_score(s)
+
+
+# ── Drift Saw ────────────────────────────────────────────────────────────────
+# Warm, alive analog saw — the Minimoog pad.
+
+print("\n=== DRIFT SAW (vintage VCO) ===")
+s = Score("4/4", bpm=88)
+p = s.part("drift", instrument="drift_saw",
+           reverb=0.35, reverb_type="taj_mahal", reverb_decay=2.0)
+p.add("D4", HALF).add("F4", HALF)
+p.add("A4", DOTTED_Q).add("G4", EIGHTH).add("F4", QUARTER).rest(QUARTER)
+p.add("D4", QUARTER).add("E4", QUARTER).add("F4", HALF)
+p.add("D4", WHOLE)
+play_score(s)
+
+
+# ── Drift Square ─────────────────────────────────────────────────────────────
+# Hollow, wobbly — 8-bit with analog soul.
+
+print("\n=== DRIFT SQUARE ===")
+s = Score("4/4", bpm=110)
+p = s.part("dsq", instrument="drift_square",
+           reverb=0.25, reverb_type="plate")
+p.add("C4", EIGHTH).add("E4", EIGHTH).add("G4", QUARTER).add("E4", QUARTER)
+p.rest(QUARTER)
+p.add("A4", EIGHTH).add("G4", EIGHTH).add("E4", QUARTER).add("C4", HALF)
+p.add("D4", QUARTER).add("F4", EIGHTH).add("G4", EIGHTH).add("A4", HALF)
+p.add("G4", WHOLE)
+play_score(s)
+
+
+# ── Analog Pad ───────────────────────────────────────────────────────────────
+# Slow, drifting chords — Juno-style lushness.
+
+print("\n=== ANALOG PAD ===")
+s = Score("4/4", bpm=70)
+p = s.part("pad", instrument="analog_pad",
+           reverb=0.5, reverb_type="taj_mahal", reverb_decay=3.0)
+p.add("A3", WHOLE)
+p.add("C4", HALF).add("E4", HALF)
+p.add("F4", WHOLE)
+p.add("E4", HALF).add("D4", HALF)
+p.add("C4", WHOLE)
+play_score(s)
+
+
+# ── Analog Bass ──────────────────────────────────────────────────────────────
+# Tight, punchy — Moog bass with filter sweep.
+
+print("\n=== ANALOG BASS ===")
+s = Score("4/4", bpm=120)
+p = s.part("bass", instrument="analog_bass",
+           reverb=0.1, reverb_type="plate")
+p.add("E2", EIGHTH).add("E2", EIGHTH).rest(EIGHTH).add("G2", EIGHTH)
+p.add("A2", QUARTER).rest(QUARTER)
+p.add("E2", EIGHTH).rest(EIGHTH).add("B2", EIGHTH).add("A2", EIGHTH)
+p.add("G2", QUARTER).add("E2", QUARTER).rest(HALF)
+p.add("E2", EIGHTH).add("E2", EIGHTH).add("G2", EIGHTH).add("A2", EIGHTH)
+p.add("B2", QUARTER).add("A2", QUARTER).add("E2", HALF)
+play_score(s)
+
+
+print("\nDone!")

docs/generate_audio.py

@@ -23,7 +23,20 @@ os.makedirs(AUDIO_DIR, exist_ok=True)
 
 
 def save_wav(buf, path):
-    """Save a float32 buffer as 16-bit stereo WAV."""
+    """Save a float32 buffer as 16-bit stereo WAV, trimming trailing silence."""
+    # Trim trailing silence (below -60dB threshold)
+    threshold = 0.001
+    if buf.ndim == 2:
+        amplitude = numpy.abs(buf).max(axis=1)
+    else:
+        amplitude = numpy.abs(buf)
+    # Find last sample above threshold
+    above = numpy.where(amplitude > threshold)[0]
+    if len(above) > 0:
+        # Keep 0.2s of tail after last audible sample for natural decay
+        tail = min(int(SAMPLE_RATE * 0.2), len(buf) - above[-1])
+        buf = buf[:above[-1] + tail]
+
     # Handle both mono (n,) and stereo (n, 2) buffers
     if buf.ndim == 1:
         channels = 1
@@ -172,43 +185,74 @@ def gen_tabla():
     score = Score("4/4", bpm=80)
     score.drums("teental", repeats=2)
     score.drums("chakradar", repeats=1)
-    score.set_drum_effects(reverb=0.2)
+    score.set_drum_effects(reverb=0.3, reverb_type="hall")
     render("tabla", score)
 
 
 # ── Marching snare ───────────────────────────────────────────────────────
 
 def gen_metal_blast():
-    score = Score("4/4", bpm=200)
-    score.drums("metal blast", repeats=8, fill="metal cascade", fill_every=4)
+    score = Score("4/4", bpm=190)
+    # Showcase all metal patterns: groove → gallop → triplet fill → blast
+    score.drums("metal groove", repeats=2)
+    score.drums("metal gallop", repeats=4, fill="metal triplet", fill_every=4)
+    score.drums("metal blast", repeats=2, fill="metal cascade", fill_every=2)
+    score.drums("double kick", repeats=2, fill="metal blast", fill_every=2)
     render("metal_blast", score)
 
 
 def gen_cajon():
     score = Score("4/4", bpm=100)
     score.drums("cajon", repeats=8, fill="cajon flam", fill_every=4)
+    score.set_drum_effects(reverb=0.25, reverb_type="room")
     render("cajon", score)
 
 
 def gen_tabla_teental():
     score = Score("4/4", bpm=160)
-    score.drums("teental", repeats=4)
-    score.set_drum_effects(reverb=0.2)
+    score.drums("teental", repeats=3)
+    score.drums("teental", repeats=1, fill="bayan", fill_every=1)
+    score.set_drum_effects(reverb=0.3, reverb_type="hall")
     render("tabla_teental", score)
 
 
 def gen_tabla_keherwa():
     score = Score("4/4", bpm=180)
-    score.drums("keherwa", repeats=4, fill="chakkardar", fill_every=4)
-    score.set_drum_effects(reverb=0.2)
+    # Manual part so we can add ge_bend hits
+    tabla = score.part("tabla", synth="sine", volume=0.5, reverb=0.3, reverb_type="hall")
+    DHA = DrumSound.TABLA_DHA
+    NA = DrumSound.TABLA_NA
+    TIN = DrumSound.TABLA_TIN
+    TIT = DrumSound.TABLA_TIT
+    GE = DrumSound.TABLA_GE
+    GB = DrumSound.TABLA_GE_BEND
+    # Keherwa with ge_bend accents
+    for _ in range(3):
+        tabla.hit(DHA, Duration.EIGHTH, velocity=90, articulation="accent")
+        tabla.hit(GE, Duration.EIGHTH, velocity=65)
+        tabla.hit(NA, Duration.EIGHTH, velocity=72)
+        tabla.hit(TIT, Duration.EIGHTH, velocity=45)
+        tabla.hit(NA, Duration.EIGHTH, velocity=68)
+        tabla.hit(TIT, Duration.EIGHTH, velocity=42)
+        tabla.hit(DHA, Duration.EIGHTH, velocity=85, articulation="accent")
+        tabla.hit(NA, Duration.EIGHTH, velocity=70)
+    # Last bar with bayan bends
+    tabla.hit(DHA, Duration.EIGHTH, velocity=95, articulation="marcato")
+    tabla.hit(GB, Duration.EIGHTH, velocity=80)
+    tabla.hit(NA, Duration.EIGHTH, velocity=72)
+    tabla.hit(GB, Duration.EIGHTH, velocity=82)
+    tabla.hit(DHA, Duration.EIGHTH, velocity=100, articulation="accent")
+    tabla.hit(GB, Duration.EIGHTH, velocity=85)
+    tabla.hit(DHA, Duration.QUARTER, velocity=110, articulation="fermata")
     render("tabla_keherwa", score)
 
 
 def gen_tabla_chakradar():
     score = Score("4/4", bpm=200)
-    score.drums("teental", repeats=2)
+    score.drums("teental", repeats=1)
+    score.drums("teental", repeats=1, fill="bayan", fill_every=1)
     score.drums("chakradar", repeats=1)
-    score.set_drum_effects(reverb=0.2)
+    score.set_drum_effects(reverb=0.3, reverb_type="hall")
     render("tabla_chakradar", score)
 
 
@@ -232,31 +276,120 @@ def gen_mridangam():
 
 def gen_march_snare():
     score = Score("4/4", bpm=120)
-    p = score.part("snare", synth="sine", volume=0.8, reverb=0.15)
+
     S = DrumSound.MARCH_SNARE
     R = DrumSound.MARCH_RIMSHOT
     C = DrumSound.MARCH_CLICK
+    Q1 = DrumSound.QUAD_1
+    Q2 = DrumSound.QUAD_2
+    Q3 = DrumSound.QUAD_3
+    Q4 = DrumSound.QUAD_4
+    QS = DrumSound.QUAD_SPOCK
+    B1 = DrumSound.BASS_1
+    B2 = DrumSound.BASS_2
+    B3 = DrumSound.BASS_3
+    B4 = DrumSound.BASS_4
+    B5 = DrumSound.BASS_5
 
-    for _ in range(4):
-        p.hit(C, Duration.QUARTER, velocity=95)
+    # Snare line — 8 players (high volume to compensate for ensemble division)
+    sn = score.part("snares", synth="sine", volume=1.5, reverb=0.2, ensemble=8)
+    # Quads — 4 players
+    q = score.part("quads", synth="sine", volume=0.5, reverb=0.2, ensemble=4)
+    # Basses — 5 players
+    b = score.part("basses", synth="sine", volume=0.55, reverb=0.2, ensemble=5)
 
+    # Click count-off
     for _ in range(4):
-        p.hit(R, Duration.SIXTEENTH, velocity=118)
-        p.hit(S, Duration.SIXTEENTH, velocity=30)
-        p.hit(S, Duration.SIXTEENTH, velocity=32)
-        p.hit(S, Duration.SIXTEENTH, velocity=28)
-        p.hit(R, Duration.SIXTEENTH, velocity=115)
-        p.hit(S, Duration.SIXTEENTH, velocity=30)
-        p.hit(S, Duration.SIXTEENTH, velocity=28)
-        p.hit(S, Duration.SIXTEENTH, velocity=32)
-        p.hit(R, Duration.SIXTEENTH, velocity=118)
-        p.hit(S, Duration.SIXTEENTH, velocity=35)
-        p.hit(S, Duration.SIXTEENTH, velocity=28)
-        p.hit(S, Duration.SIXTEENTH, velocity=30)
-        p.hit(R, Duration.SIXTEENTH, velocity=120)
-        p.hit(S, Duration.SIXTEENTH, velocity=30)
-        p.hit(S, Duration.SIXTEENTH, velocity=28)
-        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        sn.hit(C, Duration.QUARTER, velocity=95)
+        q.rest(Duration.QUARTER)
+        b.rest(Duration.QUARTER)
+
+    # Bar 1-2: snare groove, quads accent, bass on beats
+    for _ in range(2):
+        sn.hit(R, Duration.SIXTEENTH, velocity=118)
+        sn.hit(S, Duration.SIXTEENTH, velocity=30)
+        sn.hit(S, Duration.SIXTEENTH, velocity=32)
+        sn.hit(S, Duration.SIXTEENTH, velocity=28)
+        sn.hit(R, Duration.SIXTEENTH, velocity=115)
+        sn.hit(S, Duration.SIXTEENTH, velocity=30)
+        sn.hit(S, Duration.SIXTEENTH, velocity=28)
+        sn.hit(S, Duration.SIXTEENTH, velocity=32)
+        sn.hit(R, Duration.SIXTEENTH, velocity=118)
+        sn.hit(S, Duration.SIXTEENTH, velocity=35)
+        sn.hit(S, Duration.SIXTEENTH, velocity=28)
+        sn.hit(S, Duration.SIXTEENTH, velocity=30)
+        sn.hit(R, Duration.SIXTEENTH, velocity=120)
+        sn.hit(S, Duration.SIXTEENTH, velocity=30)
+        sn.hit(S, Duration.SIXTEENTH, velocity=28)
+        sn.hit(S, Duration.SIXTEENTH, velocity=32)
+
+        q.hit(Q1, Duration.SIXTEENTH, velocity=95)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q4, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q4, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=95)
+        q.hit(QS, Duration.SIXTEENTH, velocity=100)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=55)
+        q.hit(QS, Duration.SIXTEENTH, velocity=100)
+        q.hit(Q4, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=90)
+
+        b.hit(B3, Duration.QUARTER, velocity=100)
+        b.hit(B1, Duration.EIGHTH, velocity=90)
+        b.hit(B5, Duration.EIGHTH, velocity=95)
+        b.hit(B3, Duration.QUARTER, velocity=100)
+        b.hit(B5, Duration.EIGHTH, velocity=90)
+        b.hit(B1, Duration.EIGHTH, velocity=95)
+
+    # Bar 3: flams + diddles
+    sn.flam(S, Duration.QUARTER, velocity=120)
+    sn.diddle(S, Duration.EIGHTH, velocity=45)
+    sn.hit(S, Duration.SIXTEENTH, velocity=30)
+    sn.hit(S, Duration.SIXTEENTH, velocity=32)
+    sn.flam(S, Duration.QUARTER, velocity=118)
+    sn.diddle(S, Duration.EIGHTH, velocity=42)
+    sn.hit(S, Duration.SIXTEENTH, velocity=28)
+    sn.hit(S, Duration.SIXTEENTH, velocity=30)
+
+    q.hit(Q1, Duration.QUARTER, velocity=95)
+    q.hit(Q3, Duration.EIGHTH, velocity=55)
+    q.hit(Q2, Duration.SIXTEENTH, velocity=55)
+    q.hit(Q4, Duration.SIXTEENTH, velocity=55)
+    q.hit(QS, Duration.QUARTER, velocity=100)
+    q.hit(Q4, Duration.EIGHTH, velocity=55)
+    q.hit(Q1, Duration.EIGHTH, velocity=90)
+
+    b.hit(B5, Duration.QUARTER, velocity=100)
+    b.hit(B3, Duration.QUARTER, velocity=95)
+    b.hit(B1, Duration.QUARTER, velocity=100)
+    b.hit(B3, Duration.QUARTER, velocity=95)
+
+    # Bar 4: buzz roll finale into big hit
+    for i in range(28):
+        sn.hit(S, 0.0625, velocity=min(25 + i * 3, 100))
+    sn.hit(R, Duration.EIGHTH, velocity=125)
+    sn.hit(R, Duration.EIGHTH, velocity=127)
+
+    for i in range(8):
+        q.hit([Q1,Q2,Q3,Q4,Q4,Q3,Q2,Q1][i], Duration.SIXTEENTH, velocity=60+i*4)
+    q.hit(QS, Duration.HALF, velocity=110)
+
+    b.hit(B1, Duration.SIXTEENTH, velocity=90)
+    b.hit(B2, Duration.SIXTEENTH, velocity=90)
+    b.hit(B3, Duration.SIXTEENTH, velocity=90)
+    b.hit(B4, Duration.SIXTEENTH, velocity=90)
+    b.hit(B5, Duration.SIXTEENTH, velocity=95)
+    b.hit(B4, Duration.SIXTEENTH, velocity=90)
+    b.hit(B3, Duration.SIXTEENTH, velocity=90)
+    b.hit(B2, Duration.SIXTEENTH, velocity=90)
+    b.hit(B3, Duration.HALF, velocity=100)
+
     render("march_snare", score)
 
 
@@ -391,6 +524,470 @@ def gen_jazz_ballad():
 
 # ── Quickstart example ───────────────────────────────────────────────────
 
+# ── Synth waveform demos ──────────────────────────────────────────────────
+
+def _synth_demo(name, synth, envelope="none", **kwargs):
+    """Short C major melody on a given synth."""
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth=synth, envelope=envelope, volume=0.5,
+                   reverb=0.2, **kwargs)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render(f"synth_{name}", score)
+
+
+def gen_synth_sine():
+    _synth_demo("sine", "sine")
+
+def gen_synth_saw():
+    _synth_demo("saw", "saw")
+
+def gen_synth_triangle():
+    _synth_demo("triangle", "triangle")
+
+def gen_synth_square():
+    _synth_demo("square", "square")
+
+def gen_synth_piano():
+    score = Score("4/4", bpm=85)
+    p = score.part("demo", instrument="piano", volume=0.5, reverb=0.3)
+    # Hold chords with melody on top
+    p.hold("C3", Duration.WHOLE * 2, velocity=60)
+    p.hold("E3", Duration.WHOLE * 2, velocity=55)
+    p.hold("G3", Duration.WHOLE * 2, velocity=55)
+    for n in ["E4", "G4", "C5", "G4", "E4", "D4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=80)
+    render("synth_piano", score)
+
+def gen_synth_acoustic_guitar():
+    from pytheory import Fretboard
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="acoustic_guitar", volume=0.5,
+                   reverb=0.25, fretboard=Fretboard.guitar())
+    for ch in ["G", "D", "Em", "C"]:
+        p.strum(ch, Duration.WHOLE, velocity=75)
+    render("synth_acoustic_guitar", score)
+
+def gen_synth_pulse():
+    _synth_demo("pulse", "pulse")
+
+def gen_synth_noise():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="noise", envelope="pad", volume=0.3,
+                   lowpass=2000, reverb=0.3)
+    p.add("C4", Duration.WHOLE * 2, velocity=80)
+    render("synth_noise", score)
+
+def gen_synth_pwm_slow():
+    _synth_demo("pwm_slow", "pwm_slow", envelope="pad")
+
+def gen_synth_pwm_fast():
+    _synth_demo("pwm_fast", "pwm_fast")
+
+def gen_synth_fm():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="fm", envelope="bell", volume=0.5,
+                   fm_ratio=3.0, fm_index=5.0, reverb=0.3)
+    for n in ["C5", "E5", "G5", "C6", "G5", "E5", "C5", "E5"]:
+        p.add(n, Duration.QUARTER, velocity=80)
+    render("synth_fm", score)
+
+def gen_synth_rhodes():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", instrument="electric_piano", volume=0.5, reverb=0.3)
+    # Jazz chords with hold
+    p.hold("C3", Duration.WHOLE * 2, velocity=60)
+    p.hold("E3", Duration.WHOLE * 2, velocity=55)
+    p.hold("Bb3", Duration.WHOLE * 2, velocity=55)
+    for n in ["G4", "Bb4", "C5", "Bb4", "G4", "F4", "E4", "G4"]:
+        p.add(n, Duration.QUARTER, velocity=75)
+    render("synth_rhodes", score)
+
+def gen_synth_supersaw():
+    _synth_demo("supersaw", "supersaw", envelope="pad")
+
+def gen_synth_bass_guitar():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="bass_guitar_synth", envelope="none",
+                   volume=0.5, reverb=0.2)
+    for n in ["C2", "E2", "G2", "C3", "G2", "E2", "C2", "E2"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_bass_guitar", score)
+
+def gen_synth_flute():
+    _synth_demo("flute", "flute_synth", envelope="none")
+
+def gen_synth_trumpet():
+    _synth_demo("trumpet", "trumpet_synth", envelope="none")
+
+def gen_synth_clarinet():
+    _synth_demo("clarinet", "clarinet_synth", envelope="none")
+
+def gen_synth_oboe():
+    _synth_demo("oboe", "oboe_synth", envelope="none")
+
+def gen_synth_cello():
+    score = Score("4/4", bpm=70)
+    p = score.part("demo", instrument="cello", volume=0.5, reverb=0.3, ensemble=3)
+    for n in ["C3", "E3", "G3", "C4"]:
+        p.add(n, Duration.WHOLE, velocity=80)
+    render("synth_cello", score)
+
+def gen_synth_harpsichord():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="harpsichord_synth", envelope="none",
+                   volume=0.5, reverb=0.25)
+    # Baroque ornamental runs
+    p.hold("C3", Duration.WHOLE, velocity=70)
+    for n in ["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"]:
+        p.add(n, Duration.EIGHTH, velocity=80)
+    p.hold("G3", Duration.WHOLE, velocity=70)
+    for n in ["C5", "B4", "A4", "G4", "F4", "E4", "D4", "C4"]:
+        p.add(n, Duration.EIGHTH, velocity=78)
+    render("synth_harpsichord", score)
+
+def gen_synth_electric_guitar():
+    from pytheory import Fretboard
+    score = Score("4/4", bpm=110)
+    p = score.part("demo", instrument="electric_guitar", volume=0.5,
+                   reverb=0.15, fretboard=Fretboard.guitar())
+    for ch in ["Am", "F", "C", "G"]:
+        p.strum(ch, Duration.WHOLE, velocity=80)
+    render("synth_electric_guitar", score)
+
+def gen_synth_kalimba():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="kalimba", volume=0.5, reverb=0.3)
+    for n in ["C5", "E5", "G5", "C6", "G5", "E5", "C5", "E5"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_kalimba", score)
+
+def gen_synth_wurlitzer():
+    score = Score("4/4", bpm=90)
+    p = score.part("demo", instrument="wurlitzer", volume=0.5, reverb=0.25)
+    p.hold("C3", Duration.WHOLE * 2, velocity=60)
+    p.hold("Eb3", Duration.WHOLE * 2, velocity=55)
+    p.hold("G3", Duration.WHOLE * 2, velocity=55)
+    for n in ["G4", "Bb4", "C5", "Bb4", "G4", "F4", "Eb4", "G4"]:
+        p.add(n, Duration.QUARTER, velocity=78)
+    render("synth_wurlitzer", score)
+
+def gen_synth_vibraphone():
+    score = Score("4/4", bpm=90)
+    p = score.part("demo", instrument="vibraphone", volume=0.5)
+    for n in ["C5", "E5", "G5", "C6", "G5", "E5", "C5", "E5"]:
+        p.add(n, Duration.QUARTER, velocity=75)
+    render("synth_vibraphone", score)
+
+def gen_synth_pipe_organ():
+    score = Score("4/4", bpm=70)
+    p = score.part("demo", instrument="pipe_organ", volume=0.5)
+    p.hold("C3", Duration.WHOLE * 4, velocity=70)
+    p.hold("G3", Duration.WHOLE * 4, velocity=65)
+    for n in ["C4", "D4", "E4", "F4", "G4", "F4", "E4", "D4",
+              "C4", "E4", "G4", "C5", "G4", "E4", "C4", "C4"]:
+        p.add(n, Duration.QUARTER, velocity=75)
+    render("synth_pipe_organ", score)
+
+def gen_synth_choir():
+    score = Score("4/4", bpm=70)
+    p = score.part("demo", instrument="choir", volume=0.5)
+    for n, v in [("C4", "ah"), ("E4", "oh"), ("G4", "ah"), ("C5", "ee"),
+                 ("G4", "oh"), ("E4", "ah"), ("C4", "oo"), ("C4", "ah")]:
+        p.add(n, Duration.HALF, velocity=70, lyric=v)
+    render("synth_choir", score)
+
+def gen_synth_organ():
+    _synth_demo("organ", "organ_synth", envelope="organ")
+
+def gen_synth_marimba():
+    _synth_demo("marimba", "marimba_synth", envelope="mallet")
+
+def gen_synth_sitar():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", instrument="sitar", volume=0.4, reverb=0.35)
+    # Drone under melody
+    p.hold("C3", Duration.WHOLE * 4, velocity=55)
+    for n, d in [("C4", 1.0), ("D4", 0.5), ("E4", 0.5), ("G4", 1.0),
+                 ("A4", 0.5), ("G4", 0.5), ("E4", 1.0), ("D4", 0.5),
+                 ("C4", 0.5), ("D4", 1.0), ("C4", 2.0)]:
+        p.add(n, d, velocity=75)
+    render("synth_sitar", score)
+
+
+def gen_synth_harp():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", synth="harp_synth", envelope="none",
+                   volume=0.5, reverb=0.3)
+    # Arpeggiated chords with hold — harp style
+    p.hold("C3", Duration.WHOLE * 2, velocity=70)
+    for n in ["E4", "G4", "C5", "E5", "G5", "C5", "G4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=75)
+    render("synth_harp", score)
+
+def gen_synth_upright_bass():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="upright_bass_synth", envelope="none",
+                   volume=0.5, reverb=0.2)
+    for n in ["C2", "E2", "G2", "C3", "G2", "E2", "C2", "E2"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_upright_bass", score)
+
+def gen_synth_timpani():
+    score = Score("4/4", bpm=140)
+    timp = score.part("timp", synth="timpani_synth", volume=0.5, reverb=0.25)
+    timp.roll("C3", Duration.WHOLE, velocity_start=20, velocity_end=110, speed=0.125)
+    timp.add("C3", Duration.HALF, velocity=127)
+    timp.rest(Duration.HALF)
+    timp.roll("G2", Duration.WHOLE, velocity_start=20, velocity_end=110, speed=0.125)
+    timp.add("G2", Duration.HALF, velocity=127)
+    render("synth_timpani", score)
+
+def gen_synth_strings():
+    score = Score("4/4", bpm=70)
+    p = score.part("demo", synth="strings_synth", envelope="bowed",
+                   volume=0.5, reverb=0.35, ensemble=8)
+    for n in ["C4", "E4", "G4", "C5"]:
+        p.add(n, Duration.WHOLE, velocity=75)
+    render("synth_strings", score)
+
+def gen_synth_saxophone():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="tenor_sax", 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_saxophone", score)
+
+def gen_synth_pedal_steel():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="pedal_steel", volume=0.5, reverb=0.3)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_pedal_steel", score)
+
+def gen_synth_theremin():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="theremin", volume=0.5, reverb=0.3)
+    for n in ["C4", "E4", "G4", "C5", "G4", "E4", "C4", "E4"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_theremin", score)
+
+def gen_synth_steel_drum():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", instrument="steel_drum", volume=0.5, reverb=0.2)
+    for n in ["C5", "E5", "G5", "C6", "G5", "E5", "C5", "E5"]:
+        p.add(n, Duration.QUARTER, velocity=85)
+    render("synth_steel_drum", score)
+
+def gen_synth_accordion():
+    score = Score("4/4", bpm=110)
+    p = score.part("demo", instrument="accordion", volume=0.5, reverb=0.2)
+    # Waltz feel with held chords
+    p.hold("C3", Duration.WHOLE, velocity=65)
+    p.hold("E3", Duration.WHOLE, velocity=60)
+    p.hold("G3", Duration.WHOLE, velocity=60)
+    for n in ["E4", "G4", "C5", "G4"]:
+        p.add(n, Duration.QUARTER, velocity=78)
+    p.hold("F3", Duration.WHOLE, velocity=65)
+    p.hold("A3", Duration.WHOLE, velocity=60)
+    p.hold("C4", Duration.WHOLE, velocity=60)
+    for n in ["A4", "C5", "F5", "C5"]:
+        p.add(n, Duration.QUARTER, velocity=78)
+    render("synth_accordion", score)
+
+def gen_synth_didgeridoo():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", instrument="didgeridoo", volume=0.5, reverb=0.3)
+    p.add("C2", Duration.WHOLE * 2, velocity=85)
+    render("synth_didgeridoo", score)
+
+def gen_synth_bagpipe():
+    score = Score("4/4", bpm=90)
+    p = score.part("demo", instrument="bagpipe", volume=0.4, reverb=0.2)
+    # Drone on low A + E (like real Highland pipes)
+    p.hold("A3", Duration.WHOLE * 4, velocity=70)
+    p.hold("E3", Duration.WHOLE * 4, velocity=65)
+    # Chanter melody on top
+    for n, d in [("A4", 1.0), ("B4", 0.5), ("C5", 0.5), ("D5", 1.0),
+                 ("E5", 1.0), ("D5", 0.5), ("C5", 0.5), ("B4", 1.0),
+                 ("A4", 1.0), ("G4", 1.0), ("A4", 2.0)]:
+        p.add(n, d, velocity=80)
+    render("synth_bagpipe", score)
+
+def gen_synth_banjo():
+    from pytheory import Fretboard
+    score = Score("4/4", bpm=130)
+    p = score.part("demo", instrument="banjo", volume=0.5, reverb=0.15,
+                   fretboard=Fretboard.guitar())
+    # Strum into a picking lick
+    p.strum("G", Duration.WHOLE, velocity=80)
+    p.strum("C", Duration.WHOLE, velocity=78)
+    # Bluegrass lick — 16th note picking
+    for n in ["G4", "B4", "D5", "G5", "D5", "B4", "A4", "G4",
+              "D4", "G4", "B4", "D5", "B4", "G4", "D4", "G4"]:
+        p.add(n, Duration.SIXTEENTH, velocity=82)
+    render("synth_banjo", score)
+
+def gen_synth_mandolin():
+    score = Score("4/4", bpm=110)
+    p = score.part("demo", instrument="mandolin", volume=0.5, reverb=0.2)
+    # Tremolo rolls on held notes — the mandolin signature
+    p.roll("G4", Duration.WHOLE, velocity_start=65, velocity_end=85, speed=Duration.SIXTEENTH)
+    p.roll("A4", Duration.WHOLE, velocity_start=65, velocity_end=85, speed=Duration.SIXTEENTH)
+    # Quick melody
+    for n in ["B4", "C5", "D5", "C5", "B4", "A4", "G4", "A4"]:
+        p.add(n, Duration.EIGHTH, velocity=80)
+    # End on a roll
+    p.roll("G4", Duration.WHOLE, velocity_start=70, velocity_end=90, speed=Duration.SIXTEENTH)
+    render("synth_mandolin", score)
+
+def gen_synth_ukulele():
+    from pytheory import Fretboard
+    score = Score("4/4", bpm=110)
+    p = score.part("demo", instrument="ukulele", volume=0.5, reverb=0.25,
+                   fretboard=Fretboard.ukulele())
+    for ch in ["C", "Am", "F", "G"]:
+        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)
+    for n in ["C4", "E4", "G4", "C5"]:
+        p.add(n, Duration.WHOLE, velocity=75)
+    render("synth_granular", score)
+
+
+def gen_synth_crotales():
+    score = Score("4/4", bpm=60)
+    p = score.part("demo", synth="crotales_synth", envelope="none",
+                   volume=0.5, reverb=0.3)
+    for n in ["C6", "E6", "G6", "C7", "G6", "E6", "C6"]:
+        p.add(n, Duration.HALF, velocity=80)
+    render("synth_crotales", score)
+
+
+def gen_synth_tingsha():
+    score = Score("4/4", bpm=40)
+    p = score.part("demo", synth="tingsha_synth", envelope="none",
+                   volume=0.5, reverb=0.4)
+    for n in ["E5", "A5", "E6", "A5"]:
+        p.add(n, Duration.WHOLE, velocity=75)
+    render("synth_tingsha", score)
+
+
+def gen_rainstick():
+    score = Score("4/4", bpm=60)
+    p = score.part("demo", synth="sine", volume=1.0)
+    p.hit(DrumSound.RAINSTICK, Duration.WHOLE * 3, velocity=90)
+    render("rainstick", score)
+
+
+def gen_rainstick_slow():
+    score = Score("4/4", bpm=60)
+    p = score.part("demo", synth="sine", volume=1.0)
+    p.hit(DrumSound.RAINSTICK_SLOW, Duration.WHOLE * 4, velocity=85)
+    render("rainstick_slow", score)
+
+
+def gen_ocean_drum():
+    score = Score("4/4", bpm=60)
+    p = score.part("demo", synth="sine", volume=1.0)
+    p.hit(DrumSound.OCEAN_DRUM, Duration.WHOLE * 3, velocity=85)
+    render("ocean_drum", score)
+
+
+def gen_cabasa():
+    score = Score("4/4", bpm=100)
+    p = score.part("demo", synth="sine", volume=1.0)
+    for _ in range(16):
+        p.hit(DrumSound.CABASA, Duration.EIGHTH, velocity=100)
+    render("cabasa", score)
+
+
+def gen_wind_chimes():
+    score = Score("4/4", bpm=60)
+    p = score.part("demo", synth="sine", volume=1.0)
+    p.hit(DrumSound.WIND_CHIMES, Duration.WHOLE * 3, velocity=85)
+    render("wind_chimes", score)
+
+
+def gen_finger_cymbal():
+    score = Score("4/4", bpm=80)
+    p = score.part("demo", synth="sine", volume=1.0)
+    for _ in range(8):
+        p.hit(DrumSound.FINGER_CYMBAL, Duration.QUARTER, velocity=85)
+    render("finger_cymbal", score)
+
+
+def gen_synth_singing_bowl_strike():
+    score = Score("4/4", bpm=40)
+    p = score.part("demo", synth="singing_bowl_strike_synth", envelope="none",
+                   volume=0.5, reverb=0.4)
+    for n in ["A3", "D4", "F4", "A4"]:
+        p.add(n, Duration.WHOLE, velocity=80)
+    render("synth_singing_bowl_strike", score)
+
+
+def gen_synth_singing_bowl_ring():
+    score = Score("4/4", bpm=30)
+    p = score.part("demo", synth="singing_bowl_ring_synth", envelope="none",
+                   volume=0.5, reverb=0.4)
+    for n in ["A3", "D4", "A4"]:
+        p.add(n, Duration.WHOLE * 2, velocity=75)
+    render("synth_singing_bowl_ring", score)
+
+
 def gen_arpeggio():
     score = Score("4/4", bpm=132)
     score.drums("house", repeats=8)
@@ -419,25 +1016,24 @@ def gen_legato_glide():
 
 
 def gen_quickstart():
-    score = Score("4/4", bpm=140)
-    score.drums("bossa nova", repeats=4)
-    chords = score.part("chords", synth="sine", envelope="pad",
-                        reverb=0.4, volume=0.3)
-    lead = score.part("lead", synth="saw", envelope="pluck",
-                      lowpass=2000, lowpass_q=3.0, distortion=0.8,
-                      legato=True, glide=0.03, volume=0.4)
-    bass = score.part("bass", synth="sine", lowpass=500)
-    key = Key("A", "minor")
-    for chord in key.progression("i", "iv", "V", "i"):
-        chords.add(chord, Duration.WHOLE)
-        chords.add(chord, Duration.WHOLE)
-    lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)
-    lead.arpeggio("Dm", bars=2, pattern="updown", octaves=2)
-    lead.set(lowpass=5000, reverb=0.3)
-    lead.arpeggio("E7", bars=2, pattern="up", octaves=2)
-    lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)
-    for n in ["A2", "E2", "A2", "C3"] * 4:
-        bass.add(n, Duration.QUARTER)
+    score = Score("4/4", bpm=120)
+    score.drums("rock", repeats=8, fill="rock", fill_every=4)
+    piano = score.part("piano", instrument="piano", reverb=0.3)
+    lead = score.part("lead", synth="saw", envelope="pluck", volume=0.4,
+                      delay=0.2, reverb=0.2, lowpass=4000)
+    bass = score.part("bass", synth="triangle", lowpass=900)
+    for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
+        piano.add(chord, Duration.WHOLE)
+    lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
+    lead.add("G5", 1).add("E5", 1)
+    lead.add("D5", 0.5).add("B4", 0.5).add("A4", 1)
+    lead.add("G4", 2).rest(2)
+    lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
+    lead.add("G5", 1).add("A5", 1)
+    lead.add("G5", 0.5).add("E5", 0.5).add("D5", 1)
+    lead.add("B4", 2).rest(2)
+    for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
+        bass.add(n, Duration.HALF)
     render("quickstart", score)
 
 
@@ -459,7 +1055,7 @@ def gen_complete_rock():
     lead = score.part("lead", synth="saw", envelope="pluck", volume=0.4,
                       delay=0.2, delay_time=0.33, reverb=0.2, lowpass=3000)
     bass = score.part("bass", synth="triangle", envelope="pluck", volume=0.45,
-                      lowpass=600)
+                      lowpass=1200)
     for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
         piano.add(chord, Duration.WHOLE)
     lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
@@ -550,6 +1146,66 @@ GENERATORS = [
     gen_ensemble,
     gen_strum,
     gen_swell,
+    gen_synth_sine,
+    gen_synth_saw,
+    gen_synth_triangle,
+    gen_synth_square,
+    gen_synth_pulse,
+    gen_synth_noise,
+    gen_synth_pwm_slow,
+    gen_synth_pwm_fast,
+    gen_synth_fm,
+    gen_synth_rhodes,
+    gen_synth_supersaw,
+    gen_synth_piano,
+    gen_synth_bass_guitar,
+    gen_synth_flute,
+    gen_synth_trumpet,
+    gen_synth_clarinet,
+    gen_synth_oboe,
+    gen_synth_cello,
+    gen_synth_harpsichord,
+    gen_synth_acoustic_guitar,
+    gen_synth_electric_guitar,
+    gen_synth_sitar,
+    gen_synth_kalimba,
+    gen_synth_wurlitzer,
+    gen_synth_vibraphone,
+    gen_synth_pipe_organ,
+    gen_synth_choir,
+    gen_synth_organ,
+    gen_synth_marimba,
+    gen_synth_harp,
+    gen_synth_upright_bass,
+    gen_synth_timpani,
+    gen_synth_strings,
+    gen_synth_saxophone,
+    gen_synth_pedal_steel,
+    gen_synth_theremin,
+    gen_synth_steel_drum,
+    gen_synth_accordion,
+    gen_synth_didgeridoo,
+    gen_synth_bagpipe,
+    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,
+    gen_synth_singing_bowl_strike,
+    gen_synth_singing_bowl_ring,
+    gen_rainstick,
+    gen_rainstick_slow,
+    gen_ocean_drum,
+    gen_cabasa,
+    gen_wind_chimes,
+    gen_finger_cymbal,
     gen_arpeggio,
     gen_legato_glide,
     gen_acid_house,

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
 -------------------