Mellotron, hard sync, ring mod, wavefold, drift synths + analog presets — v0.40.9

Five new synth waveforms: tape-replay Mellotron (strings/flute/choir
tapes with wow, flutter, saturation, 8s fadeout), hard sync oscillator,
ring modulation, wavefolding, and analog drift VCO with pitch
instability. 14 new instrument presets for Score.part(). Synth kwargs
now pass through play()/save()/_render(). 808 bass envelope fixed
from pluck to piano.

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

CHANGELOG.md

@@ -2,6 +2,213 @@
 
 All notable changes to PyTheory are documented here.
 
+## 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
+  now has an embedded stereo audio player. Covers quickstart, sequencing,
+  drums (all world percussion), playback, and cookbook.
+- **`docs/generate_audio.py`** — renders all doc examples to WAV
+- Numpy vectorization: cached time arrays, decay envelopes, drum hits;
+  vectorized piano harmonic synthesis
+- Fixed acid legato example (removed pad envelope, added proper 303 recipe)
+
+## 0.39.2
+
+- **Marching percussion** — snare, rimshot, and stick click sounds with
+  high-tension kevlar synthesis and woody-metallic rimshot crack
+- **`Part.flam()`**, **`Part.diddle()`**, **`Part.cheese()`** — marching
+  rudiment methods for any drum sound
+- **`Part ensemble=`** — duplicate voices with per-player timing tendencies
+  and micro pitch drift. Works on any Part (drumline, string section, choir).
+  `ensemble=20` for a full snare line, `ensemble=4` for a string quartet.
+- **Sympathetic resonance** — marching snare buzz builds up with repeated
+  hits, decays during rests (like real snare wire response)
+- **4 marching patterns** — march, cadence, paradiddle, roll
+- **Chakradar tabla pattern** — 16-beat tihai of tihais composition
+- Song #32: Snare Cadence (flams, diddles, cheese, triplets, 32nds)
+
+## 0.39.1
+
+- **Chakradar tabla pattern** — 16-beat tihai of tihais composition with
+  3 escalating phrases and a crescendo triplet finale
+
+## 0.39.0
+
+- **Dropped `numeral` dependency** — Roman numeral helpers inlined,
+  reducing supply chain surface (#47)
+- **`Part.ramp()`** — smooth parameter automation with 4 interpolation
+  curves (linear, ease_in, ease_out, ease_in_out)
+- **Articulations** — staccato, legato, marcato, tenuto, accent, fermata
+- **Dynamic curves** — crescendo(), decrescendo(), swell(), dynamics()
+- **`Part.hit()`** — individual drum sounds with articulation support
+- **Cross-choke drum damping** — djembe, hi-hats, cajón, doumbek
+- **5 new djembe patterns** + 3 djembe fills (30 fills total)
+- **6 new drum fills** — 3 cajón, 3 metal
+- **Duration arithmetic** — multiply, divide, add
+- **Improved djembe slap** synthesis
+- Song #31: Acid Tabla
+
+## 0.38.2
+
+- **`Part.ramp()`** — smooth parameter automation from current value to
+  target over a duration. Works for lowpass, reverb, distortion, chorus,
+  delay, volume, and any `.set()` parameter. Four interpolation curves:
+  linear, ease_in, ease_out, ease_in_out.
+
+## 0.38.1
+
+- **Dynamic curves** — `Part.crescendo()`, `Part.decrescendo()`,
+  `Part.swell()`, and `Part.dynamics()` for velocity ramps and custom
+  curves across a sequence of notes
+
+## 0.38.0
+
+- **Articulations** — `staccato`, `legato`, `marcato`, `tenuto`, `accent`,
+  `fermata` via `articulation=` on `Part.add()` and `Part.hold()`
+- **`Part.hit()`** — place individual drum sounds in a Part's note stream
+  with articulation, velocity, and effects support
+- **5 new djembe patterns** — dununba, tiriba, yankadi, djansa, mendiani
+- **3 new djembe fills** — djembe call, djembe roll, djembe break (30 fills total)
+- **Cross-choke drum damping** — striking one sound fades out related sounds
+  (djembe, hi-hats, cajón, doumbek)
+- **Improved djembe slap** — dry goatskin pop instead of snare-like noise
+
+## 0.37.0
+
+- **5 new djembe patterns** — dununba, tiriba, yankadi, djansa, mendiani
+- **3 new djembe fills** — djembe call, djembe roll, djembe break (30 fills total)
+- **Cross-choke drum damping** — striking one sound on a hand drum fades
+  out the ring of related sounds (djembe slap kills bass resonance, closed
+  hat chokes open hat, cajón slap dampens bass, doumbek tek dampens dum)
+- **Improved djembe slap** — dry, high-pitched goatskin pop instead of
+  snare-like noise rattle
+
+## 0.36.6
+
+- **6 new drum fills** — 3 cajón (flam, rumble, breakdown) and 3 metal
+  (triplet, blast, cascade). 27 fills total.
+- Updated drums documentation with fill lists and examples
+
+## 0.36.5
+
+- **Duration arithmetic** — `Duration.WHOLE * 2`, `Duration.HALF + Duration.QUARTER`,
+  division, and reverse multiply all work now (previously raised TypeError)
+
+## 0.36.3
+
+- **`Part.hold()`** — polyphonic overlap on a single part. Add notes
+  without advancing the beat position so they play simultaneously.
+  Enables: piano sustain, sitar drone under melody, guitar strum texture.
+- **Strum uses hold()** — leading string plays simultaneously with chord,
+  no more timing gaps or choppiness
+- **Improved songs** 1-16: humanize, velocity dynamics, reverb, saxophone
+  for blues
+- **Ctrl-C handling** — clean stop on all playback functions
+- **REPL updates** — strum, roll, bend, temperament, reference commands
+- Song #28 Descent (generative), #29 Pop Rock, #30 Sitar Drone
+- 862 tests
+
 ## 0.36.1
 
 - **7 new instrument synths:** pedal steel guitar, theremin, kalimba/thumb

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/_templates/audio.html

@@ -0,0 +1,4 @@
+<audio controls style="width: 100%; margin: 0.5em 0 1.5em 0;">
+  <source src="{{ pathto('_static/audio/' + file, 1) }}" type="audio/wav">
+  Your browser does not support the audio element.
+</audio>

docs/guide/chords.rst

@@ -322,6 +322,14 @@ against 17 known chord types (triads, 7ths, 9ths, sus, power chords).
    >>> Chord.from_tones("Bb", "D", "F").identify()
    'Bb major'
 
+Enharmonic spellings are fully supported — Cb, Fb, E#, B#, double
+sharps/flats, and unicode symbols (see :doc:`tones` for details):
+
+.. code-block:: pycon
+
+   >>> Chord.from_tones("Cb", "Eb", "Gb").identify()
+   'B minor'
+
 You can also access the root and quality separately:
 
 .. code-block:: pycon

docs/guide/cookbook.rst

@@ -411,6 +411,10 @@ Acid House Track
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/acid_house.wav" type="audio/wav"></audio>
+
 Dub Reggae with Delay Madness
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -443,6 +447,10 @@ Sparse notes into infinite echo:
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/dub_reggae.wav" type="audio/wav"></audio>
+
 Jazz Ballad with Humanize
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -480,6 +488,10 @@ The difference between a robot and a musician:
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/jazz_ballad.wav" type="audio/wav"></audio>
+
 Song with Sections
 ~~~~~~~~~~~~~~~~~~~
 
@@ -513,6 +525,10 @@ Define once, arrange freely:
    play_score(score)
    score.save_midi("my_song.mid")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/song_sections.wav" type="audio/wav"></audio>
+
 Export Everything to MIDI
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/guide/drums.rst

@@ -9,8 +9,8 @@ in Atlanta. Over a dancehall pattern, you're in Kingston. The drums ARE
 the genre -- they tell the listener's body how to move before a single
 melodic note is played.
 
-PyTheory includes a complete drum system -- 27 synthesized percussion
-sounds, 80+ pattern presets across dozens of genres, and 21 fill presets.
+PyTheory includes a complete drum system -- 51 synthesized percussion
+sounds, 95+ pattern presets across dozens of genres, and 30 fill presets.
 Every sound is generated from waveforms; no samples needed.
 
 Drum Sounds
@@ -91,7 +91,7 @@ The ``DrumSound`` enum maps to General MIDI percussion note numbers:
    >>> DrumSound.CLOSED_HAT.value
    42
 
-All 27 sounds, organized by type:
+All 51 sounds, organized by type:
 
 **Kicks:** KICK (36)
 
@@ -106,7 +106,32 @@ All 27 sounds, organized by type:
 **Percussion:** COWBELL (56), CLAVE (75), SHAKER (70), TAMBOURINE (54),
 CONGA_HIGH (63), CONGA_LOW (64), BONGO_HIGH (60), BONGO_LOW (61),
 TIMBALE_HIGH (65), TIMBALE_LOW (66), AGOGO_HIGH (67), AGOGO_LOW (68),
-GUIRO (73), MARACAS (70)
+GUIRO (73)
+
+**Tabla:** TABLA_NA (86), TABLA_TIN (87), TABLA_GE (88), TABLA_DHA (89),
+TABLA_TIT (90), TABLA_KE (91), TABLA_GE_BEND (108 -- bayan with upward
+pitch bend from palm pressing into the head)
+
+**Dhol:** DHOL_DAGGA (92), DHOL_TILLI (93), DHOL_BOTH (94)
+
+**Dholak:** DHOLAK_GE (95), DHOLAK_NA (96), DHOLAK_TIT (97)
+
+**Mridangam:** MRIDANGAM_THAM (98), MRIDANGAM_NAM (99), MRIDANGAM_DIN (100),
+MRIDANGAM_THA (101)
+
+**Djembe:** DJEMBE_BASS (102), DJEMBE_TONE (103), DJEMBE_SLAP (104)
+
+**Cajón:** CAJON_BASS (108), CAJON_SLAP (109), CAJON_TAP (110)
+
+**Metal Kit:** METAL_KICK (105), METAL_SNARE (106), METAL_HAT (107)
+
+**Marching Snare:** MARCH_SNARE (115), MARCH_RIMSHOT (116), MARCH_CLICK (118)
+
+**Quads (Tenors):** QUAD_1 (119), QUAD_2 (120), QUAD_3 (121), QUAD_4 (122),
+QUAD_SPOCK (123)
+
+**Marching Bass:** BASS_1 (124), BASS_2 (125), BASS_3 (126), BASS_4 (127),
+BASS_5 (80)
 
 Drum Synthesis
 --------------
@@ -200,8 +225,8 @@ everything to its essentials. The metal kit adds 3 dedicated sounds
 (double kick, china cymbal, stack) and 4 patterns for extreme metal
 subgenres.
 
-**World Percussion:** tabla, dhol, dholak, mridangam, djembe -- Deep
-traditions from across the globe, each with authentic sound sets and
+**World Percussion:** tabla, dhol, dholak, mridangam, djembe, cajón --
+Deep traditions from across the globe, each with authentic sound sets and
 idiomatic patterns. See the World Percussion section below for details.
 
 **Other:** funk, hip hop, bo diddley, second line, new orleans, waltz,
@@ -224,6 +249,13 @@ Playing Patterns
    play_pattern(Pattern.preset("salsa"), repeats=4, bpm=180)
    play_pattern(Pattern.preset("afrobeat"), repeats=8, bpm=110)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/rock_beat.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/bossa_nova_pattern.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/salsa_pattern.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 1.5em"><source src="../_static/audio/afrobeat_pattern.wav" type="audio/wav"></audio>
+
 Fills
 -----
 
@@ -235,14 +267,17 @@ ending and a new one is about to begin. Without fills, a drum pattern
 just loops. With them, it breathes and has structure.
 
 ``Pattern.fill()`` loads a 1-bar drum fill -- a short break that
-transitions between sections. 21 fill presets are available:
+transitions between sections. 30 fill presets are available:
 
 .. code-block:: pycon
 
    >>> Pattern.list_fills()
    ['afrobeat', 'blast', 'bossa nova', 'breakdown', 'buildup',
-    'cumbia', 'disco', 'funk', 'highlife', 'hip hop', 'house',
-    'jazz', 'jazz brush', 'metal', 'reggae', 'rock', 'rock crash',
+    'cajon breakdown', 'cajon flam', 'cajon rumble',
+    'cumbia', 'disco', 'djembe break', 'djembe call', 'djembe roll',
+    'funk', 'highlife', 'hip hop', 'house',
+    'jazz', 'jazz brush', 'metal', 'metal blast', 'metal cascade',
+    'metal triplet', 'reggae', 'rock', 'rock crash',
     'salsa', 'samba', 'second line', 'trap']
 
    >>> fill = Pattern.fill("rock")
@@ -311,6 +346,10 @@ drum pattern and all named parts are mixed together by ``play_score()``:
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/salsa_layered.wav" type="audio/wav"></audio>
+
 World Percussion
 ----------------
 
@@ -330,19 +369,36 @@ most expressive percussion instruments ever created. A single tabla
 player can produce an astonishing range of tones by varying finger
 placement, pressure, and striking technique.
 
-**6 sounds** -- covering the primary tabla strokes (na, tin, tun, ge,
-ke, and ti-ra-ki-ta combinations).
+**7 sounds** -- covering the primary tabla strokes (na, tin, tun, ge,
+dha, ke, tit) plus a bayan pitch bend sound (TABLA_GE_BEND) that
+models the technique of pressing the palm into the bayan head to bend
+the pitch upward.
 
 **7 patterns:** teental (16 beats, the most common taal), jhaptaal
 (10 beats), rupak (7 beats), dadra (6 beats), keherwa (8 beats, folk
 and light classical), tabla solo, and tiri kita (fast ornamental
 pattern).
 
+**5 fills:** tihai (3x crescendo landing on sam), chakkardar (32nd
+triplet cascade into slam), tiri kita (rapid 16th-note dayan burst),
+bayan (deep bass bends showcase), tabla call (dayan/bayan call-and-response).
+
+.. code-block:: python
+
+   score.drums("teental", repeats=4, fill="tihai")
+   score.drums("keherwa", repeats=4, fill="chakkardar")
+
 .. code-block:: python
 
    score = Score("4/4", bpm=80)
    score.drums("teental", repeats=4)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/tabla_teental.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/tabla_keherwa.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 1.5em"><source src="../_static/audio/tabla_chakradar.wav" type="audio/wav"></audio>
+
 Dhol
 ~~~~
 
@@ -360,6 +416,10 @@ energetic, and physically impossible to sit still to.
    score = Score("4/4", bpm=160)
    score.drums("bhangra", repeats=4)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/dhol.wav" type="audio/wav"></audio>
+
 Dholak
 ~~~~~~
 
@@ -377,6 +437,10 @@ music) and dholak folk (a general folk groove).
    score = Score("4/4", bpm=120)
    score.drums("qawwali", repeats=4)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/dholak.wav" type="audio/wav"></audio>
