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,117 @@
 
 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

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

@@ -249,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
 -----
 
@@ -339,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
 ----------------
 
@@ -382,6 +393,12 @@ bayan (deep bass bends showcase), tabla call (dayan/bayan call-and-response).
    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
 ~~~~
 
@@ -399,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
 ~~~~~~
 
@@ -416,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
 ~~~~~~~~~
 
@@ -434,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
 ~~~~~~
 
@@ -458,6 +487,10 @@ West African-style break).
    score = Score("4/4", bpm=120)
    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
 ~~~~~~~~~
 
@@ -482,6 +515,10 @@ roll → kick roll → alternating → crash ending).
    score = Score("4/4", bpm=200)
    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
 ~~~~~
 
@@ -504,6 +541,10 @@ bass-slap groove).
    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
 ~~~~~~~~~~~~~~~~~~~
 
@@ -548,6 +589,10 @@ voice with per-player timing tendencies and micro pitch drift.
    # 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.

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,10 @@ 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:

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

@@ -161,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
@@ -244,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
 ------------
 
@@ -292,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.
 
@@ -322,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.
@@ -335,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
 --------
 
@@ -431,6 +458,10 @@ Pass ``articulation=`` to ``Part.add()``:
    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.
@@ -467,6 +498,10 @@ of notes instead of setting each one manually.
    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``.
@@ -548,6 +583,12 @@ 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
 ----------------
 
@@ -663,6 +704,10 @@ Four interpolation curves:
    # 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).

docs/guide/synths.rst

@@ -1,7 +1,7 @@
 Synthesizers
 ============
 
-PyTheory includes 41 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
-31 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 41.
+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,10 @@ 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
 ~~~~~~~~~~~~~~~~~
 
@@ -568,6 +906,10 @@ and long sustain. Pairs naturally with spring reverb.
 
    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
 ~~~~~~~~~~~~~~
 
@@ -578,6 +920,10 @@ Best used with legato and glide for continuous pitch.
 
    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
 ~~~~~~~~~~~~~
 
@@ -588,6 +934,10 @@ inharmonic overtones (modes at 1x, 2.92x, 5.4x).
 
    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
 ~~~~~~~~~~~~~~~~
 
@@ -598,6 +948,10 @@ Inharmonic partials at 2.0x, 3.01x, 4.1x, 5.3x.
 
    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
 ~~~~~~~~~~~~~~~
 
@@ -608,6 +962,10 @@ create natural beating. Bellows pressure swell modulates amplitude.
 
    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
 ~~~~~~~~~~~~~~~~
 
@@ -619,6 +977,10 @@ Best with cave reverb.
 
    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
 ~~~~~~~~~~~~~
 
@@ -629,6 +991,10 @@ peaked around 3-7 (the piercing brightness). No dynamics — always ff.
 
    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
 ~~~~~~~~~~~
 
@@ -639,6 +1005,10 @@ nasal, ringy resonance with faster decay than guitar.
 
    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
 ~~~~~~~~~~~~~~
 
@@ -649,6 +1019,10 @@ doubled unison strings. Bright, ringing, fast attack.
 
    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
 ~~~~~~~~~~~~~
 
@@ -659,6 +1033,10 @@ softer attack than guitar, shorter sustain.
 
    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
 ~~~~~~~~~~~~~~
 
@@ -688,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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -743,13 +1262,19 @@ distorted_guitar, orange_crunch, metal_guitar, bass_guitar, upright_bass,
 harp, sitar, koto, banjo, mandolin, mandola, ukulele
 
 **World/Exotic**: pedal_steel, theremin, kalimba, steel_drum, didgeridoo,
-bagpipe
+bagpipe, singing_bowl, singing_bowl_ring, tingsha
 
 **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
+timpani, crotales
 
 Explicit kwargs override preset defaults:
 
@@ -790,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.

docs/index.rst

@@ -46,23 +46,33 @@ it through your speakers, export MIDI, finish in your DAW:
 
 .. 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)
-   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)
 
-   for chord in Key("A", "minor").progression("i", "iv", "V", "i"):
-       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=4, 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 ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
+       bass.add(n, Duration.HALF)
 
    play_score(score)
-   score.save_midi("sketch.mid")
+
+.. raw:: html
+
+   <audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="_static/audio/quickstart.wav" type="audio/wav"></audio>
 
 Or hear a randomly generated track from the command line — different
 every time::

examples/songs.py

@@ -543,7 +543,7 @@ def dub_kingston():
                       volume=0.6, pan=0.0, lowpass=400, lowpass_q=1.5,
                       humanize=0.2)
     siren = score.part("siren", synth="pwm_slow", envelope="pad",
-                       volume=0.15, pan=0.5,
+                       volume=0.15, pan=0.5, ensemble=4,
                        reverb=0.7, reverb_decay=3.0, reverb_type="cathedral",
                        lowpass=1200, detune=10)
 
@@ -1124,14 +1124,14 @@ def cinematic_showcase():
         bells.rest(Duration.WHOLE)
 
     # String ensemble — lush wide pad
-    strings = score.part("strings", instrument="string_ensemble",
+    strings = score.part("strings", instrument="string_ensemble", ensemble=8,
                          reverb=0.4, reverb_type="hall")
     strings.rest(Duration.WHOLE)
     for sym in ["Am", "F", "C", "G", "Dm", "Am", "E"]:
         strings.add(Chord.from_symbol(sym), Duration.WHOLE)
 
     # Cello — deep foundation
-    cello = score.part("cello", instrument="cello",
+    cello = score.part("cello", instrument="cello", ensemble=3,
                        reverb=0.3, reverb_type="hall")
     cello.rest(Duration.WHOLE)
     for n in ["A2", "F2", "C3", "G2", "D3", "A2", "E2"]:
@@ -1629,7 +1629,7 @@ def epic_bhairav():
     timp.add(Tone("Pa", octave=2, system=shruti), Duration.HALF, velocity=115)
 
     # Choir — bar 3
-    choir = score.part("choir", synth="vocal_synth", envelope="pad",
+    choir = score.part("choir", synth="vocal_synth", envelope="pad", ensemble=6,
                         detune=8, spread=0.4, reverb=0.4, reverb_type=REV, volume=0.2)
     for _ in range(2):
         choir.rest(Duration.WHOLE)
@@ -1651,7 +1651,7 @@ def epic_bhairav():
         bansuri.add(tone, dur, velocity=vel)
 
     # Cello — bar 3
-    cello = score.part("cello", instrument="cello", volume=0.22, reverb=0.4, reverb_type=REV)
+    cello = score.part("cello", instrument="cello", volume=0.22, reverb=0.4, reverb_type=REV, ensemble=3)
     for _ in range(2):
         cello.rest(Duration.WHOLE)
     for name, dur, vel in [
@@ -1677,7 +1677,7 @@ def epic_bhairav():
 
     # Strings — bar 13
     strings = score.part("strings", instrument="string_ensemble", volume=0.18,
-                          reverb=0.4, reverb_type=REV)
+                          reverb=0.4, reverb_type=REV, ensemble=10)
     for _ in range(12):
         strings.rest(Duration.WHOLE)
     for name, dur, vel in [("Sa", 4.0, 58), ("Ma", 4.0, 62), ("Pa", 4.0, 68), ("Sa", 4.0, 72)]:
@@ -1887,7 +1887,7 @@ def ascent():
 
     # 3: SURFACING (5-8)
     cello = score.part("cello", instrument="cello", volume=0.22,
-                        reverb=0.4, reverb_type=REV)
+                        reverb=0.4, reverb_type=REV, ensemble=3)
     cello.rest(16.0)
     for note, dur, vel in [("E2",4.0,52),("G2",4.0,55),("B2",4.0,58),("E3",4.0,62)]:
         cello.add(note, dur, velocity=vel)
@@ -1943,7 +1943,7 @@ def ascent():
         theremin.add(note, dur, velocity=vel)
 
     strings = score.part("strings", instrument="string_ensemble", volume=0.15,
-                          reverb=0.45, reverb_type=REV)
+                          reverb=0.45, reverb_type=REV, ensemble=8)
     strings.rest(40.0)
     for sym, vel in [("Em",52),("C",55),("Am",58),("B",55),("Em",60),("C",62)]:
         strings.add(Chord.from_symbol(sym), 4.0, velocity=vel)
@@ -2218,7 +2218,7 @@ def pop_rock():
                        cabinet=1.0, cabinet_brightness=0.6,
                        reverb=0.2, reverb_type="plate", pan=0.2)
     strings = score.part("strings", instrument="string_ensemble", volume=0.12,
-                          reverb=0.35, reverb_type="hall")
+                          reverb=0.35, reverb_type="hall", ensemble=6)
 
     prog = ["G", "D", "Em", "C"]
 