+
 Mridangam
 ~~~~~~~~~
 
@@ -395,6 +459,10 @@ and mridangam korvai (a rhythmic cadence pattern).
    score = Score("4/4", bpm=90)
    score.drums("adi talam", repeats=4)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/mridangam.wav" type="audio/wav"></audio>
+
 Djembe
 ~~~~~~
 
@@ -405,14 +473,23 @@ central to the drum ensemble traditions of Mali, Guinea, and Senegal.
 **3 sounds** -- bass (open center strike), tone (edge strike), and
 slap (sharp edge strike).
 
-**3 patterns:** djembe (a basic accompanying rhythm), kuku (a
-traditional rhythm from Guinea associated with fishing), and soli (a
-solo/celebration rhythm).
+**8 patterns:** djembe (basic accompanying rhythm), kuku (Guinean harvest
+dance), soli (powerful Mandinka rhythm), dununba (heavy bass-driven),
+tiriba (joyful Susu rhythm), yankadi (gentle greeting/welcome), djansa
+(fast Malinke dance), mendiani (women's celebratory dance).
+
+**3 fills:** djembe call (bass-tone-slap conversation building to climax),
+djembe roll (rapid slaps accelerating into bass), djembe break (syncopated
+West African-style break).
 
 .. code-block:: python
 
    score = Score("4/4", bpm=120)
-   score.drums("djembe", repeats=4)
+   score.drums("djembe", repeats=8, fill="djembe call", fill_every=4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/djembe.wav" type="audio/wav"></audio>
 
 Metal Kit
 ~~~~~~~~~
@@ -428,10 +505,97 @@ metal blast (blast beat with china cymbal accents), metal groove (a
 half-time groove with double kick fills), and metal gallop (the
 classic triplet-feel gallop rhythm).
 
+**4 fills:** metal (double kick 16ths with descending toms), metal triplet
+(double kick triplets with snare accents), metal blast (alternating
+snare/kick 32nds into half-time crash), metal cascade (descending snare
+roll → kick roll → alternating → crash ending).
+
 .. code-block:: python
 
    score = Score("4/4", bpm=200)
-   score.drums("metal blast", repeats=4)
+   score.drums("metal blast", repeats=8, fill="metal cascade", fill_every=4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/metal_blast.wav" type="audio/wav"></audio>
+
+Cajón
+~~~~~
+
+The cajón is a box-shaped percussion instrument from Peru, now
+ubiquitous in acoustic and unplugged settings worldwide. Players sit
+on the box and strike the front face with their hands.
+
+**3 sounds** -- bass (deep center thump), slap (sharp, snare-like edge
+hit with wire buzz), and tap (light finger tap).
+
+**3 patterns:** cajon (basic groove), cajon rumba (flamenco-style rumba),
+and cajon folk (folk/acoustic pattern).
+
+**3 fills:** cajon flam (slaps accelerating into bass hits), cajon rumble
+(fast taps building to slap accents), cajon breakdown (syncopated
+bass-slap groove).
+
+.. code-block:: python
+
+   score = Score("4/4", bpm=100)
+   score.drums("cajon", repeats=8, fill="cajon flam", fill_every=4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/cajon.wav" type="audio/wav"></audio>
+
+Marching Percussion
+~~~~~~~~~~~~~~~~~~~
+
+A full drumline — snare, quads (tenors), and pitched bass drums.
+Every sound is synthesized: kevlar snare heads, aluminum shell ting
+on the quads, felt-beater thwack on the basses.
+
+**Snare** -- 3 sounds: MARCH_SNARE (tight kevlar tap), MARCH_RIMSHOT
+(woody-metallic crack), MARCH_CLICK (stick click for count-offs).
+
+**Quads** -- 5 sounds: QUAD_1 through QUAD_4 (high to low pitched
+tenors) plus QUAD_SPOCK (rim click on the shell).
+
+**Bass drums** -- 5 pitched drums: BASS_1 (highest/smallest) through
+BASS_5 (lowest/biggest), each with a prominent felt-beater thwack.
+
+**6 patterns:** march (basic 4/4), cadence (8-beat street beat),
+march paradiddle, march roll (buzz crescendo), quad sweep (run across
+all 4 drums), quad groove, bass split (cascading across the line),
+bass unison (all 5 hit together), drumline (snare + quads + bass).
+
+**Rudiment methods:** ``Part.flam()``, ``Part.diddle()``, and
+``Part.cheese()`` for marching rudiments on any drum sound.
+
+**Ensemble rendering:** ``ensemble=N`` on any Part duplicates the
+voice with per-player timing tendencies and micro pitch drift.
+``ensemble=8`` for a snare line, ``ensemble=20`` for a massive section.
+
+.. code-block:: python
+
+   # Full drumline with ensemble
+   snares = score.part("snares", synth="sine", volume=0.9,
+                       reverb=0.2, ensemble=8)
+   quads = score.part("quads", synth="sine", volume=0.5,
+                      reverb=0.2, ensemble=4)
+   basses = score.part("basses", synth="sine", volume=0.55,
+                       reverb=0.2, ensemble=5)
+
+   snares.flam(DrumSound.MARCH_SNARE, Duration.QUARTER, velocity=120)
+   snares.diddle(DrumSound.MARCH_SNARE, Duration.EIGHTH, velocity=60)
+
+   # Or use patterns
+   score.drums("drumline", repeats=4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/march_snare.wav" type="audio/wav"></audio>
+
+**Sympathetic resonance:** The marching snare builds up snare wire
+buzz as hits accumulate, and the buzz decays during rests — just like
+a real drum.
 
 MIDI Export
 -----------

docs/guide/effects.rst

@@ -841,9 +841,11 @@ processes each section independently:
    lead.arpeggio("Gm", bars=4, pattern="updown", octaves=2)
 
 Any parameter can be automated: ``lowpass``, ``lowpass_q``, ``highpass``,
-``reverb``, ``reverb_decay``, ``delay``, ``delay_time``, ``delay_feedback``,
-``distortion``, ``distortion_drive``, ``chorus``, ``phaser``, ``phaser_rate``,
-``saturation``, ``tremolo_depth``, ``tremolo_rate``, ``volume``.
+``reverb``, ``reverb_decay``, ``reverb_type``, ``delay``, ``delay_time``,
+``delay_feedback``, ``distortion``, ``distortion_drive``, ``chorus``,
+``phaser``, ``phaser_rate``, ``saturation``, ``tremolo_depth``,
+``tremolo_rate``, ``cabinet``, ``cabinet_brightness``, ``analog_drift``,
+``volume``.
 
 LFO Automation
 --------------

docs/guide/playback.rst

@@ -44,6 +44,22 @@ Optional parameters for synth, envelope, and temperament:
    play(Tone.from_string("C4"), synth=Synth.SAW, envelope=Envelope.PLUCK, t=1_000)
    play(Tone.from_string("C4"), temperament="pythagorean", t=1_000)
 
+Synth-specific parameters are passed through as keyword arguments:
+
+.. code-block:: python
+
+   # Mellotron with flute tape
+   play(Tone.from_string("C4"), synth=Synth.MELLOTRON, tape="choir", t=2_000)
+
+   # Hard sync with custom slave ratio
+   play(Tone.from_string("C4"), synth=Synth.HARD_SYNC, slave_ratio=2.5)
+
+   # Wavefolding with 4 folds
+   play(Tone.from_string("C4"), synth=Synth.WAVEFOLD, folds=4.0)
+
+   # Drift oscillator with square shape
+   play(Tone.from_string("C4"), synth=Synth.DRIFT, shape="square")
+
 play_score() -- Full Arrangements
 ---------------------------------
 
@@ -66,6 +82,21 @@ the mix louder and punchier:
        chords.add(Chord.from_symbol(sym), Duration.WHOLE)
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/playback_basic.wav" type="audio/wav"></audio>
+
+The render pipeline respects the Score's ``temperament`` and
+``reference_pitch`` settings, so Baroque or microtonal scores play back
+at the correct tuning:
+
+.. code-block:: python
+
+   score = Score("4/4", bpm=80, temperament="meantone", reference_pitch=415.0)
+
+Press **Ctrl+C** at any time during playback to stop — PyTheory catches
+``KeyboardInterrupt`` and stops audio cleanly.
+
 See :doc:`sequencing` for how to build scores and parts.
 
 render_score() -- Headless Rendering
@@ -153,7 +184,7 @@ Play a drum pattern through the speakers:
    play_pattern(Pattern.preset("rock"), repeats=4, bpm=120)
    play_pattern(Pattern.preset("bossa nova"), repeats=4, bpm=140)
 
-See :doc:`drums` for the full list of 58 presets and 21 fills.
+See :doc:`drums` for the full list of 80+ presets and 21 fills.
 
 play_progression() -- Quick Chord Playback
 ------------------------------------------

docs/guide/quickstart.rst

@@ -143,48 +143,34 @@ chords, melody, bass, each with their own synth and effects:
 
 .. code-block:: python
 
-   from pytheory import Score, Pattern, Key, Duration, Chord
+   from pytheory import Score, Key, Duration
    from pytheory.play import play_score
 
-   score = Score("4/4", bpm=140)
-   score.drums("bossa nova", repeats=4)
+   score = Score("4/4", bpm=120)
+   score.drums("rock", repeats=8, fill="rock", fill_every=4)
 
-   chords = score.part(
-       "chords",
-       synth="fm",
-       envelope="pad",
-       reverb=0.4,
-   )
-   lead = score.part(
-       "lead",
-       synth="saw",
-       envelope="pluck",
-       delay=0.3,
-       lowpass=3000,
-       humanize=0.2,
-   )
-   bass = score.part(
-       "bass",
-       synth="sine",
-       lowpass=500,
-   )
+   piano = score.part("piano", instrument="piano", reverb=0.3)
+   lead = score.part("lead", synth="saw", envelope="pluck",
+                     delay=0.2, reverb=0.2, lowpass=4000)
+   bass = score.part("bass", synth="triangle", lowpass=900)
 
-   key = Key("A", "minor")
-   for chord in key.progression("i", "iv", "V", "i"):
-       chords.add(chord, Duration.WHOLE)
-       chords.add(chord, Duration.WHOLE)
+   for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
+       piano.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)
+   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)
 
-   for n in ["A2", "E2", "A2", "C3"] * 4:
-       bass.add(n, Duration.QUARTER)
+   for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
+       bass.add(n, Duration.HALF)
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/quickstart.wav" type="audio/wav"></audio>
+
 Export to Your DAW
 ------------------
 

docs/guide/sequencing.rst

@@ -47,6 +47,18 @@ A ``Duration`` represents a note length in beats (quarter note = 1 beat):
    >>> Duration.TRIPLET_QUARTER.value
    0.6666666666666666
 
+Duration supports arithmetic — multiply, divide, and add to create
+compound durations:
+
+.. code-block:: pycon
+
+   >>> Duration.WHOLE * 2
+   8.0
+   >>> Duration.HALF + Duration.QUARTER
+   3.0
+   >>> Duration.WHOLE / 2
+   2.0
+
 Time Signatures
 ---------------
 
@@ -149,6 +161,10 @@ Chords work just like tones — pass any ``Chord`` object:
    for chord in chords:
        score.add(chord, Duration.WHOLE)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/chords_basic.wav" type="audio/wav"></audio>
+
 .. code-block:: pycon
 
    >>> score.measures
@@ -232,6 +248,31 @@ Chords and Tone objects work the same way:
    for note in ["A2", "C3", "E3", "A2", "D2", "F2", "A2", "D2"]:
        bass.add(note, Duration.QUARTER)
 
+Polyphonic Hold
+---------------
+
+``Part.hold()`` adds a note without advancing the beat position —
+the next note starts at the *same* time. This enables polyphonic
+overlap on a single part: piano sustain, sitar drone under melody,
+guitar strum texture.
+
+.. code-block:: python
+
+   piano = score.part("piano", instrument="piano", reverb=0.3)
+
+   # Hold a C major chord for 8 beats
+   piano.hold("C3", Duration.WHOLE * 2, velocity=60)
+   piano.hold("E3", Duration.WHOLE * 2, velocity=55)
+   piano.hold("G3", Duration.WHOLE * 2, velocity=55)
+
+   # Melody plays simultaneously on top
+   for n in ["E4", "G4", "C5", "G4", "E4", "D4", "C4", "E4"]:
+       piano.add(n, Duration.QUARTER, velocity=80)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/piano_hold.wav" type="audio/wav"></audio>
+
 Arpeggiator
 ------------
 
@@ -280,6 +321,10 @@ Chain arpeggios through a progression:
    for sym in ["Cm", "Fm", "Abm", "Gm"]:
        lead.arpeggio(sym, bars=2, pattern="updown", octaves=2)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/arpeggio.wav" type="audio/wav"></audio>
+
 Combined with legato, glide, distortion, and a resonant lowpass, this
 produces the classic acid/trance arpeggiator sound.
 
@@ -310,12 +355,18 @@ portamento (pitch slides between notes):
    acid = score.part(
        "acid",
        synth="saw",
-       envelope="pad",
        legato=True,
        glide=0.04,
+       lowpass=3000,
+       lowpass_q=6.0,
+       distortion=0.3,
    )
    acid.add("C2", 0.25).add("C3", 0.25).add("G2", 0.25).add("C2", 0.25)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/legato_glide.wav" type="audio/wav"></audio>
+
 - ``legato``: If True, no envelope retrigger between notes (default False).
 - ``glide``: Portamento time in seconds (default 0, instant).
   0.03--0.05 = quick 303 slide, 0.1--0.2 = slow glide.
@@ -323,63 +374,51 @@ portamento (pitch slides between notes):
 Complete Example
 ----------------
 
-A full multi-part arrangement built from scratch — bossa nova with FM
-rhodes, triangle lead, and filtered bass:
+A full multi-part arrangement — rock beat with piano chords, saw
+lead, and filtered bass:
 
 .. code-block:: python
 
-   from pytheory import Score, Pattern, Key, Duration, Chord
+   from pytheory import Score, Key, Duration, Chord
    from pytheory.play import play_score
 
-   score = Score("4/4", bpm=140)
-   score.drums("bossa nova", repeats=4)
+   score = Score("4/4", bpm=120)
+   score.drums("rock", repeats=8, fill="rock", fill_every=4)
 
-   # FM rhodes with reverb
-   rhodes = score.part(
-       "rhodes",
-       synth="fm",
-       envelope="piano",
-       volume=0.3,
-       reverb=0.4,
-       reverb_decay=1.8,
-   )
+   # Piano chords with reverb
+   piano = score.part("piano", instrument="piano", volume=0.4, reverb=0.3)
 
-   # Triangle lead with delay
+   # Saw lead with delay
    lead = score.part(
-       "lead",
-       synth="triangle",
-       envelope="pluck",
-       volume=0.45,
-       delay=0.25,
-       delay_time=0.32,
-       delay_feedback=0.35,
-       reverb=0.2,
+       "lead", synth="saw", envelope="pluck", volume=0.4,
+       delay=0.2, delay_time=0.33, reverb=0.2, lowpass=3000,
    )
 
    # Filtered bass
-   bass = score.part(
-       "bass",
-       synth="sine",
-       envelope="pluck",
-       volume=0.45,
-       lowpass=600,
-   )
+   bass = score.part("bass", synth="triangle", envelope="pluck",
+                     volume=0.45, lowpass=1200)
 
-   for sym in ["Am", "Am", "Dm", "Dm", "E7", "E7", "Am", "Am"]:
-       rhodes.add(Chord.from_symbol(sym), Duration.WHOLE)
+   for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
+       piano.add(chord, Duration.WHOLE)
 
-   for n, d in [
-       ("E5", 0.67), ("D5", 0.33), ("C5", 0.67), ("B4", 0.33),
-       ("A4", 1), ("C5", 0.67), ("E5", 0.33), ("D5", 0.67), ("C5", 0.33),
-       ("A4", 1),
-   ]:
-       lead.add(n, d)
+   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 ["A2", "E2", "A2", "C3", "D2", "A2", "D2", "F2"]:
-       bass.add(n, Duration.QUARTER)
+   for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
+       bass.add(n, Duration.HALF)
 
    play_score(score)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/complete_rock.wav" type="audio/wav"></audio>
+
 Velocity
 --------
 
@@ -399,6 +438,157 @@ The arpeggiator also accepts velocity:
 
    lead.arpeggio("Am", bars=2, pattern="up", velocity=80)
 
+Articulations
+-------------
+
+Articulations change *how* a note is played — its attack, duration, and
+weight. A staccato note is short and bouncy. A marcato note hits hard.
+A legato note melts into the next one. This is the difference between
+a melody that sounds like a MIDI file and one that sounds like a
+musician played it.
+
+Pass ``articulation=`` to ``Part.add()``:
+
+.. code-block:: python
+
+   piano.add("C4", Duration.QUARTER, articulation="staccato")   # short, bouncy
+   piano.add("D4", Duration.QUARTER, articulation="legato")     # smooth, overlaps
+   piano.add("E4", Duration.QUARTER, articulation="marcato")    # heavy accent
+   piano.add("F4", Duration.QUARTER, articulation="tenuto")     # held, soft attack
+   piano.add("G4", Duration.QUARTER, articulation="accent")     # louder
+   piano.add("C5", Duration.HALF, articulation="fermata")       # held longer
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/articulations.wav" type="audio/wav"></audio>
+
+What each articulation does:
+
+- **staccato** — plays ~40% of the note duration with a quick fade-out. Short and detached.
+- **legato** — extends ~15% into the next note. Smooth and connected.
+- **marcato** — 25% velocity boost + sharper attack. Heavy and accented.
+- **tenuto** — full duration with a softer attack ramp. Held and deliberate.
+- **accent** — 20% velocity boost, no duration change.
+- **fermata** — stretches the note 50% longer.
+
+Articulations work on ``Part.hold()`` and ``Part.hit()`` too.
+
+Dynamic Curves
+--------------
+
+Real music breathes — phrases get louder, get quieter, swell and
+recede. Dynamic curves let you shape the velocity across a sequence
+of notes instead of setting each one manually.
+
+.. code-block:: python
+
+   # Crescendo: quiet to loud
+   piano.crescendo(["C4","D4","E4","F4","G4","A4","B4","C5"],
+                   Duration.QUARTER, start_vel=30, end_vel=110)
+
+   # Decrescendo: loud to quiet
+   piano.decrescendo(["C5","B4","A4","G4","F4","E4","D4","C4"],
+                     Duration.QUARTER, start_vel=110, end_vel=30)
+
+   # Swell: up then back down (orchestral < > shape)
+   strings.swell(["C4","D4","E4","F4","G4","F4","E4","D4"],
+                 Duration.QUARTER, low_vel=35, peak_vel=110)
+
+   # Custom curve: explicit velocity per note
+   piano.dynamics(["C4","E4","G4","C5"], Duration.QUARTER,
+                  velocities=[50, 80, 110, 90])
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/dynamics.wav" type="audio/wav"></audio>
+
+Four methods:
+
+- **crescendo()** — linear velocity ramp from ``start_vel`` to ``end_vel``.
+- **decrescendo()** — same thing, but typically loud to quiet.
+- **swell()** — ramps up to the midpoint, then back down. The classic
+  orchestral crescendo-decrescendo.
+- **dynamics()** — the general form. Pass a ``(start, end)`` tuple for
+  a linear ramp, or a list of velocities for a custom curve.
+
+All four accept ``articulation=`` to combine dynamics with articulations:
+
+.. code-block:: python
+
+   # Staccato crescendo — bouncy notes getting louder
+   piano.crescendo(["C4","E4","G4","C5","E5","G5","C6","E6"],
+                   Duration.EIGHTH, start_vel=40, end_vel=110,
+                   articulation="staccato")
+
+Part.hit() — Manual Drum Placement
+-----------------------------------
+
+The pattern system is great for grooves, but sometimes you want to
+place individual drum hits with full control — articulations, effects,
+and all. ``Part.hit()`` puts a drum sound into a Part's note stream:
+
+.. code-block:: python
+
+   from pytheory import DrumSound
+
+   kit = score.part("kit", synth="sine", volume=0.7)
+
+   kit.hit(DrumSound.KICK, Duration.QUARTER, articulation="accent")
+   kit.hit(DrumSound.CLOSED_HAT, Duration.EIGHTH, velocity=60)
+   kit.hit(DrumSound.SNARE, Duration.EIGHTH, articulation="marcato")
+
+Because hits go through the normal Part renderer, they get humanize,
+effects, and articulations for free. Use this for custom beats that
+don't fit a preset pattern, or for one-shot accent hits layered on
+top of a pattern.
+
+Rudiments — Flam, Diddle, Cheese
+---------------------------------
+
+Marching percussion rudiments as methods on any Part:
+
+.. code-block:: python
+
+   from pytheory import DrumSound
+
+   p = score.part("snares", synth="sine", volume=0.9)
+
+   # Flam: grace note + main hit (gap controls tightness)
+   p.flam(DrumSound.MARCH_SNARE, Duration.QUARTER, velocity=120)
+
+   # Diddle: two equal strokes in one note duration
+   p.diddle(DrumSound.MARCH_SNARE, Duration.EIGHTH, velocity=60)
+
+   # Cheese: flam + diddle combined
+   p.cheese(DrumSound.MARCH_SNARE, Duration.QUARTER, velocity=120)
+
+Ensemble
+--------
+
+Any Part can be rendered as an ensemble — multiple players with
+per-player timing tendencies and micro pitch drift:
+
+.. code-block:: python
+
+   # 8-player snare line
+   snares = score.part("snares", synth="sine", volume=0.9, ensemble=8)
+
+   # 20-player string section
+   strings = score.part("strings", instrument="string_ensemble", ensemble=20)
+
+   # Single player (default)
+   solo = score.part("solo", instrument="violin")
+
+Each ensemble voice gets a consistent timing personality (some rush,
+some drag) plus small per-note wobble, and slightly different tuning.
+The result sounds like a real section — together but alive.
+
+Solo snare, then an 8-player section plays the same pattern:
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/ensemble.wav" type="audio/wav"></audio>
+
 Swing and Groove
 ----------------
 
@@ -478,6 +668,54 @@ integrate naturally with the rest of the automation system:
    pad.rest(Duration.WHOLE)
    pad.rest(Duration.WHOLE)
 
+Parameter Ramps
+---------------
+
+Fades only control volume. ``Part.ramp()`` smoothly sweeps *any*
+parameter from its current value to a target — filters, reverb,
+distortion, chorus, delay, anything ``.set()`` accepts. This is how
+you build filter sweeps, gradual effect sends, and EDM buildups.
+
+.. code-block:: python
+
+   lead = score.part("lead", synth="saw", lowpass=200, lowpass_q=3.0)
+
+   # Open the filter over 8 bars
+   lead.ramp(over=Duration.WHOLE * 8, lowpass=8000)
+
+   # Ramp multiple params at once
+   pad.ramp(over=Duration.WHOLE * 4, reverb=0.5, chorus=0.3)
+
+   # Close the filter with distortion fading in
+   lead.ramp(over=Duration.WHOLE * 4, lowpass=400, distortion=0.5)
+
+Four interpolation curves:
+
+- **linear** — constant rate of change (default).
+- **ease_in** — starts slow, accelerates. Good for buildups.
+- **ease_out** — starts fast, decelerates. Good for releases.
+- **ease_in_out** — slow at both ends. Smooth and natural.
+
+.. code-block:: python
+
+   # EDM buildup: slow start, accelerating filter sweep
+   lead.ramp(over=Duration.WHOLE * 8, curve="ease_in", lowpass=8000)
+
+   # Smooth reverb wash fading in and settling
+   pad.ramp(over=Duration.WHOLE * 4, curve="ease_in_out", reverb=0.6)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="../_static/audio/filter_ramp.wav" type="audio/wav"></audio>
+
+``ramp()`` generates automation points every quarter-beat by default.
+Set ``resolution=0.125`` for smoother curves (every 32nd note), or
+``resolution=1.0`` for lighter automation (every beat).
+
+Combine with ``lfo()`` for cyclic modulation and ``ramp()`` for
+one-shot sweeps — together they cover the full range of parameter
+automation.
+
 Humanize
 --------
 
@@ -667,8 +905,16 @@ A Score can use any tuning system and temperament:
    # Just intonation — pure intervals
    score = Score("4/4", bpm=90, temperament="just")
 
-Temperaments: ``"equal"`` (default), ``"pythagorean"``, ``"meantone"``,
-``"just"``.
+The Score constructor accepts these tuning parameters:
+
+- ``system``: Musical system name (default ``"western"``). Any system
+  from :doc:`systems` works — ``"indian"``, ``"shruti"``, ``"maqam"``,
+  ``"carnatic"``, etc. Note strings in ``Part.add()`` are parsed against
+  this system.
+- ``temperament``: Tuning temperament — ``"equal"`` (default),
+  ``"pythagorean"``, ``"meantone"``, ``"just"``.
+- ``reference_pitch``: Concert pitch in Hz (default 440.0). Use 415.0
+  for Baroque tuning, 432.0 for "Verdi tuning", etc.
 
 Custom equal temperaments via the ``TET()`` factory:
 

docs/guide/synths.rst

@@ -1,7 +1,7 @@
 Synthesizers
 ============
 
-PyTheory includes 30 built-in waveforms and 10 ADSR envelope presets.
+PyTheory includes 56 built-in waveforms and 10 ADSR envelope presets.
 Every sound is generated from scratch -- no samples or external audio
 files needed.
 
@@ -37,6 +37,10 @@ building block of all other waveforms (Fourier's theorem).
    tone = Tone.from_string("C4", system="western")
    play(tone, synth=Synth.SINE)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_sine.wav" type="audio/wav"></audio>
+
 Sawtooth
 ~~~~~~~~
 
@@ -50,6 +54,10 @@ Named for its ramp shape.
 
    play(tone, synth=Synth.SAW)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_saw.wav" type="audio/wav"></audio>
+
 Triangle
 ~~~~~~~~
 
@@ -63,6 +71,10 @@ described as "woody" or "hollow."
 
    play(tone, synth=Synth.TRIANGLE)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_triangle.wav" type="audio/wav"></audio>
+
 Square
 ~~~~~~
 
@@ -76,6 +88,10 @@ pulse wave with a 50% duty cycle.
 
    play(tone, synth=Synth.SQUARE)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_square.wav" type="audio/wav"></audio>
+
 Extended Waveforms
 ------------------
 
@@ -98,6 +114,10 @@ the classic NES-style buzzy tone.
 
    lead = score.part("lead", synth="pulse", envelope="pluck")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_pulse.wav" type="audio/wav"></audio>
+
 FM Synthesis
 ~~~~~~~~~~~~
 
@@ -109,18 +129,24 @@ the electric piano in every Whitney Houston ballad, the bass in every
 Depeche Mode track, the bells in a thousand TV jingles. If you heard
 pop music in the 80s, you heard FM synthesis.
 
-**Use for:** electric piano (rhodes), bells, metallic leads, jazz chords.
+**Use for:** bells, metallic leads, glassy pads, DX7-style sounds.
 
 .. code-block:: python
 
-   rhodes = score.part(
-       "rhodes",
+   bells = score.part(
+       "bells",
        synth="fm",
-       envelope="piano",
+       envelope="bell",
+       fm_ratio=3.0,
+       fm_index=5.0,
        volume=0.3,
        reverb=0.4,
    )
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_fm.wav" type="audio/wav"></audio>
+
 Noise
 -----
 
@@ -142,6 +168,10 @@ Useful as a texture layer, a percussion source, or a wind/ocean effect.
        lowpass=2000,
    )
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_noise.wav" type="audio/wav"></audio>
+
 Ensemble Waveforms
 ------------------
 
@@ -174,6 +204,10 @@ supersaw.
        reverb=0.5,
    )
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_supersaw.wav" type="audio/wav"></audio>
+
 PWM Slow
 ~~~~~~~~
 
@@ -195,6 +229,10 @@ from Boards of Canada to Drake? PWM with a slow LFO.
        reverb=0.4,
    )
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_pwm_slow.wav" type="audio/wav"></audio>
+
 PWM Fast
 ~~~~~~~~
 
@@ -207,6 +245,118 @@ produces a natural chorus/vibrato effect built into the waveform itself.
 
    lead = score.part("lead", synth="pwm_fast", envelope="pluck", volume=0.5)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_pwm_fast.wav" type="audio/wav"></audio>
+
+Analog Synthesis
+----------------
+
+These waveforms model the behavior of real analog hardware — the
+imperfections, interactions, and nonlinearities that make a room full
+of vintage synths sound so much more alive than a room full of VSTs.
+Each one is a different approach to the same question: how do you make
+a digital oscillator sound like it has a soul?
+
+Hard Sync
+~~~~~~~~~
+
+A "slave" oscillator is forced to restart its cycle every time a
+"master" oscillator completes one. The abrupt restart creates bright
+formant peaks that sweep as the slave ratio changes. This is THE sound
+of the Prophet-5, Moog Prodigy, and every screaming analog lead since
+1978.
+
+**Use for:** aggressive leads, formant sweeps, cutting solos.
+
+.. code-block:: python
+
+   lead = score.part("lead", synth="hard_sync", envelope="pluck")
+
+   # Higher slave ratio = more harmonics, brighter
+   from pytheory import play, Synth, Tone
+   play(Tone.from_string("C4"), synth=Synth.HARD_SYNC, slave_ratio=2.5)
+
+Ring Modulation
+~~~~~~~~~~~~~~~
+
+Two oscillators multiplied together, producing sum and difference
+frequencies. Unlike FM, ring mod outputs only sidebands — no carrier
+or modulator fundamental. The result is metallic, bell-like, and often
+inharmonic. Classic Dalek voice, Stockhausen, and every sci-fi
+soundtrack.
+
+**Use for:** metallic bells, alien textures, inharmonic percussion.
+
+.. code-block:: python
+
+   bells = score.part("bells", instrument="ring_mod_bell",
+                      reverb=0.5, reverb_type="cave")
+
+   # Non-integer ratios = more inharmonic
+   play(Tone.from_string("C4"), synth=Synth.RING_MOD, mod_ratio=2.1)
+
+Wavefolding
+~~~~~~~~~~~
+
+The heart of west coast synthesis (Buchla, Make Noise, Verbos). A sine
+wave is amplified past ±1.0, then "folded" — the overflow bounces back
+instead of clipping. Each fold adds new harmonic pairs. At low fold
+counts it's warm and round; crank it up and it gets buzzy, gnarly, and
+alive.
+
+This sounds completely different from subtractive synthesis — instead of
+*removing* harmonics with a filter, you're *generating* them by shaping
+the wave. Pairs beautifully with a lowpass filter after the fold.
+
+**Use for:** complex leads, evolving textures, west coast basslines.
+
+.. code-block:: python
+
+   # Warm, musical folding
+   warm = score.part("fold", instrument="wavefold_warm")
+
+   # Cranked and aggressive
+   gnarly = score.part("gnarly", instrument="wavefold_gnarly")
+
+   # Direct control over fold amount
+   play(Tone.from_string("C4"), synth=Synth.WAVEFOLD, folds=3.0)
+
+Drift Oscillator
+~~~~~~~~~~~~~~~~
+
+Real analog oscillators are never perfectly stable. Capacitor charging,
+thermal variations, and component tolerances make the pitch wander
+slightly. This is what makes a Minimoog sound "fat" and a VST sound
+"thin" — the constant micro-motion of imperfect hardware.
+
+The drift oscillator models slow pitch drift (< 1 Hz wander), fast
+jitter (per-cycle randomness), a soft analog noise floor, and slightly
+rounded waveform edges. It turns any basic shape into something that
+breathes.
+
+**Use for:** analog-style pads, warm basses, vintage leads, any voice
+that needs to feel "alive."
+
+.. code-block:: python
+
+   # Vintage Minimoog-style saw
+   pad = score.part("pad", instrument="drift_saw",
+                    reverb=0.35, reverb_type="taj_mahal")
+
+   # Hollow square with analog wobble
+   sq = score.part("sq", instrument="drift_square")
+
+   # Control the shape and instability directly
+   play(Tone.from_string("C4"), synth=Synth.DRIFT,
+        shape="triangle", drift_amount=0.25)
+
+Drift amount controls how unstable the oscillator is:
+
+- **0.05** = studio-grade (Sequential, Oberheim)
+- **0.15** = classic vintage (Minimoog, ARP) — the default
+- **0.30** = barely-holding-it-together (old SH-101)
+
 ADSR Envelopes
 --------------
 
@@ -375,6 +525,10 @@ at musical levels. Warm, round, unmistakably organ.
 
    organ = score.part("organ", synth="organ_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_organ.wav" type="audio/wav"></audio>
+
 String Ensemble
 ~~~~~~~~~~~~~~~
 
@@ -386,15 +540,19 @@ more "wooden" than a raw saw wave.
 
    violin = score.part("violin", synth="strings_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_strings.wav" type="audio/wav"></audio>
+
 Dedicated Instrument Synths
 --------------------------
 
 Beyond the classic and physical modeling waveforms, PyTheory includes
-17 dedicated instrument synths. Each one uses tailored synthesis
+36 dedicated instrument synths. Each one uses tailored synthesis
 techniques -- additive harmonics, formant shaping, body resonance
 modeling, and specialized envelopes -- to capture the character of a
 specific acoustic instrument. These are the waveforms that bring the
-total count to 30.
+total count to 56.
 
 Piano Synth
 ~~~~~~~~~~~
@@ -407,6 +565,126 @@ soundboard.
 
    piano = score.part("piano", synth="piano_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_piano.wav" type="audio/wav"></audio>
+
+Rhodes Electric Piano
+~~~~~~~~~~~~~~~~~~~~~
+
+The Fender Rhodes — a rubber-tipped hammer strikes a steel tine
+next to a tonebar, picked up by an electromagnetic pickup. Warm,
+bell-like, with a bright metallic attack that mellows into a
+singing sustain. The sound of jazz clubs, soul, and neo-soul.
+
+.. code-block:: python
+
+   rhodes = score.part("rhodes", synth="rhodes_synth")
+   # Or use the instrument preset (adds tremolo + chorus)
+   rhodes = score.part("rhodes", instrument="electric_piano")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_rhodes.wav" type="audio/wav"></audio>
+
+Wurlitzer Electric Piano
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Wurlitzer uses a vibrating steel reed (not a tine like Rhodes)
+picked up by an electrostatic pickup. More nasal, reedy, and biting
+— it barks and growls when played hard. Think Supertramp, Ray Charles.
+
+.. code-block:: python
+
+   wurli = score.part("wurli", synth="wurlitzer_synth")
+   wurli = score.part("wurli", instrument="wurlitzer")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_wurlitzer.wav" type="audio/wav"></audio>
+
+Mellotron
+~~~~~~~~~
+
+The original "sampler" — a 1960s keyboard where each key triggers a
+strip of magnetic tape with a pre-recorded instrument. The mechanical
+tape transport gives it a haunted, lo-fi quality that no digital
+emulation fully captures: pitch wobbles from uneven capstan speed,
+bandwidth limited to 300 Hz–6 kHz (like a worn cassette), soft tape
+saturation, and tapes that physically run out after 8 seconds.
+
+The Mellotron defined the sound of *Strawberry Fields Forever*,
+*Stairway to Heaven*, and every prog rock record from 1969–1977.
+
+Three tape banks are available via the ``tape`` parameter:
+
+- ``"strings"`` (default) — the iconic MkII string section
+- ``"flute"`` — breathy, haunting solo flute
+- ``"choir"`` — ghostly vocal pad
+
+**Use for:** prog rock, haunted textures, vintage orchestral color.
+
+.. code-block:: python
+
+   # Use instrument presets (includes reverb)
+   strings = score.part("strings", instrument="mellotron_strings")
+   flute = score.part("flute", instrument="mellotron_flute")
+   choir = score.part("choir", instrument="mellotron_choir")
+
+   # Or select the tape directly
+   from pytheory import play, Synth, Tone
+   play(Tone.from_string("C4"), synth=Synth.MELLOTRON, tape="choir", t=3000)
+
+Vibraphone Synth
+~~~~~~~~~~~~~~~~
+
+Struck aluminum bars with motor-driven tremolo discs. The spinning
+motor modulates the sound through the resonator tubes, creating the
+signature vibraphone shimmer. Inharmonic bar modes at 1x, 2.76x, 5.4x.
+
+.. code-block:: python
+
+   vib = score.part("vib", synth="vibraphone_synth")
+   vib = score.part("vib", instrument="vibraphone")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_vibraphone.wav" type="audio/wav"></audio>
+
+Pipe Organ Synth
+~~~~~~~~~~~~~~~~
+
+Multiple ranks of pipes — principal 8', octave 4', fifteenth 2'.
+Constant air pressure means no dynamics. Wind chiff at the attack.
+Best with cathedral reverb.
+
+.. code-block:: python
+
+   organ = score.part("organ", synth="pipe_organ_synth")
+   organ = score.part("organ", instrument="pipe_organ")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_pipe_organ.wav" type="audio/wav"></audio>
+
+Choir Synth
+~~~~~~~~~~~
+
+Voices singing vowels shaped by formant bandpass filters. The glottal
+source is filtered through vocal tract resonances — F1, F2, F3, F4 —
+which is what makes "ah" sound different from "oo". Use ``lyric=``
+to control the vowel. Best with ``ensemble=`` for a full section.
+
+.. code-block:: python
+
+   choir = score.part("choir", synth="choir_synth")
+   choir = score.part("choir", instrument="choir")  # ensemble=6 + cathedral reverb
+   choir.add("C4", Duration.WHOLE, lyric="ah")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_choir.wav" type="audio/wav"></audio>
+
 Bass Guitar Synth
 ~~~~~~~~~~~~~~~~~
 
@@ -416,6 +694,10 @@ Plucked string model with finger-damped harmonics and low-end warmth.
 
    bass = score.part("bass", synth="bass_guitar_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_bass_guitar.wav" type="audio/wav"></audio>
+
 Flute Synth
 ~~~~~~~~~~~~
 
@@ -426,6 +708,10 @@ overblowing behavior at higher velocities.
 
    flute = score.part("flute", synth="flute_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_flute.wav" type="audio/wav"></audio>
+
 Trumpet Synth
 ~~~~~~~~~~~~~
 
@@ -436,6 +722,10 @@ velocity, plus a characteristic brassy edge from shaped harmonics.
 
    trumpet = score.part("trumpet", synth="trumpet_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_trumpet.wav" type="audio/wav"></audio>
+
 Clarinet Synth
 ~~~~~~~~~~~~~~
 
@@ -446,6 +736,10 @@ characteristic hollow, woody tone.
 
    clarinet = score.part("clarinet", synth="clarinet_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_clarinet.wav" type="audio/wav"></audio>
+
 Oboe Synth
 ~~~~~~~~~~~
 
@@ -456,6 +750,10 @@ timbre.
 
    oboe = score.part("oboe", synth="oboe_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_oboe.wav" type="audio/wav"></audio>
+
 Marimba Synth
 ~~~~~~~~~~~~~
 
@@ -466,6 +764,10 @@ that emphasizes the fundamental.
 
    marimba = score.part("marimba", synth="marimba_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_marimba.wav" type="audio/wav"></audio>
+
 Harpsichord Synth
 ~~~~~~~~~~~~~~~~~
 
@@ -476,6 +778,10 @@ Plucked-string model with a bright, immediate attack and rapid decay
 
    harpsi = score.part("harpsi", synth="harpsichord_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_harpsichord.wav" type="audio/wav"></audio>
+
 Cello Synth
 ~~~~~~~~~~~
 
@@ -486,6 +792,10 @@ producing a rich, warm, sustained tone.
 
    cello = score.part("cello", synth="cello_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_cello.wav" type="audio/wav"></audio>
+
 Harp Synth
 ~~~~~~~~~~
 
@@ -496,6 +806,10 @@ modeling nylon strings on a resonant frame.
 
    harp = score.part("harp", synth="harp_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_harp.wav" type="audio/wav"></audio>
+
 Upright Bass Synth
 ~~~~~~~~~~~~~~~~~~
 
@@ -505,6 +819,10 @@ Pizzicato double bass with woody body resonance and a thumpy low end.
 
    bass = score.part("bass", synth="upright_bass_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_upright_bass.wav" type="audio/wav"></audio>
+
 Acoustic Guitar Synth
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -515,6 +833,10 @@ string decay.
 
    guitar = score.part("guitar", synth="acoustic_guitar_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_acoustic_guitar.wav" type="audio/wav"></audio>
+
 Electric Guitar Synth
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -525,6 +847,10 @@ than the acoustic, ready for effects processing.
 
    eguitar = score.part("eguitar", synth="electric_guitar_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_electric_guitar.wav" type="audio/wav"></audio>
+
 Sitar Synth
 ~~~~~~~~~~~~
 
@@ -535,6 +861,10 @@ bridge, producing a shimmering, metallic sustain.
 
    sitar = score.part("sitar", synth="sitar_synth")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_sitar.wav" type="audio/wav"></audio>
+
 Timpani Synth
 ~~~~~~~~~~~~~
 
@@ -547,6 +877,10 @@ Use ``Part.roll()`` for crescendo timpani rolls.
    timp = score.part("timp", synth="timpani_synth")
    timp.roll("C3", Duration.WHOLE, velocity_start=20, velocity_end=110)
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_timpani.wav" type="audio/wav"></audio>
+
 Saxophone Synth
 ~~~~~~~~~~~~~~~
 
@@ -558,6 +892,151 @@ mids, reed buzz, and brass body warmth. Four presets: ``saxophone``,
 
    sax = score.part("sax", instrument="tenor_sax")
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_saxophone.wav" type="audio/wav"></audio>
+
+Pedal Steel Synth
+~~~~~~~~~~~~~~~~~
+
+The Nashville crying sound — singing harmonics with slow vibrato
+and long sustain. Pairs naturally with spring reverb.
+
+.. code-block:: python
+
+   steel = score.part("steel", instrument="pedal_steel")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_pedal_steel.wav" type="audio/wav"></audio>
+
+Theremin Synth
+~~~~~~~~~~~~~~
+
+Pure sine with natural hand wobble — the eerie sci-fi sound.
+Best used with legato and glide for continuous pitch.
+
+.. code-block:: python
+
+   theremin = score.part("theremin", instrument="theremin")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_theremin.wav" type="audio/wav"></audio>
+
+Kalimba Synth
+~~~~~~~~~~~~~
+
+Metal tines on a wooden body. Bright, bell-like attack with
+inharmonic overtones (modes at 1x, 2.92x, 5.4x).
+
+.. code-block:: python
+
+   kalimba = score.part("kalimba", instrument="kalimba")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_kalimba.wav" type="audio/wav"></audio>
+
+Steel Drum Synth
+~~~~~~~~~~~~~~~~
+
+Hammered metal pan with bright, ringing, tropical character.
+Inharmonic partials at 2.0x, 3.01x, 4.1x, 5.3x.
+
+.. code-block:: python
+
+   pan = score.part("pan", instrument="steel_drum")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_steel_drum.wav" type="audio/wav"></audio>
+
+Accordion Synth
+~~~~~~~~~~~~~~~
+
+Musette-tuned doubled reeds — two slightly detuned reed sets
+create natural beating. Bellows pressure swell modulates amplitude.
+
+.. code-block:: python
+
+   acc = score.part("acc", instrument="accordion")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_accordion.wav" type="audio/wav"></audio>
+
+Didgeridoo Synth
+~~~~~~~~~~~~~~~~
+
+Deep cylindrical drone with shifting formant overtones. The
+overtone singing effect sweeps a resonant peak between 500-1500Hz.
+Best with cave reverb.
+
+.. code-block:: python
+
+   didg = score.part("didg", instrument="didgeridoo")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_didgeridoo.wav" type="audio/wav"></audio>
+
+Bagpipe Synth
+~~~~~~~~~~~~~
+
+Bright chanter reed with constant bag pressure. All harmonics
+peaked around 3-7 (the piercing brightness). No dynamics — always ff.
+
+.. code-block:: python
+
+   pipes = score.part("pipes", instrument="bagpipe")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_bagpipe.wav" type="audio/wav"></audio>
+
+Banjo Synth
+~~~~~~~~~~~
+
+Steel strings on a drum-head membrane body. The membrane gives
+nasal, ringy resonance with faster decay than guitar.
+
+.. code-block:: python
+
+   banjo = score.part("banjo", instrument="banjo")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_banjo.wav" type="audio/wav"></audio>
+
+Mandolin Synth
+~~~~~~~~~~~~~~
+
+Paired steel strings in 4 courses — natural chorus from the
+doubled unison strings. Bright, ringing, fast attack.
+
+.. code-block:: python
+
+   mando = score.part("mando", instrument="mandolin")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_mandolin.wav" type="audio/wav"></audio>
+
+Ukulele Synth
+~~~~~~~~~~~~~
+
+Nylon strings on a small body. Mid-heavy resonance (no deep bass),
+softer attack than guitar, shorter sustain.
+
+.. code-block:: python
+
+   uke = score.part("uke", instrument="ukulele")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_ukulele.wav" type="audio/wav"></audio>
+
 Granular Synth
 ~~~~~~~~~~~~~~
 
@@ -587,6 +1066,147 @@ Parameters (passed as synth kwargs):
 - ``source``: Base waveform — ``"saw"``, ``"sine"``, ``"triangle"``,
   ``"square"``, ``"noise"``.
 
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_granular.wav" type="audio/wav"></audio>
+
+Crotales
+~~~~~~~~
+
+Small tuned bronze discs (antique cymbals) struck with brass mallets.
+Bright, crystalline, bell-like tone with strong upper harmonics that
+rings for a long time. Nearly harmonic partials give crotales their
+penetrating brilliance — they cut through any orchestra.
+
+.. code-block:: python
+
+   crotales = score.part("crotales", synth="crotales_synth", envelope="none",
+                         reverb=0.3)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_crotales.wav" type="audio/wav"></audio>
+
+Tingsha
+~~~~~~~
+
+Two small Tibetan cymbals joined by a cord, clashed together. Both discs
+ring at slightly different frequencies, producing a bright ping with
+pronounced beating — the wavering interference between the two is the
+whole character of the sound.
+
+.. code-block:: python
+
+   tingsha = score.part("tingsha", synth="tingsha_synth", envelope="none",
+                        reverb=0.4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_tingsha.wav" type="audio/wav"></audio>
+
+Singing Bowl (Strike)
+~~~~~~~~~~~~~~~~~~~~~
+
+Tibetan/Himalayan singing bowl struck with a mallet. The impact excites
+inharmonic partials that ring and slowly beat against each other as
+near-degenerate mode pairs interfere. Higher modes fade quickly, leaving
+the fundamental shimmering for seconds.
+
+.. code-block:: python
+
+   bowl = score.part("bowl", synth="singing_bowl_strike_synth", envelope="none",
+                     reverb=0.4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_singing_bowl_strike.wav" type="audio/wav"></audio>
+
+Singing Bowl (Ring)
+~~~~~~~~~~~~~~~~~~~
+
+Rim-rubbed singing bowl — the mallet traces the rim, slowly building the
+fundamental into a sustained, pulsing tone. Upper harmonics shimmer in
+and out as the bowl resonates.
+
+.. code-block:: python
+
+   bowl = score.part("bowl", synth="singing_bowl_ring_synth", envelope="none",
+                     reverb=0.4)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/synth_singing_bowl_ring.wav" type="audio/wav"></audio>
+
+Rain Stick
+~~~~~~~~~~
+
+Cascading pebbles through a cactus tube with internal pins. Two variants:
+steep angle (fast cascade) and shallow angle (slow trickle).
+
+.. code-block:: python
+
+   p.hit(DrumSound.RAINSTICK, Duration.WHOLE * 3)       # steep — fast cascade
+   p.hit(DrumSound.RAINSTICK_SLOW, Duration.WHOLE * 4)  # shallow — gentle trickle
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/rainstick.wav" type="audio/wav"></audio>
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/rainstick_slow.wav" type="audio/wav"></audio>
+
+Ocean Drum
+~~~~~~~~~~
+
+Steel beads rolling inside a frame drum — tilting produces a smooth surf wash.
+
+.. code-block:: python
+
+   p.hit(DrumSound.OCEAN_DRUM, Duration.WHOLE * 3)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/ocean_drum.wav" type="audio/wav"></audio>
+
+Cabasa
+~~~~~~
+
+Metal bead chain scraped against a textured cylinder — brighter and
+more metallic than a shaker.
+
+.. code-block:: python
+
+   p.hit(DrumSound.CABASA, Duration.EIGHTH)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/cabasa.wav" type="audio/wav"></audio>
+
+Wind Chimes
+~~~~~~~~~~~
+
+Suspended metal tubes struck by hand or breeze. Each tube rings at
+its own pitch with slight time offsets.
+
+.. code-block:: python
+
+   p.hit(DrumSound.WIND_CHIMES, Duration.WHOLE * 3)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/wind_chimes.wav" type="audio/wav"></audio>
+
+Finger Cymbal
+~~~~~~~~~~~~~
+
+Single small cymbal tap (zill) — bright metallic ping.
+
+.. code-block:: python
+
+   p.hit(DrumSound.FINGER_CYMBAL, Duration.HALF)
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.3em 0 0.5em"><source src="../_static/audio/finger_cymbal.wav" type="audio/wav"></audio>
+
 Analog Oscillator Drift
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -614,7 +1234,7 @@ Instrument Presets
 ------------------
 
 Instead of choosing synth + envelope + effects manually, use an
-instrument preset — 40+ predefined combinations that approximate real
+instrument preset — 60+ predefined combinations that approximate real
 instruments:
 
 .. code-block:: python
@@ -627,20 +1247,34 @@ instruments:
 
 Available instruments:
 
-**Keys**: piano, electric_piano, organ, harpsichord, celesta, music_box
+**Keys**: piano, electric_piano, organ, harpsichord, celesta, music_box,
+accordion
 
 **Strings**: violin, viola, cello, contrabass, string_ensemble
 
-**Woodwinds**: flute, clarinet, oboe, bassoon
+**Woodwinds**: flute, clarinet, oboe, bassoon, saxophone, alto_sax,
+tenor_sax, bari_sax
 
 **Brass**: trumpet, trombone, french_horn, tuba, brass_ensemble
 
-**Plucked**: acoustic_guitar, electric_guitar, distorted_guitar,
-bass_guitar, upright_bass, harp, sitar, koto
+**Plucked**: acoustic_guitar, electric_guitar, clean_guitar, crunch_guitar,
+distorted_guitar, orange_crunch, metal_guitar, bass_guitar, upright_bass,
+harp, sitar, koto, banjo, mandolin, mandola, ukulele
 
-**Synth**: synth_lead, synth_pad, synth_bass, acid_bass, 808_bass
+**World/Exotic**: pedal_steel, theremin, kalimba, steel_drum, didgeridoo,
+bagpipe, singing_bowl, singing_bowl_ring, tingsha
 
-**Percussion**: vibraphone, marimba, xylophone, glockenspiel, tubular_bells
+**Synth**: synth_lead, synth_pad, synth_bass, acid_bass, 808_bass,
+granular_pad, granular_texture, vocal, choir
+
+**Mellotron**: mellotron, mellotron_strings, mellotron_flute, mellotron_choir
+
+**Analog**: sync_lead, sync_lead_bright, ring_mod_bell, ring_mod_metallic,
+wavefold_warm, wavefold_gnarly, drift_saw, drift_square, analog_pad,
+analog_bass
+
+**Percussion**: vibraphone, marimba, xylophone, glockenspiel, tubular_bells,
+timpani, crotales
 
 Explicit kwargs override preset defaults:
 
@@ -681,3 +1315,11 @@ Some practical combos worth memorizing:
   long reverb and you're scoring a nature documentary.
 - ``saw`` + ``pluck`` = **funk stab.** Short, sharp, bright. The
   sound of Nile Rodgers' right hand.
+- ``hard_sync`` + ``pluck`` = **prophet lead.** Bright formant peak
+  that cuts through any mix. The opening riff of every 80s synth solo.
+- ``wavefold`` + ``organ`` = **west coast bass.** Warm, harmonically
+  rich sine-derivative that pairs beautifully with a lowpass after.
+- ``drift`` + ``pad`` = **analog pad.** A sawtooth that breathes and
+  wobbles like a real VCO. Add chorus and reverb for Juno vibes.
+- ``mellotron_synth`` + ``organ`` = **prog strings.** Haunted tape
+  machine. Add cathedral reverb and you're in 1972.