@@ -2804,6 +2804,201 @@ def snare_cadence():
     play_song(score, "Snare Cadence — full drumline (8 snares, 4 quads, 5 basses)")
 
 
+def ensemble_showcase():
+    """Ensemble Showcase — acid bass, tabla solo, strings, snare line."""
+    score = Score("4/4", bpm=128)
+
+    # ── Drums: house kit ──
+    score.drums("house", repeats=24, fill="house", fill_every=8)
+    score.set_drum_effects(volume=0.4, reverb=0.1)
+
+    # ── 303 Acid Bass: detuned, spread, LFO filter, ensemble=3 ──
+    acid = score.part("acid", synth="saw", volume=0.55, ensemble=3,
+                      lowpass=400, lowpass_q=10.0, distortion=0.35,
+                      distortion_drive=4.0, legato=True, glide=0.03,
+                      detune=12, spread=0.4, sub_osc=0.15,
+                      sidechain=0.5, sidechain_release=0.08)
+
+    acid.lfo("lowpass", rate=0.5, min=400, max=5000, bars=16, shape="sine")
+    for _ in range(8):
+        for n in ["C2", "C3", "C2", "Eb2", "C2", "G2", "Bb2", "C2"]:
+            acid.add(n, Duration.EIGHTH, velocity=90)
+
+    acid.ramp(over=Duration.WHOLE * 8, curve="ease_in", lowpass=6000)
+    for _ in range(8):
+        for n in ["C2", "Eb3", "C3", "G2", "Bb2", "C3", "G2", "C2"]:
+            acid.add(n, Duration.EIGHTH, velocity=95)
+
+    acid.ramp(over=Duration.WHOLE * 8, curve="ease_out", lowpass=500)
+    for _ in range(8):
+        for n in ["C2", "C3", "C2", "Eb2", "C2", "G2", "Bb2", "C2"]:
+            acid.add(n, Duration.EIGHTH, velocity=88)
+
+    # ── Strings: 16-player ensemble pad ──
+    strings = score.part("strings", instrument="string_ensemble", volume=0.0,
+                         reverb=0.4, ensemble=16, detune=8, spread=0.5)
+
+    for _ in range(32):
+        strings.rest(Duration.QUARTER)
+    strings.ramp(over=Duration.WHOLE * 4, curve="ease_in", volume=0.18)
+    for ch in ["Cm", "Ab", "Eb", "Bb"] * 4:
+        strings.add(Chord.from_symbol(ch), Duration.WHOLE, velocity=55)
+    strings.ramp(over=Duration.WHOLE * 4, curve="ease_out", volume=0.0)
+    for ch in ["Cm", "Ab", "Eb", "Bb"]:
+        strings.add(Chord.from_symbol(ch), Duration.WHOLE, velocity=45)
+    for _ in range(16):
+        strings.rest(Duration.QUARTER)
+
+    # ── Tabla: ensemble=3, enters bar 9 ──
+    tabla = score.part("tabla", synth="sine", volume=0.0, reverb=0.15, ensemble=3)
+
+    for _ in range(32):
+        tabla.rest(Duration.QUARTER)
+    tabla.ramp(over=Duration.WHOLE * 2, volume=0.45)
+
+    # Keherwa groove — 8 bars
+    for _ in range(8):
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=95, articulation="accent")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=50)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=48)
+        tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=82)
+        tabla.hit(DrumSound.TABLA_TIN, Duration.EIGHTH, velocity=78)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=48)
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=88, articulation="accent")
+        tabla.hit(DrumSound.TABLA_GE, Duration.EIGHTH, velocity=72)
+
+    # Tabla solo — getting busier
+    tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=100, articulation="marcato")
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=45)
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=48)
+    tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=85)
+    tabla.hit(DrumSound.TABLA_TIN, Duration.EIGHTH, velocity=80)
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=45)
+    tabla.hit(DrumSound.TABLA_NA, Duration.SIXTEENTH, velocity=55)
+    tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=95, articulation="accent")
+    tabla.hit(DrumSound.TABLA_GE_BEND, Duration.EIGHTH, velocity=82)
+
+    tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=105, articulation="marcato")
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=48)
+    tabla.hit(DrumSound.TABLA_NA, Duration.SIXTEENTH, velocity=55)
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=45)
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=48)
+    tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=88)
+    tabla.hit(DrumSound.TABLA_DHA, Duration.SIXTEENTH, velocity=100)
+    tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=50)
+    tabla.hit(DrumSound.TABLA_GE_BEND, Duration.EIGHTH, velocity=85)
+    tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=108, articulation="accent")
+
+    # Tihai crescendo
+    for vel in [85, 90, 95, 100, 105, 110]:
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=vel, articulation="accent")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=int(vel * 0.55))
+        tabla.hit(DrumSound.TABLA_NA, Duration.SIXTEENTH, velocity=int(vel * 0.7))
+    tabla.hit(DrumSound.TABLA_DHA, Duration.QUARTER, velocity=125, articulation="fermata")
+    tabla.hit(DrumSound.TABLA_GE_BEND, Duration.QUARTER, velocity=110)
+
+    # Groove out
+    for _ in range(4):
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=88, articulation="accent")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=45)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=42)
+        tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=75)
+        tabla.hit(DrumSound.TABLA_TIN, Duration.EIGHTH, velocity=70)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=42)
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=80)
+        tabla.hit(DrumSound.TABLA_GE, Duration.EIGHTH, velocity=65)
+
+    # ── Snare line: 8-player ensemble, enters bar 17 ──
+    S = DrumSound.MARCH_SNARE
+    R = DrumSound.MARCH_RIMSHOT
+
+    snares = score.part("snares", synth="sine", volume=0.0, reverb=0.15, ensemble=8)
+
+    for _ in range(64):
+        snares.rest(Duration.QUARTER)
+    snares.ramp(over=Duration.WHOLE * 2, volume=0.7)
+
+    for _ in range(4):
+        snares.hit(R, Duration.SIXTEENTH, velocity=118)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(R, Duration.SIXTEENTH, velocity=115)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+        snares.hit(R, Duration.SIXTEENTH, velocity=118)
+        snares.hit(S, Duration.SIXTEENTH, velocity=35)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(R, Duration.SIXTEENTH, velocity=120)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+
+    # Buzz roll finale
+    for i in range(64):
+        snares.hit(S, 0.0625, velocity=min(20 + i * 1.5, 100))
+    snares.hit(R, Duration.EIGHTH, velocity=127)
+    snares.hit(R, Duration.EIGHTH, velocity=127)
+
+    snares.ramp(over=Duration.WHOLE * 2, curve="ease_out", volume=0.0)
+    for _ in range(2):
+        snares.hit(R, Duration.SIXTEENTH, velocity=110)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+        snares.hit(R, Duration.SIXTEENTH, velocity=108)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+        snares.hit(R, Duration.SIXTEENTH, velocity=105)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+        snares.hit(R, Duration.SIXTEENTH, velocity=100)
+        snares.hit(S, Duration.SIXTEENTH, velocity=30)
+        snares.hit(S, Duration.SIXTEENTH, velocity=28)
+        snares.hit(S, Duration.SIXTEENTH, velocity=32)
+
+    # ── Lead synth: 6-player ensemble, enters bar 5 ──
+    lead = score.part("lead", synth="saw", envelope="pluck", volume=0.0,
+                      lowpass=3500, detune=6, chorus=0.1, reverb=0.2,
+                      delay=0.15, delay_time=0.33, delay_feedback=0.25,
+                      ensemble=6)
+
+    for _ in range(16):
+        lead.rest(Duration.QUARTER)
+    lead.ramp(over=Duration.WHOLE * 2, volume=0.3)
+
+    for _ in range(2):
+        lead.add("Eb5", Duration.QUARTER, velocity=88)
+        lead.add("G5", Duration.QUARTER, velocity=92)
+        lead.add("Bb5", Duration.HALF, velocity=95, articulation="accent")
+        lead.add("Ab5", Duration.QUARTER, velocity=88)
+        lead.add("G5", Duration.QUARTER, velocity=85)
+        lead.add("Eb5", Duration.QUARTER, velocity=82)
+        lead.add("D5", Duration.QUARTER, velocity=80)
+
+    lead.swell(["Eb5", "G5", "Bb5", "C6", "Bb5", "G5", "Eb5", "D5"],
+               Duration.QUARTER, low_vel=75, peak_vel=105)
+    lead.decrescendo(["Eb5", "D5", "C5", "Bb4"], Duration.HALF,
+                     start_vel=90, end_vel=60)
+
+    for _ in range(16):
+        lead.rest(Duration.QUARTER)
+
+    lead.ramp(over=Duration.WHOLE * 2, volume=0.35)
+    lead.crescendo(["C5", "Eb5", "G5", "Bb5", "C6", "Eb6", "C6", "Bb5"],
+                   Duration.QUARTER, start_vel=80, end_vel=110)
+    lead.add("G5", Duration.HALF, velocity=105, bend=1, bend_type="smooth")
+    lead.add("Eb5", Duration.HALF, velocity=95)
+    lead.decrescendo(["C5", "Bb4", "G4", "Eb4"], Duration.WHOLE,
+                     start_vel=85, end_vel=40)
+
+    play_song(score, "Ensemble Showcase — acid bass, tabla solo, 16-player strings, 8-player snare line")
+
+
 SONGS = {
     "1": ("Bossa Nova in A minor", bossa_nova_girl),
     "2": ("Bebop in Bb major", bebop_in_bb),
@@ -2837,6 +3032,7 @@ SONGS = {
     "30": ("Sitar Drone (Bhairav, hold() polyphony)", sitar_drone),
     "31": ("Acid Tabla (303 + tabla, ramp, articulations)", acid_tabla),
     "32": ("Snare Cadence (marching snare, flams, diddles)", snare_cadence),
+    "33": ("Ensemble Showcase (acid+tabla+strings+snare line)", ensemble_showcase),
 }
 
 if __name__ == "__main__":
@@ -2850,7 +3046,7 @@ if __name__ == "__main__":
             print(f"    {key:>2}. {name}")
 
         print()
-        choice = input("  Pick a song (1-32, or 'all'): ").strip()
+        choice = input("  Pick a song (1-33, or 'all'): ").strip()
         print()
 
         if choice == "all":