v0.39.3: Audio samples in docs, numpy vectorization

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

CHANGELOG.md

@@ -2,6 +2,98 @@
 
 All notable changes to PyTheory are documented here.
 
+## 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

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/generate_audio.py

@@ -0,0 +1,573 @@
+"""Generate audio samples for documentation.
+
+Renders code examples from the docs as WAV files so they can be
+embedded as <audio> players on the website.
+
+Usage:
+    uv run python docs/generate_audio.py
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from pytheory import Score, Duration, Key, Chord, Fretboard, DrumSound
+from pytheory.play import render_score, SAMPLE_RATE
+
+import numpy
+import struct
+
+AUDIO_DIR = os.path.join(os.path.dirname(__file__), "_static", "audio")
+os.makedirs(AUDIO_DIR, exist_ok=True)
+
+
+def save_wav(buf, path):
+    """Save a float32 buffer as 16-bit stereo WAV."""
+    # Handle both mono (n,) and stereo (n, 2) buffers
+    if buf.ndim == 1:
+        channels = 1
+        n_frames = len(buf)
+    else:
+        channels = buf.shape[1]
+        n_frames = buf.shape[0]
+    peak = numpy.abs(buf).max()
+    if peak > 0:
+        buf = buf / peak * 0.9
+    samples = (buf * 32767).astype(numpy.int16)
+    byte_rate = SAMPLE_RATE * channels * 2
+    block_align = channels * 2
+    data_size = n_frames * channels * 2
+    with open(path, "wb") as f:
+        f.write(b"RIFF")
+        f.write(struct.pack("<I", 36 + data_size))
+        f.write(b"WAVE")
+        f.write(b"fmt ")
+        f.write(struct.pack("<IHHIIHH", 16, 1, channels, SAMPLE_RATE,
+                            byte_rate, block_align, 16))
+        f.write(b"data")
+        f.write(struct.pack("<I", data_size))
+        f.write(samples.tobytes())
+    label = "stereo" if channels == 2 else "mono"
+    print(f"  {os.path.basename(path)} ({n_frames/SAMPLE_RATE:.1f}s, {label})")
+
+
+def render(name, score):
+    """Render a score to WAV in the audio directory."""
+    buf = render_score(score)
+    save_wav(buf, os.path.join(AUDIO_DIR, f"{name}.wav"))
+
+
+# ── Piano hold (polyphonic overlap) ──────────────────────────────────────
+
+def gen_piano_hold():
+    score = Score("4/4", bpm=85)
+    piano = score.part("piano", instrument="piano", reverb=0.3)
+    piano.hold("C3", Duration.WHOLE * 2, velocity=60)
+    piano.hold("E3", Duration.WHOLE * 2, velocity=55)
+    piano.hold("G3", Duration.WHOLE * 2, velocity=55)
+    for n in ["E4", "G4", "C5", "G4", "E4", "D4", "C4", "E4"]:
+        piano.add(n, Duration.QUARTER, velocity=80)
+    render("piano_hold", score)
+
+
+# ── Articulations ────────────────────────────────────────────────────────
+
+def gen_articulations():
+    score = Score("4/4", bpm=90)
+    piano = score.part("piano", instrument="piano", reverb=0.25)
+    for n in ["C4", "E4", "G4", "C5"]:
+        piano.add(n, Duration.QUARTER, velocity=80)
+    for n in ["C4", "E4", "G4", "C5"]:
+        piano.add(n, Duration.QUARTER, velocity=80, articulation="staccato")
+    for n in ["C5", "G4", "E4", "C4"]:
+        piano.add(n, Duration.QUARTER, velocity=80, articulation="legato")
+    for n in ["C4", "E4", "G4", "C5"]:
+        piano.add(n, Duration.QUARTER, velocity=80, articulation="marcato")
+    render("articulations", score)
+
+
+# ── Dynamic curves ───────────────────────────────────────────────────────
+
+def gen_dynamics():
+    score = Score("4/4", bpm=90)
+    piano = score.part("piano", instrument="piano", reverb=0.3)
+    piano.crescendo(["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"],
+                    Duration.QUARTER, start_vel=30, end_vel=110)
+    piano.decrescendo(["C5", "B4", "A4", "G4", "F4", "E4", "D4", "C4"],
+                      Duration.QUARTER, start_vel=110, end_vel=30)
+    render("dynamics", score)
+
+
+# ── Filter ramp ──────────────────────────────────────────────────────────
+
+def gen_filter_ramp():
+    score = Score("4/4", bpm=130)
+    score.drums("house", repeats=8, fill="house", fill_every=8)
+    score.set_drum_effects(volume=0.4)
+    acid = score.part("acid", synth="saw", volume=0.6,
+                      lowpass=300, lowpass_q=8.0, distortion=0.3,
+                      legato=True, glide=0.03)
+    acid.ramp(over=Duration.WHOLE * 4, curve="ease_in", lowpass=5000)
+    for _ in range(4):
+        for n in ["C2", "C3", "C2", "Eb2", "C2", "G2", "Bb2", "C2"]:
+            acid.add(n, Duration.EIGHTH, velocity=90)
+    acid.ramp(over=Duration.WHOLE * 4, curve="ease_out", lowpass=300)
+    for _ in range(4):
+        for n in ["C2", "C3", "C2", "Eb2", "C2", "G2", "Bb2", "C2"]:
+            acid.add(n, Duration.EIGHTH, velocity=88)
+    render("filter_ramp", score)
+
+
+# ── Rock beat ────────────────────────────────────────────────────────────
+
+def gen_rock_beat():
+    score = Score("4/4", bpm=120)
+    score.drums("rock", repeats=4, fill="rock", fill_every=4)
+    render("rock_beat", score)
+
+
+def gen_bossa_nova_pattern():
+    score = Score("4/4", bpm=140)
+    score.drums("bossa nova", repeats=4)
+    render("bossa_nova_pattern", score)
+
+
+def gen_salsa_pattern():
+    score = Score("4/4", bpm=180)
+    score.drums("salsa", repeats=4)
+    render("salsa_pattern", score)
+
+
+def gen_afrobeat_pattern():
+    score = Score("4/4", bpm=110)
+    score.drums("afrobeat", repeats=8)
+    render("afrobeat_pattern", score)
+
+
+# ── Bossa nova ───────────────────────────────────────────────────────────
+
+def gen_bossa_nova():
+    score = Score("4/4", bpm=140)
+    score.drums("bossa nova", repeats=4)
+    rhodes = score.part("rhodes", synth="fm", envelope="piano", volume=0.3,
+                        reverb=0.4, reverb_decay=1.8)
+    for sym in ["Am", "Am", "Dm", "Dm", "E7", "E7", "Am", "Am"]:
+        rhodes.add(Chord.from_symbol(sym), Duration.WHOLE)
+    render("bossa_nova", score)
+
+
+# ── Djembe ───────────────────────────────────────────────────────────────
+
+def gen_djembe():
+    score = Score("4/4", bpm=110)
+    score.drums("tiriba", repeats=4, fill="djembe call", fill_every=4)
+    score.set_drum_effects(reverb=0.2)
+    render("djembe", score)
+
+
+# ── Tabla ────────────────────────────────────────────────────────────────
+
+def gen_tabla():
+    score = Score("4/4", bpm=80)
+    score.drums("teental", repeats=2)
+    score.drums("chakradar", repeats=1)
+    score.set_drum_effects(reverb=0.2)
+    render("tabla", score)
+
+
+# ── Marching snare ───────────────────────────────────────────────────────
+
+def gen_metal_blast():
+    score = Score("4/4", bpm=200)
+    score.drums("metal blast", repeats=8, fill="metal cascade", fill_every=4)
+    render("metal_blast", score)
+
+
+def gen_cajon():
+    score = Score("4/4", bpm=100)
+    score.drums("cajon", repeats=8, fill="cajon flam", fill_every=4)
+    render("cajon", score)
+
+
+def gen_tabla_teental():
+    score = Score("4/4", bpm=160)
+    score.drums("teental", repeats=4)
+    score.set_drum_effects(reverb=0.2)
+    render("tabla_teental", score)
+
+
+def gen_tabla_keherwa():
+    score = Score("4/4", bpm=180)
+    score.drums("keherwa", repeats=4, fill="chakkardar", fill_every=4)
+    score.set_drum_effects(reverb=0.2)
+    render("tabla_keherwa", score)
+
+
+def gen_tabla_chakradar():
+    score = Score("4/4", bpm=200)
+    score.drums("teental", repeats=2)
+    score.drums("chakradar", repeats=1)
+    score.set_drum_effects(reverb=0.2)
+    render("tabla_chakradar", score)
+
+
+def gen_dhol():
+    score = Score("4/4", bpm=160)
+    score.drums("bhangra", repeats=4)
+    render("dhol", score)
+
+
+def gen_dholak():
+    score = Score("4/4", bpm=120)
+    score.drums("qawwali", repeats=4)
+    render("dholak", score)
+
+
+def gen_mridangam():
+    score = Score("4/4", bpm=90)
+    score.drums("adi talam", repeats=4)
+    render("mridangam", score)
+
+
+def gen_march_snare():
+    score = Score("4/4", bpm=120)
+    p = score.part("snare", synth="sine", volume=0.8, reverb=0.15)
+    S = DrumSound.MARCH_SNARE
+    R = DrumSound.MARCH_RIMSHOT
+    C = DrumSound.MARCH_CLICK
+
+    for _ in range(4):
+        p.hit(C, Duration.QUARTER, velocity=95)
+
+    for _ in range(4):
+        p.hit(R, Duration.SIXTEENTH, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(R, Duration.SIXTEENTH, velocity=115)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(R, Duration.SIXTEENTH, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=35)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(R, Duration.SIXTEENTH, velocity=120)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+    render("march_snare", score)
+
+
+# ── Ensemble comparison ──────────────────────────────────────────────────
+
+def gen_ensemble():
+    score = Score("4/4", bpm=120)
+    S = DrumSound.MARCH_SNARE
+    R = DrumSound.MARCH_RIMSHOT
+
+    # Solo first
+    solo = score.part("solo", synth="sine", volume=0.7, reverb=0.15)
+    for _ in range(2):
+        solo.hit(R, Duration.SIXTEENTH, velocity=118)
+        solo.hit(S, Duration.SIXTEENTH, velocity=30)
+        solo.hit(S, Duration.SIXTEENTH, velocity=32)
+        solo.hit(S, Duration.SIXTEENTH, velocity=28)
+        solo.hit(R, Duration.SIXTEENTH, velocity=115)
+        solo.hit(S, Duration.SIXTEENTH, velocity=30)
+        solo.hit(S, Duration.SIXTEENTH, velocity=28)
+        solo.hit(S, Duration.SIXTEENTH, velocity=32)
+        solo.hit(R, Duration.SIXTEENTH, velocity=118)
+        solo.hit(S, Duration.SIXTEENTH, velocity=35)
+        solo.hit(S, Duration.SIXTEENTH, velocity=28)
+        solo.hit(S, Duration.SIXTEENTH, velocity=30)
+        solo.hit(R, Duration.SIXTEENTH, velocity=120)
+        solo.hit(S, Duration.SIXTEENTH, velocity=30)
+        solo.hit(S, Duration.SIXTEENTH, velocity=28)
+        solo.hit(S, Duration.SIXTEENTH, velocity=32)
+
+    # Then ensemble
+    line = score.part("line", synth="sine", volume=0.7, reverb=0.15, ensemble=8)
+    for _ in range(8):
+        line.rest(Duration.QUARTER)
+    for _ in range(4):
+        line.hit(R, Duration.SIXTEENTH, velocity=118)
+        line.hit(S, Duration.SIXTEENTH, velocity=30)
+        line.hit(S, Duration.SIXTEENTH, velocity=32)
+        line.hit(S, Duration.SIXTEENTH, velocity=28)
+        line.hit(R, Duration.SIXTEENTH, velocity=115)
+        line.hit(S, Duration.SIXTEENTH, velocity=30)
+        line.hit(S, Duration.SIXTEENTH, velocity=28)
+        line.hit(S, Duration.SIXTEENTH, velocity=32)
+        line.hit(R, Duration.SIXTEENTH, velocity=118)
+        line.hit(S, Duration.SIXTEENTH, velocity=35)
+        line.hit(S, Duration.SIXTEENTH, velocity=28)
+        line.hit(S, Duration.SIXTEENTH, velocity=30)
+        line.hit(R, Duration.SIXTEENTH, velocity=120)
+        line.hit(S, Duration.SIXTEENTH, velocity=30)
+        line.hit(S, Duration.SIXTEENTH, velocity=28)
+        line.hit(S, Duration.SIXTEENTH, velocity=32)
+    render("ensemble", score)
+
+
+# ── Guitar strum ─────────────────────────────────────────────────────────
+
+def gen_strum():
+    score = Score("4/4", bpm=100)
+    guitar = score.part("guitar", instrument="acoustic_guitar",
+                        fretboard=Fretboard.guitar())
+    for ch in ["G", "D", "Em", "C"] * 2:
+        guitar.strum(ch, duration=Duration.WHOLE, velocity=75)
+    render("strum", score)
+
+
+# ── Swell ────────────────────────────────────────────────────────────────
+
+def gen_swell():
+    score = Score("4/4", bpm=80)
+    strings = score.part("strings", instrument="string_ensemble",
+                         reverb=0.4, ensemble=12)
+    strings.swell(["C4", "D4", "E4", "F4", "G4", "F4", "E4", "D4",
+                   "C4", "D4", "E4", "F4", "G4", "A4", "G4", "E4"],
+                  Duration.QUARTER, low_vel=30, peak_vel=100)
+    render("swell", score)
+
+
+# ── Generate all ─────────────────────────────────────────────────────────
+
+# ── Cookbook: Acid House ───────────────────────────────────────────────────
+
+def gen_acid_house():
+    score = Score("4/4", bpm=132)
+    score.drums("house", repeats=8, fill="house", fill_every=8)
+    pad = score.part("pad", synth="supersaw", envelope="pad",
+                     reverb=0.4, chorus=0.3, sidechain=0.85)
+    acid = score.part("acid", synth="saw", envelope="pad",
+                      legato=True, glide=0.03, distortion=0.8,
+                      distortion_drive=8.0, lowpass=1000, lowpass_q=5.0)
+    acid.lfo("lowpass", rate=0.5, min=600, max=2500, bars=8)
+    for sym in ["Cm", "Fm", "Abm", "Gm"]:
+        pad.add(Chord.from_symbol(sym), Duration.WHOLE)
+        pad.add(Chord.from_symbol(sym), Duration.WHOLE)
+        acid.arpeggio(sym, bars=2, pattern="up", octaves=2)
+    render("acid_house", score)
+
+
+# ── Cookbook: Dub Reggae ──────────────────────────────────────────────────
+
+def gen_dub_reggae():
+    score = Score("4/4", bpm=72)
+    score.drums("dub", repeats=8)
+    melodica = score.part("melodica", synth="triangle", envelope="pluck",
+                          delay=0.5, delay_time=0.66, delay_feedback=0.55,
+                          reverb=0.4, reverb_type="cathedral")
+    bass = score.part("bass", synth="sine", lowpass=400, lowpass_q=1.5)
+    melodica.add("A4", 2).rest(6)
+    melodica.add("E5", 1.5).rest(6.5)
+    melodica.add("D5", 1).add("C5", 1).add("A4", 2).rest(4)
+    for _ in range(16):
+        bass.add("A1", Duration.HALF)
+    render("dub_reggae", score)
+
+
+# ── Cookbook: Jazz Ballad ─────────────────────────────────────────────────
+
+def gen_jazz_ballad():
+    score = Score("4/4", bpm=72, swing=0.5)
+    score.drums("jazz", repeats=8)
+    rhodes = score.part("rhodes", synth="fm", envelope="piano",
+                        reverb=0.4, reverb_type="plate", humanize=0.3)
+    lead = score.part("lead", synth="triangle", envelope="strings",
+                      delay=0.25, reverb=0.3, humanize=0.35)
+    key = Key("Bb", "major")
+    for chord in key.progression("I", "vi", "ii", "V") * 2:
+        rhodes.add(chord, Duration.WHOLE)
+    for n, d in [("D5", 1.5), ("F5", 0.5), ("Bb5", 2), (None, 4),
+                 ("A5", 1), ("G5", 1), ("F5", 2), (None, 4)]:
+        lead.rest(d) if n is None else lead.add(n, d)
+    render("jazz_ballad", score)
+
+
+# ── Quickstart example ───────────────────────────────────────────────────
+
+def gen_arpeggio():
+    score = Score("4/4", bpm=132)
+    score.drums("house", repeats=8)
+    score.set_drum_effects(volume=0.3)
+    lead = score.part("lead", synth="saw", envelope="pluck", volume=0.5,
+                      lowpass=5000, detune=8, chorus=0.15, reverb=0.25,
+                      delay=0.2, delay_time=0.33, delay_feedback=0.3)
+    for sym in ["Cm", "Fm", "Abm", "Gm"]:
+        lead.arpeggio(sym, bars=2, pattern="updown", octaves=2)
+    render("arpeggio", score)
+
+
+def gen_legato_glide():
+    score = Score("4/4", bpm=132)
+    score.drums("house", repeats=4)
+    score.set_drum_effects(volume=0.35)
+    acid = score.part("acid", synth="saw", volume=0.6,
+                      legato=True, glide=0.04,
+                      lowpass=3000, lowpass_q=6.0,
+                      distortion=0.3, distortion_drive=3.0)
+    acid.lfo("lowpass", rate=0.5, min=800, max=4000, bars=4)
+    for _ in range(4):
+        acid.add("C2", 0.25).add("C3", 0.25).add("G2", 0.25).add("C2", 0.25)
+        acid.add("C2", 0.25).add("Eb2", 0.25).add("G2", 0.25).add("Bb2", 0.25)
+    render("legato_glide", score)
+
+
+def gen_quickstart():
+    score = Score("4/4", bpm=140)
+    score.drums("bossa nova", repeats=4)
+    chords = score.part("chords", synth="sine", envelope="pad",
+                        reverb=0.4, volume=0.3)
+    lead = score.part("lead", synth="saw", envelope="pluck",
+                      lowpass=2000, lowpass_q=3.0, distortion=0.8,
+                      legato=True, glide=0.03, volume=0.4)
+    bass = score.part("bass", synth="sine", lowpass=500)
+    key = Key("A", "minor")
+    for chord in key.progression("i", "iv", "V", "i"):
+        chords.add(chord, Duration.WHOLE)
+        chords.add(chord, Duration.WHOLE)
+    lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)
+    lead.arpeggio("Dm", bars=2, pattern="updown", octaves=2)
+    lead.set(lowpass=5000, reverb=0.3)
+    lead.arpeggio("E7", bars=2, pattern="up", octaves=2)
+    lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)
+    for n in ["A2", "E2", "A2", "C3"] * 4:
+        bass.add(n, Duration.QUARTER)
+    render("quickstart", score)
+
+
+# ── Sequencing complete example (bossa nova) ─────────────────────────────
+
+def gen_chords_basic():
+    score = Score("4/4", bpm=120)
+    key = Key("C", "major")
+    chords = key.progression("I", "V", "vi", "IV")
+    for chord in chords:
+        score.add(chord, Duration.WHOLE)
+    render("chords_basic", score)
+
+
+def gen_complete_rock():
+    score = Score("4/4", bpm=120)
+    score.drums("rock", repeats=8, fill="rock", fill_every=4)
+    piano = score.part("piano", instrument="piano", volume=0.4, reverb=0.3)
+    lead = score.part("lead", synth="saw", envelope="pluck", volume=0.4,
+                      delay=0.2, delay_time=0.33, reverb=0.2, lowpass=3000)
+    bass = score.part("bass", synth="triangle", envelope="pluck", volume=0.45,
+                      lowpass=600)
+    for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
+        piano.add(chord, Duration.WHOLE)
+    lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
+    lead.add("G5", 1).add("E5", 1)
+    lead.add("D5", 0.5).add("B4", 0.5).add("A4", 1)
+    lead.add("G4", 2).rest(2)
+    lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
+    lead.add("G5", 1).add("A5", 1)
+    lead.add("G5", 0.5).add("E5", 0.5).add("D5", 1)
+    lead.add("B4", 2).rest(2)
+    for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
+        bass.add(n, Duration.HALF)
+    render("complete_rock", score)
+
+
+# ── Drums layering (salsa) ───────────────────────────────────────────────
+
+def gen_salsa_layered():
+    score = Score("4/4", bpm=180)
+    score.drums("salsa", repeats=4, fill="salsa", fill_every=4)
+    pads = score.part("pads", synth="sine", envelope="pad", volume=0.3)
+    lead = score.part("lead", synth="saw", envelope="pluck", volume=0.4)
+    bass = score.part("bass", synth="sine", envelope="pluck", volume=0.45)
+    for chord in Key("D", "minor").progression("ii", "V", "i", "i") * 2:
+        pads.add(chord, Duration.WHOLE)
+    lead.add("A5", 0.67).add("G5", 0.33).add("F5", 0.67).add("E5", 0.33)
+    for n in ["D2", "A2", "D2", "F2"] * 2:
+        bass.add(n, Duration.QUARTER)
+    render("salsa_layered", score)
+
+
+# ── Playback basic ───────────────────────────────────────────────────────
+
+def gen_playback_basic():
+    score = Score("4/4", bpm=140)
+    score.drums("bossa nova", repeats=4)
+    chords = score.part("chords", synth="sine", envelope="pad")
+    for sym in ["Am", "Dm", "E7", "Am"]:
+        chords.add(Chord.from_symbol(sym), Duration.WHOLE)
+    render("playback_basic", score)
+
+
+# ── Cookbook: song with sections ──────────────────────────────────────────
+
+def gen_song_sections():
+    score = Score("4/4", bpm=120)
+    score.drums("rock", repeats=16, fill="rock", fill_every=4)
+    chords = score.part("chords", synth="saw", envelope="pad")
+    lead = score.part("lead", synth="triangle", envelope="pluck")
+    score.section("verse")
+    for sym in ["Am", "F", "C", "G"]:
+        chords.add(Chord.from_symbol(sym), Duration.WHOLE)
+    lead.add("A4", 1).add("C5", 1).add("E5", 1).rest(1)
+    lead.add("F5", 1).add("E5", 1).add("C5", 2)
+    score.section("chorus")
+    lead.set(reverb=0.4, lowpass=5000)
+    for sym in ["F", "G", "Am", "C"]:
+        chords.add(Chord.from_symbol(sym), Duration.WHOLE)
+    lead.add("C6", 2).add("A5", 1).add("G5", 1)
+    lead.add("F5", 2).add("E5", 2)
+    score.end_section()
+    score.repeat("verse")
+    score.repeat("chorus", times=2)
+    render("song_sections", score)
+
+
+GENERATORS = [
+    gen_piano_hold,
+    gen_articulations,
+    gen_dynamics,
+    gen_filter_ramp,
+    gen_rock_beat,
+    gen_bossa_nova_pattern,
+    gen_salsa_pattern,
+    gen_afrobeat_pattern,
+    gen_bossa_nova,
+    gen_djembe,
+    gen_tabla,
+    gen_metal_blast,
+    gen_cajon,
+    gen_tabla_teental,
+    gen_tabla_keherwa,
+    gen_tabla_chakradar,
+    gen_dhol,
+    gen_dholak,
+    gen_mridangam,
+    gen_march_snare,
+    gen_ensemble,
+    gen_strum,
+    gen_swell,
+    gen_arpeggio,
+    gen_legato_glide,
+    gen_acid_house,
+    gen_dub_reggae,
+    gen_jazz_ballad,
+    gen_quickstart,
+    gen_chords_basic,
+    gen_complete_rock,
+    gen_salsa_layered,
+    gen_playback_basic,
+    gen_song_sections,
+]
+
+
+if __name__ == "__main__":
+    print("Generating audio samples for docs...")
+    print()
+    for gen in GENERATORS:
+        gen()
+    print()
+    print(f"Done. {len(GENERATORS)} files in {AUDIO_DIR}")

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

@@ -10,7 +10,7 @@ the genre -- they tell the listener's body how to move before a single
 melodic note is played.
 
 PyTheory includes a complete drum system -- 51 synthesized percussion
-sounds, 80+ pattern presets across dozens of genres, and 21 fill presets.
+sounds, 95+ pattern presets across dozens of genres, and 30 fill presets.
 Every sound is generated from waveforms; no samples needed.
 
 Drum Sounds
@@ -121,10 +121,18 @@ MRIDANGAM_THA (101)
 
 **Djembe:** DJEMBE_BASS (102), DJEMBE_TONE (103), DJEMBE_SLAP (104)
 
-**Cajón:** CAJON_SLAP (109), CAJON_TAP (110)
+**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
 --------------
 
@@ -241,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
 -----
 
@@ -252,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")
@@ -328,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
 ----------------
 
@@ -357,11 +379,26 @@ the pitch upward.
 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
 ~~~~
 
@@ -379,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
 ~~~~~~
 
@@ -396,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
 ~~~~~~~~~
 
@@ -414,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
 ~~~~~~
 
@@ -424,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
 ~~~~~~~~~
@@ -447,10 +505,19 @@ 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
 ~~~~~
@@ -459,15 +526,76 @@ 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.
 
-**2 sounds** -- slap (sharp, snare-like) and tap (bass-like).
+**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=4)
+   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/playback.rst

@@ -66,6 +66,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

@@ -185,6 +185,10 @@ chords, melody, bass, each with their own synth and effects:
 
    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=600)
 
-   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
 --------
 

docs/index.rst

@@ -62,7 +62,10 @@ it through your speakers, export MIDI, finish in your DAW:
    lead.arpeggio("Am", bars=4, pattern="updown", octaves=2)
 
    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"]
 
@@ -2324,6 +2324,681 @@ def sitar_drone():
     play_song(score, "Sitar Drone — Raga Bhairav (22-Shruti JI, hold() polyphony)")
 
 
+def acid_tabla():
+    """Acid Tabla — 303 filter automation meets Indian percussion."""
+    score = Score("4/4", bpm=132)
+
+    # ── House drums ──
+    score.drums("house", repeats=20, fill="house", fill_every=8)
+    score.set_drum_effects(volume=0.45)
+
+    # ── 303 acid bass ──
+    acid = score.part("acid", synth="saw", volume=0.75,
+                      legato=True, glide=0.035,
+                      distortion=0.35, distortion_drive=4.5,
+                      saturation=0.15, humanize=0.05)
+
+    # Intro (4 bars): filter closed, high resonance
+    acid.set(lowpass=600, lowpass_q=12.0)
+    for _ in range(4):
+        for n in ["C3","C3","C2","C3","Eb3","C2","G2","C3"]:
+            acid.add(n, Duration.EIGHTH)
+
+    # Build (4 bars): filter opens
+    acid.ramp(over=Duration.WHOLE * 4, curve="ease_in", lowpass=4500)
+    for _ in range(4):
+        for n in ["C2","G2","C3","Eb3","C2","Bb2","G2","C3"]:
+            acid.add(n, Duration.EIGHTH)
+
+    # Peak (4 bars): wide open, wilder pattern
+    acid.set(lowpass=7000, lowpass_q=7.0)
+    for _ in range(2):
+        for n in ["C2","C3","Eb3","G3","C2","Bb2","G2","Eb3"]:
+            acid.add(n, Duration.EIGHTH)
+    for _ in range(2):
+        for n in ["C2","Eb3","C3","G3","Bb2","C3","G2","C2"]:
+            acid.add(n, Duration.EIGHTH)
+
+    # Tabla section (4 bars): filter pulls back
+    acid.set(lowpass=3000, lowpass_q=5.0)
+    for _ in range(4):
+        for n in ["C2","G2","C3","C2","Eb2","G2","Bb2","C2"]:
+            acid.add(n, Duration.EIGHTH)
+
+    # Outro (4 bars): filter closes
+    acid.ramp(over=Duration.WHOLE * 4, curve="ease_out", lowpass=400, lowpass_q=15.0)
+    for _ in range(4):
+        for n in ["C3","G2","C2","C3","C2","G2","Eb2","C2"]:
+            acid.add(n, Duration.EIGHTH)
+
+    # ── Tabla: enters bar 9, rides through to the end ──
+    tabla = score.part("tabla", synth="sine", volume=0.55, reverb=0.15)
+
+    # 8 bars rest
+    for _ in range(64):
+        tabla.rest(Duration.EIGHTH)
+
+    # Bars 9-12: keherwa groove
+    for _ in range(4):
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=100, articulation="accent")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=55)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=50)
+        tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=88)
+        tabla.hit(DrumSound.TABLA_TIN, Duration.EIGHTH, velocity=82)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.EIGHTH, velocity=52)
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=95, articulation="accent")
+        tabla.hit(DrumSound.TABLA_GE, Duration.EIGHTH, velocity=78)
+
+    # Bars 13-14: busier with 16ths
+    for _ in range(2):
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=105, articulation="marcato")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=48)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=52)
+        tabla.hit(DrumSound.TABLA_NA, Duration.EIGHTH, velocity=90)
+        tabla.hit(DrumSound.TABLA_TIN, Duration.EIGHTH, velocity=85)
+        tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=48)
+        tabla.hit(DrumSound.TABLA_NA, Duration.SIXTEENTH, velocity=58)
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=100, articulation="accent")
+        tabla.hit(DrumSound.TABLA_GE_BEND, Duration.EIGHTH, velocity=88)
+
+    # Bars 15-16: tihai crescendo ending
+    for vel in [85, 90, 95]:
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=vel, articulation="accent")
+        tabla.hit(DrumSound.TABLA_TIT, Duration.SIXTEENTH, velocity=int(vel * 0.6))
+        tabla.hit(DrumSound.TABLA_NA, Duration.SIXTEENTH, velocity=int(vel * 0.75))
+    for vel in [100, 105, 110]:
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=vel, articulation="marcato")
+        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=127, articulation="fermata")
+    tabla.hit(DrumSound.TABLA_GE_BEND, Duration.QUARTER, velocity=110)
+    tabla.rest(Duration.HALF)
+
+    # Bars 17-20: tabla continues through outro, lighter
+    for _ in range(4):
+        tabla.hit(DrumSound.TABLA_DHA, Duration.EIGHTH, velocity=85, 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)
+
+    # ── Pad: enters at peak, fades during outro ──
+    pad = score.part("pad", synth="supersaw", envelope="pad", volume=0.0,
+                     reverb=0.4, chorus=0.2, detune=10, lowpass=2500)
+    for _ in range(32):
+        pad.rest(Duration.QUARTER)
+    pad.ramp(over=Duration.WHOLE * 2, volume=0.18)
+    for sym in ["Cm", "Ab", "Eb", "Bb"] * 3:
+        pad.add(Chord.from_symbol(sym), Duration.WHOLE)
+    pad.ramp(over=Duration.WHOLE * 2, curve="ease_out", volume=0.0)
+    for sym in ["Cm", "Cm"]:
+        pad.add(Chord.from_symbol(sym), Duration.WHOLE)
+
+    play_song(score, "Acid Tabla — 303 filter automation + tabla (ramp, articulations, Part.hit)")
+
+
+def snare_cadence():
+    """Snare Cadence — full drumline with ensemble, flams, diddles, cheese."""
+    score = Score("4/4", bpm=120)
+
+    S = DrumSound.MARCH_SNARE
+    R = DrumSound.MARCH_RIMSHOT
+    C = DrumSound.MARCH_CLICK
+    Q1 = DrumSound.QUAD_1
+    Q2 = DrumSound.QUAD_2
+    Q3 = DrumSound.QUAD_3
+    Q4 = DrumSound.QUAD_4
+    QS = DrumSound.QUAD_SPOCK
+    B1 = DrumSound.BASS_1
+    B2 = DrumSound.BASS_2
+    B3 = DrumSound.BASS_3
+    B4 = DrumSound.BASS_4
+    B5 = DrumSound.BASS_5
+
+    # Snare line — 8 players
+    p = score.part("snares", synth="sine", volume=0.9, reverb=0.2, ensemble=8)
+    # Quad line — 4 players
+    q = score.part("quads", synth="sine", volume=0.5, reverb=0.2, ensemble=4)
+    # Bass line — 5 players
+    b = score.part("basses", synth="sine", volume=0.55, reverb=0.2, ensemble=5)
+
+    _trip = 1.0 / 3
+
+    # Helper: bass split run (down or up)
+    def bass_down(dur=Duration.SIXTEENTH):
+        b.hit(B1, dur, velocity=95)
+        b.hit(B2, dur, velocity=90)
+        b.hit(B3, dur, velocity=85)
+        b.hit(B4, dur, velocity=90)
+
+    def bass_up(dur=Duration.SIXTEENTH):
+        b.hit(B4, dur, velocity=90)
+        b.hit(B3, dur, velocity=85)
+        b.hit(B2, dur, velocity=90)
+        b.hit(B1, dur, velocity=95)
+
+    def bass_hit(dur=Duration.QUARTER):
+        b.hit(B3, dur, velocity=100)
+
+    def quad_sweep_down():
+        q.hit(Q1, Duration.SIXTEENTH, velocity=95)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=88)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=82)
+        q.hit(Q4, Duration.SIXTEENTH, velocity=78)
+
+    def quad_sweep_up():
+        q.hit(Q4, Duration.SIXTEENTH, velocity=78)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=82)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=88)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=95)
+
+    # ── Click count-off ──
+    for _ in range(4):
+        p.hit(C, Duration.QUARTER, velocity=95)
+        q.rest(Duration.QUARTER)
+        b.rest(Duration.QUARTER)
+
+    # ── Section 1: 16th groove — snares only (4 bars) ──
+    for _ in range(16):
+        q.rest(Duration.QUARTER)
+        b.rest(Duration.QUARTER)
+
+    for _ in range(2):
+        p.hit(R, Duration.SIXTEENTH, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(S, Duration.SIXTEENTH, velocity=35)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(R, Duration.SIXTEENTH, velocity=115)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(R, Duration.SIXTEENTH, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=35)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(R, Duration.SIXTEENTH, velocity=120)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+
+    # Triplets mixed in
+    for _ in range(2):
+        p.hit(R, _trip, velocity=118)
+        p.hit(S, _trip, velocity=32)
+        p.hit(S, _trip, velocity=30)
+        p.hit(R, _trip, velocity=115)
+        p.hit(S, _trip, velocity=28)
+        p.hit(S, _trip, velocity=32)
+        p.hit(R, Duration.SIXTEENTH, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(S, Duration.SIXTEENTH, velocity=28)
+        p.hit(R, _trip, velocity=118)
+        p.hit(S, _trip, velocity=30)
+        p.hit(S, _trip, velocity=35)
+
+    # ── Section 2: Quads + bass enter (4 bars) ──
+    for _ in range(2):
+        p.flam(S, Duration.QUARTER, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.hit(R, _trip, velocity=118)
+        p.hit(S, _trip, velocity=28)
+        p.hit(S, _trip, velocity=30)
+        p.flam(S, Duration.QUARTER, velocity=118)
+
+        quad_sweep_down()
+        q.hit(QS, Duration.QUARTER, velocity=100)
+        quad_sweep_up()
+        q.hit(QS, Duration.QUARTER, velocity=100)
+
+        bass_hit()
+        b.hit(B5, Duration.QUARTER, velocity=95)
+        bass_hit()
+        b.hit(B1, Duration.QUARTER, velocity=95)
+
+    for _ in range(2):
+        p.hit(S, _trip, velocity=35)
+        p.flam(S, _trip * 2, velocity=118)
+        p.hit(S, Duration.SIXTEENTH, velocity=30)
+        p.hit(S, Duration.SIXTEENTH, velocity=32)
+        p.flam(S, Duration.QUARTER, velocity=118)
+        p.hit(S, _trip, velocity=28)
+        p.hit(R, _trip, velocity=122)
+        p.hit(S, _trip, velocity=35)
+
+        quad_sweep_down()
+        quad_sweep_up()
+        q.hit(Q1, Duration.EIGHTH, velocity=95)
+        q.hit(Q4, Duration.EIGHTH, velocity=85)
+        q.hit(QS, Duration.QUARTER, velocity=100)
+
+        bass_down()
+        bass_up()
+        b.hit(B3, Duration.HALF, velocity=100)
+
+    # ── Section 3: Flams + diddles + full line (4 bars) ──
+    for _ in range(2):
+        p.flam(S, Duration.QUARTER, velocity=120)
+        p.diddle(S, Duration.EIGHTH, velocity=45)
+        p.hit(S, _trip, velocity=30)
+        p.hit(S, _trip, velocity=32)
+        p.hit(S, _trip, velocity=28)
+        p.hit(R, Duration.EIGHTH, velocity=122)
+        p.diddle(S, Duration.EIGHTH, velocity=42)
+
+        q.hit(Q1, Duration.QUARTER, velocity=95)
+        q.hit(Q3, Duration.EIGHTH, velocity=55)
+        q.hit(Q2, _trip, velocity=55)
+        q.hit(Q3, _trip, velocity=55)
+        q.hit(Q4, _trip, velocity=55)
+        q.hit(QS, Duration.EIGHTH, velocity=100)
+        q.hit(Q1, Duration.EIGHTH, velocity=55)
+
+        bass_hit()
+        b.hit(B1, Duration.EIGHTH, velocity=90)
+        b.hit(B5, Duration.EIGHTH, velocity=95)
+        bass_hit()
+        b.hit(B5, Duration.EIGHTH, velocity=90)
+        b.hit(B1, Duration.EIGHTH, velocity=95)
+
+    for _ in range(2):
+        p.diddle(S, Duration.EIGHTH, velocity=45)
+        p.hit(R, _trip, velocity=120)
+        p.hit(S, _trip, velocity=30)
+        p.hit(S, _trip, velocity=32)
+        p.diddle(S, Duration.EIGHTH, velocity=48)
+        p.hit(R, _trip, velocity=118)
+        p.hit(S, _trip, velocity=28)
+        p.hit(S, _trip, velocity=30)
+        p.flam(S, Duration.EIGHTH, velocity=122)
+        p.hit(S, Duration.EIGHTH, velocity=35)
+
+        quad_sweep_down()
+        quad_sweep_up()
+        quad_sweep_down()
+        quad_sweep_up()
+
+        bass_down()
+        bass_up()
+        bass_down()
+        bass_up()
+
+    # ── Section 4: Cheese + 32nds (4 bars) ──
+    for _ in range(2):
+        p.cheese(S, Duration.QUARTER, velocity=120)
+        p.hit(S, 0.0625, velocity=30)
+        p.hit(S, 0.0625, velocity=32)
+        p.hit(S, 0.0625, velocity=35)
+        p.hit(S, 0.0625, velocity=30)
+        p.cheese(S, Duration.QUARTER, velocity=118)
+        p.diddle(S, Duration.EIGHTH, velocity=48)
+        p.hit(R, Duration.EIGHTH, velocity=125)
+
+        q.hit(QS, Duration.QUARTER, velocity=105)
+        q.hit(Q1, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q2, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q3, Duration.SIXTEENTH, velocity=55)
+        q.hit(Q4, Duration.SIXTEENTH, velocity=55)
+        q.hit(QS, Duration.QUARTER, velocity=105)
+        q.hit(Q4, Duration.EIGHTH, velocity=55)
+        q.hit(Q1, Duration.EIGHTH, velocity=90)
+
+        bass_hit()
+        b.hit(B1, Duration.EIGHTH, velocity=90)
+        b.hit(B3, Duration.EIGHTH, velocity=85)
+        b.hit(B5, Duration.EIGHTH, velocity=95)
+        b.hit(B3, Duration.EIGHTH, velocity=85)
+        bass_hit()
+        b.rest(Duration.QUARTER)
+
+    # All cheese
+    p.cheese(S, Duration.QUARTER, velocity=122)
+    p.cheese(S, Duration.QUARTER, velocity=120)
+    p.cheese(S, Duration.QUARTER, velocity=125)
+    p.cheese(S, Duration.QUARTER, velocity=122)
+
+    q.hit(QS, Duration.QUARTER, velocity=105)
+    q.hit(QS, Duration.QUARTER, velocity=105)
+    q.hit(QS, Duration.QUARTER, velocity=108)
+    q.hit(QS, Duration.QUARTER, velocity=105)
+
+    b.hit(B5, Duration.QUARTER, velocity=100)
+    b.hit(B3, Duration.QUARTER, velocity=100)
+    b.hit(B1, Duration.QUARTER, velocity=100)
+    b.hit(B3, Duration.QUARTER, velocity=100)
+
+    p.flam(S, Duration.EIGHTH, velocity=120)
+    p.diddle(S, Duration.EIGHTH, velocity=50)
+    p.flam(S, Duration.EIGHTH, velocity=122)
+    p.diddle(S, Duration.EIGHTH, velocity=52)
+    p.flam(S, Duration.EIGHTH, velocity=125)
+    p.diddle(S, Duration.EIGHTH, velocity=55)
+    p.hit(R, Duration.EIGHTH, velocity=127)
+    p.hit(S, Duration.EIGHTH, velocity=38)
+
+    quad_sweep_down()
+    quad_sweep_up()
+    quad_sweep_down()
+    quad_sweep_up()
+
+    bass_down()
+    bass_up()
+    bass_down()
+    bass_up()
+
+    # ── Section 5: 16ths + triplet 16ths + 32nds (4 bars) ──
+    _trip16 = 1.0 / 6
+
+    for _ in range(2):
+        for beat in range(4):
+            p.hit(R, _trip, velocity=118)
+            p.hit(S, _trip, velocity=35)
+            p.hit(S, _trip, velocity=32)
+
+        quad_sweep_down()
+        quad_sweep_up()
+        quad_sweep_down()
+        quad_sweep_up()
+
+        bass_hit()
+        b.hit(B5, Duration.QUARTER, velocity=95)
+        bass_hit()
+        b.hit(B1, Duration.QUARTER, velocity=95)
+
+    # 32nd run crescendo
+    for i in range(32):
+        p.hit(S, 0.0625, velocity=min(22 + i * 3, 92))
+    p.hit(R, Duration.EIGHTH, velocity=125)
+    p.hit(R, Duration.EIGHTH, velocity=127)
+
+    for _ in range(4):
+        q.hit(Q1, 0.0625, velocity=55)
+        q.hit(Q2, 0.0625, velocity=55)
+        q.hit(Q3, 0.0625, velocity=55)
+        q.hit(Q4, 0.0625, velocity=55)
+    q.hit(QS, Duration.QUARTER, velocity=108)
+
+    bass_down()
+    bass_up()
+    bass_down()
+    b.hit(B5, Duration.QUARTER, velocity=100)
+    b.hit(B1, Duration.QUARTER, velocity=100)
+
+    # Triplet 16ths — all sections
+    for _ in range(2):
+        for beat in range(4):
+            p.hit(R, _trip16, velocity=115)
+            p.hit(S, _trip16, velocity=30)
+            p.hit(S, _trip16, velocity=32)
+            p.hit(R, _trip16, velocity=112)
+            p.hit(S, _trip16, velocity=28)
+            p.hit(S, _trip16, velocity=30)
+
+        for beat in range(4):
+            q.hit(Q1, _trip16, velocity=90)
+            q.hit(Q2, _trip16, velocity=55)
+            q.hit(Q3, _trip16, velocity=55)
+            q.hit(Q4, _trip16, velocity=55)
+            q.hit(Q3, _trip16, velocity=55)
+            q.hit(Q2, _trip16, velocity=55)
+
+        bass_down()
+        bass_up()
+        bass_down()
+        bass_up()
+
+    # ── Section 6: Buzz roll climax (2 bars) ──
+    for i in range(64):
+        p.hit(S, 0.0625, velocity=min(20 + i * 1.5, 100))
+    p.hit(R, Duration.EIGHTH, velocity=127)
+    p.hit(R, Duration.EIGHTH, velocity=127)
+
+    for i in range(32):
+        q.hit([Q1, Q2, Q3, Q4][i % 4], 0.0625, velocity=min(40 + i * 2, 95))
+    q.hit(QS, Duration.QUARTER, velocity=110)
+
+    for i in range(16):
+        b.hit([B1, B2, B3, B4, B5, B4, B3, B2,
+               B1, B2, B3, B4, B5, B4, B3, B2][i], Duration.SIXTEENTH, velocity=90)
+    b.hit(B3, Duration.HALF, velocity=100)
+    b.hit(B3, Duration.HALF, velocity=100)
+
+    # ── Ending: big unison hits ──
+    p.hit(R, Duration.EIGHTH, velocity=127)
+    q.hit(QS, Duration.EIGHTH, velocity=110)
+    b.hit(B3, Duration.EIGHTH, velocity=100)
+
+    p.rest(Duration.QUARTER + Duration.EIGHTH)
+    q.rest(Duration.QUARTER + Duration.EIGHTH)
+    b.rest(Duration.QUARTER + Duration.EIGHTH)
+
+    p.hit(R, Duration.EIGHTH, velocity=127)
+    q.hit(QS, Duration.EIGHTH, velocity=110)
+    b.hit(B3, Duration.EIGHTH, velocity=100)
+
+    p.rest(Duration.QUARTER + Duration.EIGHTH)
+    q.rest(Duration.QUARTER + Duration.EIGHTH)
+    b.rest(Duration.QUARTER + Duration.EIGHTH)
+
+    # Flam into final CRACK — all sections
+    p.flam(S, Duration.EIGHTH, velocity=127)
+    q.hit(QS, Duration.EIGHTH, velocity=110)
+    b.hit(B3, Duration.EIGHTH, velocity=100)
+
+    p.rest(Duration.QUARTER + Duration.EIGHTH)
+    q.rest(Duration.QUARTER + Duration.EIGHTH)
+    b.rest(Duration.QUARTER + Duration.EIGHTH)
+
+    p.hit(R, Duration.QUARTER, velocity=127)
+    q.hit(QS, Duration.QUARTER, velocity=110)
+    b.hit(B3, Duration.QUARTER, velocity=100)
+
+    p.rest(Duration.HALF)
+    q.rest(Duration.HALF)
+    b.rest(Duration.HALF)
+
+    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),
@@ -2355,6 +3030,9 @@ SONGS = {
     "28": ("Descent (Generative — different every time)", descent),
     "29": ("Pop Rock (I-V-vi-IV)", pop_rock),
     "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__":
@@ -2368,7 +3046,7 @@ if __name__ == "__main__":
             print(f"    {key:>2}. {name}")
 
         print()
-        choice = input("  Pick a song (1-30, or 'all'): ").strip()
+        choice = input("  Pick a song (1-33, or 'all'): ").strip()
         print()
 
         if choice == "all":

examples/sprunki.py

@@ -0,0 +1,69 @@
+"""Sprunki Simon Phase 1 — melody reference.
+
+Notes transcribed from MIDI. Use as a base for arrangements.
+
+Usage:
+    python examples/sprunki.py
+"""
+
+import sounddevice as sd
+
+from pytheory import Score, Duration
+from pytheory.play import render_score, SAMPLE_RATE
+
+
+def sprunki_simon():
+    score = Score("4/4", bpm=200)
+
+    lead = score.part("lead", synth="square", envelope="pluck", volume=0.5,
+                      lowpass=4500, detune=3, reverb=0.1)
+
+    # Phrase A
+    lead.add("E4", 1.0)
+    lead.add("G4", 1.0)
+    lead.rest(1.5)
+    lead.add("A4", 0.5)
+    lead.add("B4", 1.0)
+    lead.add("A4", 1.0)
+    lead.add("G4", 1.0)
+    lead.add("D4", 1.0)
+
+    # Phrase B
+    lead.add("E4", 1.0)
+    lead.add("G4", 1.0)
+    lead.rest(1.5)
+    lead.add("A4", 0.5)
+    lead.add("D4", 2.0)
+    lead.add("B3", 1.0)
+    lead.add("A3", 0.5)
+    lead.add("D4", 0.5)
+
+    # Phrase C
+    lead.add("E4", 1.0)
+    lead.add("G4", 1.0)
+    lead.rest(1.5)
+    lead.add("A4", 0.5)
+    lead.add("B4", 1.0)
+    lead.add("A4", 1.0)
+    lead.add("G4", 1.0)
+    lead.add("B4", 1.0)
+
+    # Phrase D
+    lead.add("A4", 2.0)
+    lead.add("G4", 1.0)
+    lead.add("E4", 1.0)
+    lead.add("B3", 2.0)
+    lead.add("D4", 2.0)
+
+    return score
+
+
+if __name__ == "__main__":
+    score = sprunki_simon()
+    print("  Sprunki Simon Phase 1")
+    try:
+        buf = render_score(score)
+        sd.play(buf, SAMPLE_RATE)
+        sd.wait()
+    except KeyboardInterrupt:
+        sd.stop()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytheory"
-version = "0.36.3"
+version = "0.39.3"
 description = "Music Theory for Humans"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,6 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "numeral",
     "sounddevice",
     "scipy",
 ]

pytheory/__init__.py

@@ -1,6 +1,6 @@
 """PyTheory: Music Theory for Humans."""
 
-__version__ = "0.36.3"
+__version__ = "0.39.3"
 
 from .tones import Tone, Interval
 from .systems import System, SYSTEMS, TET
@@ -23,7 +23,7 @@ __all__ = [
     "PROGRESSIONS", "Chord", "Fretboard", "Fingering", "analyze_progression",
     "System", "SYSTEMS", "TET", "CHARTS", "charts_for_fretboard",
     "play", "save", "save_midi", "play_progression", "play_pattern",
-    "play_score", "Synth", "Envelope",
+    "play_score", "render_score", "Synth", "Envelope",
     "Duration", "TimeSignature", "RhythmNote", "Rest", "Score", "Part",
     "DrumSound", "Pattern", "Section", "INSTRUMENTS",
 ]

pytheory/_statics.py

@@ -2,6 +2,43 @@ import math
 
 REFERENCE_A = 440
 
+# ── Roman numeral helpers (replaces `numeral` package) ───────────────────
+
+_ROMAN_MAP = [
+    (1000, "M"), (900, "CM"), (500, "D"), (400, "CD"),
+    (100, "C"), (90, "XC"), (50, "L"), (40, "XL"),
+    (10, "X"), (9, "IX"), (5, "V"), (4, "IV"), (1, "I"),
+]
+
+_ROMAN_VALUES = {
+    "I": 1, "V": 5, "X": 10, "L": 50, "C": 100, "D": 500, "M": 1000,
+}
+
+
+def int2roman(n: int) -> str:
+    """Convert an integer to an uppercase Roman numeral string."""
+    result = []
+    for value, numeral in _ROMAN_MAP:
+        while n >= value:
+            result.append(numeral)
+            n -= value
+    return "".join(result)
+
+
+def roman2int(s: str) -> int:
+    """Convert a Roman numeral string (case-insensitive) to an integer."""
+    s = s.upper()
+    total = 0
+    prev = 0
+    for ch in reversed(s):
+        val = _ROMAN_VALUES.get(ch, 0)
+        if val < prev:
+            total -= val
+        else:
+            total += val
+        prev = val
+    return total
+
 # Index of C in the Western tone list (A=0, A#=1, B=2, C=3, ...).
 # Scientific pitch notation changes octave at C, not A, so this offset
 # is needed for all octave arithmetic.

pytheory/chords.py

@@ -849,7 +849,7 @@ class Chord:
             >>> Chord([D4, F4, A4]).analyze("C")
             'ii'
         """
-        import numeral as numeral_mod
+        from ._statics import int2roman
         from .scales import TonedScale
         from .systems import SYSTEMS
         from .tones import Tone
@@ -874,7 +874,7 @@ class Chord:
         scale_names = [t.name for t in scale.tones[:-1]]
 
         def _build_numeral(root, quality, degree_idx, prefix=""):
-            numeral_str = numeral_mod.int2roman(degree_idx + 1, only_ascii=True)
+            numeral_str = int2roman(degree_idx + 1)
             suffix = ""
             if "minor" in quality:
                 numeral_str = numeral_str.lower()

pytheory/play.py

@@ -358,27 +358,42 @@ def piano_wave(hz, peak=SAMPLE_PEAK, n_samples=SAMPLE_RATE):
     # Harmonics with the metallic spectral shape of steel strings
     n_harmonics = min(15, int((SAMPLE_RATE / 2) / hz))
 
+    # Vectorized harmonic synthesis — all harmonics at once
+    harmonics = numpy.arange(1, n_harmonics + 1, dtype=numpy.float64)
+
+    # Piano spectral shape as array
+    amps = numpy.zeros(n_harmonics, dtype=numpy.float64)
+    amps[0] = 1.0
+    if n_harmonics > 1:
+        amps[1] = 0.7 + 0.15 * brightness
+    if n_harmonics > 2:
+        amps[2] = 0.45 + 0.2 * brightness
+    for i in range(3, min(6, n_harmonics)):
+        amps[i] = (0.25 + 0.15 * brightness) / (i + 1)
+    for i in range(6, n_harmonics):
+        amps[i] = (0.1 + 0.1 * brightness) / ((i + 1) ** 2)
+
+    # Per-harmonic decay rates
+    h_decay_rates = (1.5 - 0.5 * brightness) * (harmonics - 1)
+
+    # Random phases
+    phases = rng.uniform(0, 2 * numpy.pi, n_harmonics)
+
     for string_hz in [hz, hz2]:
-        for n in range(1, n_harmonics + 1):
-            f_n = string_hz * n
-            if f_n >= SAMPLE_RATE / 2:
-                break
-            # Piano spectral shape: strong 1-3, then falling
-            # Upper register has more prominent harmonics (brighter)
-            if n == 1:
-                amp = 1.0
-            elif n == 2:
-                amp = 0.7 + 0.15 * brightness
-            elif n == 3:
-                amp = 0.45 + 0.2 * brightness
-            elif n <= 6:
-                amp = (0.25 + 0.15 * brightness) / n
-            else:
-                amp = (0.1 + 0.1 * brightness) / (n * n)
-            # Higher harmonics decay faster, but less so in upper register
-            h_decay = decay * numpy.exp(-(1.5 - 0.5 * brightness) * (n - 1) * t)
-            phase = rng.uniform(0, 2 * numpy.pi)
-            wave += amp * numpy.sin(2 * numpy.pi * f_n * t + phase) * h_decay
+        freqs = string_hz * harmonics  # (n_harmonics,)
+        # Mask out harmonics above Nyquist
+        valid = freqs < SAMPLE_RATE / 2
+        if not valid.any():
+            continue
+        v_freqs = freqs[valid]
+        v_amps = amps[valid]
+        v_rates = h_decay_rates[valid]
+        v_phases = phases[valid]
+
+        # 2D: (n_valid, n_samples) — one sin() call for all harmonics
+        phase_matrix = 2 * numpy.pi * v_freqs[:, numpy.newaxis] * t[numpy.newaxis, :] + v_phases[:, numpy.newaxis]
+        decay_matrix = decay[numpy.newaxis, :] * numpy.exp(-v_rates[:, numpy.newaxis] * t[numpy.newaxis, :])
+        wave += (v_amps[:, numpy.newaxis] * numpy.sin(phase_matrix) * decay_matrix).sum(axis=0)
 
     wave *= 0.5
 
@@ -1237,6 +1252,47 @@ def steel_drum_wave(hz, peak=SAMPLE_PEAK, n_samples=SAMPLE_RATE):
     return (peak * wave).astype(numpy.int16)
 
 
+def harmonium_wave(hz, peak=SAMPLE_PEAK, n_samples=SAMPLE_RATE):
+    """Harmonium — Indian pump organ, single free reed per note.
+
+    Unlike accordion (doubled musette reeds), the harmonium has one
+    reed per note — no beating, just a pure, nasal, reedy tone.
+    Constant bellows pressure, warm but slightly buzzy. The sound
+    of kirtan, qawwali, and devotional music.
+    """
+    t = numpy.arange(n_samples, dtype=numpy.float64) / SAMPLE_RATE
+    rng = numpy.random.default_rng(int(hz * 100) % 2**31)
+
+    # Single reed — odd harmonics stronger (like clarinet but warmer)
+    wave = numpy.zeros(n_samples, dtype=numpy.float64)
+    for n in range(1, 12):
+        f_n = hz * n
+        if f_n >= SAMPLE_RATE / 2:
+            break
+        amp = (1.0 / n) * (1.0 if n % 2 == 1 else 0.5)
+        phase = rng.uniform(0, 2 * numpy.pi)
+        wave += amp * numpy.sin(2 * numpy.pi * f_n * t + phase)
+
+    # Bellows pressure — gentle swell, slower than accordion
+    bellows = 0.9 + 0.1 * numpy.sin(2 * numpy.pi * 0.5 * t)
+    wave *= bellows
+
+    # Nasal character — slight midrange boost
+    import scipy.signal as _sig
+    center = min(1200, hz * 3)
+    lo = max(20, int(center - 300))
+    hi = min(SAMPLE_RATE // 2 - 1, int(center + 300))
+    if lo < hi:
+        bp, ap = _sig.butter(2, [lo, hi], btype='band', fs=SAMPLE_RATE)
+        nasal = _sig.lfilter(bp, ap, wave) * 0.2
+        wave += nasal
+
+    mx = numpy.abs(wave).max()
+    if mx > 0:
+        wave /= mx
+    return (peak * wave).astype(numpy.int16)
+
+
 def accordion_wave(hz, peak=SAMPLE_PEAK, n_samples=SAMPLE_RATE):
     """Accordion — bellows-driven free reeds.
 
@@ -1794,6 +1850,7 @@ class Synth(Enum):
     THEREMIN = "theremin_synth"
     KALIMBA = "kalimba_synth"
     STEEL_DRUM = "steel_drum_synth"
+    HARMONIUM = "harmonium_synth"
     ACCORDION = "accordion_synth"
     DIDGERIDOO = "didgeridoo_synth"
     BAGPIPE = "bagpipe_synth"
@@ -1825,7 +1882,7 @@ _SYNTH_FUNCTIONS = {
     "granular_synth": granular_wave, "vocal_synth": vocal_wave,
     "pedal_steel_synth": pedal_steel_wave, "theremin_synth": theremin_wave,
     "kalimba_synth": kalimba_wave, "steel_drum_synth": steel_drum_wave,
-    "accordion_synth": accordion_wave, "didgeridoo_synth": didgeridoo_wave,
+    "harmonium_synth": harmonium_wave, "accordion_synth": accordion_wave, "didgeridoo_synth": didgeridoo_wave,
     "bagpipe_synth": bagpipe_wave,
     "banjo_synth": banjo_wave, "mandolin_synth": mandolin_wave,
     "ukulele_synth": ukulele_wave,
@@ -1953,16 +2010,32 @@ def _noise(n_samples):
     return numpy.random.uniform(-1.0, 1.0, n_samples).astype(numpy.float32)
 
 
+# ── Cached helpers for hot paths ──────────────────────────────────────────
+
+_time_cache = {}
+
+
+def _get_time_array(n_samples):
+    """Cached time array — avoids reallocation on every synth call."""
+    if n_samples not in _time_cache:
+        _time_cache[n_samples] = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    return _time_cache[n_samples]
+
+
 def _sine_f32(hz, n_samples):
     """Float32 sine wave, normalized to ±1."""
-    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
-    return numpy.sin(2 * numpy.pi * hz * t)
+    return numpy.sin(2 * numpy.pi * hz * _get_time_array(n_samples))
+
+
+_decay_cache = {}
 
 
 def _exp_decay(n_samples, decay_rate):
-    """Exponential decay envelope from 1→0."""
-    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
-    return numpy.exp(-decay_rate * t)
+    """Exponential decay envelope from 1→0. Cached."""
+    key = (n_samples, decay_rate)
+    if key not in _decay_cache:
+        _decay_cache[key] = numpy.exp(-decay_rate * _get_time_array(n_samples))
+    return _decay_cache[key]
 
 
 def _synth_kick(n_samples):
@@ -2584,6 +2657,52 @@ def _synth_mridangam_tha(n_samples):
     return out
 
 
+def _synth_doumbek_dum(n_samples):
+    """Doumbek Dum — open center strike, deep and round."""
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    freq = 80 + 40 * numpy.exp(-25 * t)
+    phase = 2 * numpy.pi * numpy.cumsum(freq) / SAMPLE_RATE
+    body = numpy.sin(phase) * _exp_decay(n_samples, 8) * 0.8
+    thump_len = min(int(SAMPLE_RATE * 0.04), n_samples)
+    import scipy.signal as _sig
+    thump = _noise(thump_len)
+    if thump_len > 20:
+        bl, al = _sig.butter(2, [50, 250], btype='band', fs=SAMPLE_RATE)
+        thump = _sig.lfilter(bl, al, numpy.pad(thump, (0, max(0, n_samples - thump_len))))[:thump_len].astype(numpy.float32)
+    thump *= _exp_decay(thump_len, 22) * 0.7
+    body[:thump_len] += thump
+    return numpy.tanh(body * 1.3).astype(numpy.float32)
+
+
+def _synth_doumbek_tek(n_samples):
+    """Doumbek Tek — sharp edge strike, bright and cutting."""
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    ring = numpy.sin(2 * numpy.pi * 400 * t) * _exp_decay(n_samples, 22) * 0.5
+    ring2 = numpy.sin(2 * numpy.pi * 900 * t) * 0.3 * _exp_decay(n_samples, 30)
+    click_len = min(int(SAMPLE_RATE * 0.005), n_samples)
+    click = _noise(click_len) * _exp_decay(click_len, 300) * 0.9
+    import scipy.signal as _sig
+    if click_len > 10:
+        bl, al = _sig.butter(2, [2000, min(8000, SAMPLE_RATE // 2 - 1)], btype='band', fs=SAMPLE_RATE)
+        click = _sig.lfilter(bl, al, numpy.pad(click, (0, max(0, n_samples - click_len))))[:click_len].astype(numpy.float32)
+    result = ring + ring2
+    result[:click_len] += click
+    return numpy.tanh(result * 1.8).astype(numpy.float32)
+
+
+def _synth_doumbek_ka(n_samples):
+    """Doumbek Ka — muted edge slap, short and dry."""
+    n = min(n_samples, int(SAMPLE_RATE * 0.04))
+    t = numpy.arange(n, dtype=numpy.float32) / SAMPLE_RATE
+    body = numpy.sin(2 * numpy.pi * 350 * t) * _exp_decay(n, 30) * 0.4
+    slap = _noise(min(80, n)) * _exp_decay(min(80, n), 200) * 0.7
+    result = body
+    result[:min(80, n)] += slap
+    out = numpy.zeros(n_samples, dtype=numpy.float32)
+    out[:n] = numpy.tanh(result * 1.5)
+    return out
+
+
 def _synth_cajon_bass(n_samples):
     """Cajón bass — palm strike on center of the face.
 
@@ -2708,6 +2827,151 @@ def _synth_metal_hat(n_samples):
     return out
 
 
+def _synth_march_snare(n_samples):
+    """Marching snare — ultra-tight kevlar head, high and crisp.
+
+    Higher pitched than a kit snare. Very short decay — all attack,
+    no sustain. Tight snare wires give a brief sizzle.
+    """
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    # Higher-pitched body — tight kevlar pops high
+    body = numpy.sin(2 * numpy.pi * 450 * t) * _exp_decay(n_samples, 60) * 0.4
+    body2 = numpy.sin(2 * numpy.pi * 700 * t) * _exp_decay(n_samples, 75) * 0.2
+    # Sharp stick pop
+    click_len = min(int(SAMPLE_RATE * 0.001), n_samples)
+    click = _noise(click_len) * _exp_decay(click_len, 400) * 1.2
+    # Very tight snare sizzle — higher band, shorter
+    buzz_len = min(int(SAMPLE_RATE * 0.025), n_samples)
+    buzz_raw = _noise(buzz_len)
+    if buzz_len > 20:
+        bl, al = scipy.signal.butter(2, [3500, 8000], btype='band', fs=SAMPLE_RATE)
+        buzz = scipy.signal.lfilter(bl, al, numpy.pad(buzz_raw, (0, max(0, n_samples - buzz_len))))[:buzz_len]
+    else:
+        buzz = buzz_raw
+    buzz *= _exp_decay(buzz_len, 50) * 0.35
+    result = body + body2
+    result[:click_len] += click
+    result[:buzz_len] += buzz
+    return numpy.tanh(result * 2.8)
+
+
+def _synth_march_rimshot(n_samples):
+    """Marching rimshot — woody metallic crack.
+
+    The stick catches the rim — you get the full snare hit plus
+    a bright, woody-metallic crack from the aluminum rim. Short
+    ring that dies fast but gives it that cutting edge.
+    """
+    wave = _synth_march_snare(n_samples)
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    # Rim crack — bright but short, woody-metallic character
+    rim = numpy.sin(2 * numpy.pi * 1100 * t) * _exp_decay(n_samples, 45) * 0.35
+    rim2 = numpy.sin(2 * numpy.pi * 2200 * t) * _exp_decay(n_samples, 55) * 0.2
+    # Hard transient pop
+    pop_len = min(int(SAMPLE_RATE * 0.002), n_samples)
+    pop = _noise(pop_len) * _exp_decay(pop_len, 350) * 1.5
+    # Extra body punch
+    punch = numpy.sin(2 * numpy.pi * 500 * t) * _exp_decay(n_samples, 65) * 0.3
+    result = wave * 1.4 + rim + rim2 + punch
+    result[:pop_len] += pop
+    return numpy.tanh(result * 2.0)
+
+
+def _synth_march_click(n_samples):
+    """Stick click — taped hickory sticks clocked together.
+
+    Bright wood-on-wood with a slightly dampened attack from the
+    electrical tape. Not as ringy as a clave — the tape absorbs
+    some of the high overtones — but still bright and snappy.
+    """
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    # Wood resonance — brighter than before, but tape dampens ring
+    body = numpy.sin(2 * numpy.pi * 1100 * t) * _exp_decay(n_samples, 65) * 0.45
+    body2 = numpy.sin(2 * numpy.pi * 1800 * t) * _exp_decay(n_samples, 80) * 0.25
+    # Woody overtone — gives it that hickory character
+    body3 = numpy.sin(2 * numpy.pi * 2600 * t) * _exp_decay(n_samples, 95) * 0.12
+    # Bright but slightly muffled transient (tape on wood)
+    click_len = min(int(SAMPLE_RATE * 0.001), n_samples)
+    click_raw = _noise(click_len)
+    if click_len > 10:
+        bl, al = scipy.signal.butter(2, [800, 7000], btype='band', fs=SAMPLE_RATE)
+        click = scipy.signal.lfilter(bl, al, numpy.pad(click_raw, (0, max(0, n_samples - click_len))))[:click_len]
+    else:
+        click = click_raw
+    click *= _exp_decay(click_len, 350) * 0.9
+    result = body + body2 + body3
+    result[:click_len] += click
+    return numpy.tanh(result * 2.8)
+
+
+def _synth_quad(n_samples, pitch=300):
+    """Marching tenor/quad drum — tuned mylar head, bright and ringy.
+
+    Quads have a distinctive metallic ting from the high-tension
+    mylar head and aluminum shell. More ring than a kit tom,
+    brighter attack, clear pitch.
+    """
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    # Pitched body — more ring/sustain than snare
+    body = numpy.sin(2 * numpy.pi * pitch * t) * _exp_decay(n_samples, 22) * 0.5
+    # Metallic overtones — the ting
+    ting = numpy.sin(2 * numpy.pi * pitch * 2.3 * t) * _exp_decay(n_samples, 35) * 0.25
+    ting2 = numpy.sin(2 * numpy.pi * pitch * 3.1 * t) * _exp_decay(n_samples, 45) * 0.12
+    # Shell ring
+    shell = numpy.sin(2 * numpy.pi * pitch * 4.7 * t) * _exp_decay(n_samples, 55) * 0.06
+    # Sharp stick attack
+    click_len = min(int(SAMPLE_RATE * 0.001), n_samples)
+    click = _noise(click_len) * _exp_decay(click_len, 400) * 0.8
+    result = body + ting + ting2 + shell
+    result[:click_len] += click
+    return numpy.tanh(result * 2.5)
+
+
+def _synth_quad_spock(n_samples):
+    """Quad spock — rim shot on the tenor shell. Bright, ringy, cutting."""
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    ring = numpy.sin(2 * numpy.pi * 1400 * t) * _exp_decay(n_samples, 40) * 0.5
+    ring2 = numpy.sin(2 * numpy.pi * 2100 * t) * _exp_decay(n_samples, 55) * 0.25
+    click_len = min(int(SAMPLE_RATE * 0.001), n_samples)
+    click = _noise(click_len) * _exp_decay(click_len, 400) * 1.0
+    result = ring + ring2
+    result[:click_len] += click
+    return numpy.tanh(result * 2.8)
+
+
+def _synth_march_bass(n_samples, pitch=60):
+    """Marching bass drum — deep, boomy, pitched, felt beater thwack.
+
+    The beater hitting the head is a big part of the sound — a round,
+    pillowy thwack followed by the deep pitched boom. More beater
+    sound than a kit bass drum because marching bass drums project
+    outward.
+    """
+    t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
+    # Deep pitched body — sustains and rings
+    body = numpy.sin(2 * numpy.pi * pitch * t) * _exp_decay(n_samples, 10) * 0.7
+    body2 = numpy.sin(2 * numpy.pi * pitch * 2 * t) * _exp_decay(n_samples, 16) * 0.2
+    # Sub thump
+    sub = numpy.sin(2 * numpy.pi * pitch * 0.5 * t) * _exp_decay(n_samples, 8) * 0.3
+    # BIG beater thwack — dominant part of the attack
+    thwack_len = min(int(SAMPLE_RATE * 0.025), n_samples)
+    thwack_raw = _noise(thwack_len)
+    if thwack_len > 10:
+        bl, al = scipy.signal.butter(2, [150, 2500], btype='band', fs=SAMPLE_RATE)
+        thwack = scipy.signal.lfilter(bl, al, numpy.pad(thwack_raw, (0, max(0, n_samples - thwack_len))))[:thwack_len]
+    else:
+        thwack = thwack_raw
+    thwack *= _exp_decay(thwack_len, 55) * 1.5
+    # Head slap — the mylar flexing on impact
+    slap_len = min(int(SAMPLE_RATE * 0.008), n_samples)
+    slap = numpy.sin(2 * numpy.pi * pitch * 3 * numpy.arange(slap_len, dtype=numpy.float32) / SAMPLE_RATE)
+    slap *= _exp_decay(slap_len, 90) * 0.4
+    result = body + body2 + sub
+    result[:thwack_len] += thwack
+    result[:slap_len] += slap
+    return numpy.tanh(result * 2.0)
+
+
 def _synth_tabla_ge_bend(n_samples):
     """Tabla Ge with upward pitch bend — palm pressing into bayan head.
 
@@ -2802,29 +3066,27 @@ def _synth_djembe_tone(n_samples):
 def _synth_djembe_slap(n_samples):
     """Djembe slap — edge strike with fingers spread, sharp crack.
 
-    The highest, sharpest djembe sound. Fingers fan out on contact
-    creating a loud crack with minimal sustain.
+    The highest, sharpest djembe sound. A dry, high-pitched pop from
+    goatskin membrane — NOT a snare. Tight attack, very short decay,
+    skin character rather than wire rattle.
     """
     t = numpy.arange(n_samples, dtype=numpy.float32) / SAMPLE_RATE
-    # Sharp crack — mostly noise
-    crack_len = min(int(SAMPLE_RATE * 0.02), n_samples)
-    crack = _noise(crack_len) * _exp_decay(crack_len, 100) * 1.0
-    # Brief high-pitched ring
-    ring = numpy.sin(2 * numpy.pi * 600 * t) * _exp_decay(n_samples, 25) * 0.4
-    ring2 = numpy.sin(2 * numpy.pi * 1200 * t) * 0.2 * _exp_decay(n_samples, 35)
-    # Brief membrane pop
-    thump_len = min(int(SAMPLE_RATE * 0.02), n_samples)
-    thump_raw = _noise(thump_len)
-    if thump_len > 20:
-        bl, al = scipy.signal.butter(2, [300, 2000], btype='band', fs=SAMPLE_RATE)
-        thump = scipy.signal.lfilter(bl, al, numpy.pad(thump_raw, (0, max(0, n_samples - thump_len))))[:thump_len]
+    # High membrane pop — goatskin resonance, much higher than snare
+    pop = numpy.sin(2 * numpy.pi * 900 * t) * _exp_decay(n_samples, 50) * 0.5
+    pop2 = numpy.sin(2 * numpy.pi * 1600 * t) * _exp_decay(n_samples, 60) * 0.25
+    pop3 = numpy.sin(2 * numpy.pi * 2400 * t) * _exp_decay(n_samples, 80) * 0.12
+    # Very short filtered click — hand-on-skin transient, not noise rattle
+    click_len = min(int(SAMPLE_RATE * 0.008), n_samples)
+    click_raw = _noise(click_len)
+    if click_len > 20:
+        bl, al = scipy.signal.butter(2, 1800 / (SAMPLE_RATE / 2), btype='high')
+        click = scipy.signal.lfilter(bl, al, numpy.pad(click_raw, (0, max(0, n_samples - click_len))))[:click_len]
     else:
-        thump = thump_raw
-    thump *= _exp_decay(thump_len, 80) * 0.8
-    result = ring + ring2
-    result[:crack_len] += crack
-    result[:thump_len] += thump
-    return numpy.tanh(result * 1.7)
+        click = click_raw
+    click *= _exp_decay(click_len, 150) * 0.6
+    result = pop + pop2 + pop3
+    result[:click_len] += click
+    return numpy.tanh(result * 1.5)
 
 
 def _synth_guiro(n_samples):
@@ -2914,6 +3176,10 @@ def _render_drum_hit(sound_value, n_samples):
         DrumSound.DJEMBE_BASS.value: lambda n: _synth_djembe_bass(n),
         DrumSound.DJEMBE_TONE.value: lambda n: _synth_djembe_tone(n),
         DrumSound.DJEMBE_SLAP.value: lambda n: _synth_djembe_slap(n),
+        # Doumbek
+        DrumSound.DOUMBEK_DUM.value: lambda n: _synth_doumbek_dum(n),
+        DrumSound.DOUMBEK_TEK.value: lambda n: _synth_doumbek_tek(n),
+        DrumSound.DOUMBEK_KA.value: lambda n: _synth_doumbek_ka(n),
         # Cajon
         DrumSound.CAJON_BASS.value: lambda n: _synth_cajon_bass(n),
         DrumSound.CAJON_SLAP.value: lambda n: _synth_cajon_slap(n),
@@ -2922,10 +3188,39 @@ def _render_drum_hit(sound_value, n_samples):
         DrumSound.METAL_KICK.value: lambda n: _synth_metal_kick(n),
         DrumSound.METAL_SNARE.value: lambda n: _synth_metal_snare(n),
         DrumSound.METAL_HAT.value: lambda n: _synth_metal_hat(n),
+        # Marching
+        DrumSound.MARCH_SNARE.value: lambda n: _synth_march_snare(n),
+        DrumSound.MARCH_RIMSHOT.value: lambda n: _synth_march_rimshot(n),
+        DrumSound.MARCH_CLICK.value: lambda n: _synth_march_click(n),
+        # Quads (tenor drums) — pitched high to low
+        DrumSound.QUAD_1.value: lambda n: _synth_quad(n, pitch=400),
+        DrumSound.QUAD_2.value: lambda n: _synth_quad(n, pitch=330),
+        DrumSound.QUAD_3.value: lambda n: _synth_quad(n, pitch=270),
+        DrumSound.QUAD_4.value: lambda n: _synth_quad(n, pitch=220),
+        DrumSound.QUAD_SPOCK.value: lambda n: _synth_quad_spock(n),
+        # Marching bass drums — pitched high to low
+        DrumSound.BASS_1.value: lambda n: _synth_march_bass(n, pitch=90),
+        DrumSound.BASS_2.value: lambda n: _synth_march_bass(n, pitch=75),
+        DrumSound.BASS_3.value: lambda n: _synth_march_bass(n, pitch=62),
+        DrumSound.BASS_4.value: lambda n: _synth_march_bass(n, pitch=52),
+        DrumSound.BASS_5.value: lambda n: _synth_march_bass(n, pitch=42),
     }
 
     renderer = _dispatch.get(sound_value, lambda n: _synth_clave(n))
-    return renderer(n_samples)
+    result = renderer(n_samples)
+    return result
+
+
+# Drum hit cache — same sound at same length sounds identical
+_drum_cache = {}
+
+
+def _render_drum_hit_cached(sound_value, n_samples):
+    """Cached version of _render_drum_hit for pattern playback."""
+    key = (sound_value, n_samples)
+    if key not in _drum_cache:
+        _drum_cache[key] = _render_drum_hit(sound_value, n_samples)
+    return _drum_cache[key].copy()  # copy so callers can mutate
 
 
 def _render_pattern(pattern, bpm=120):
@@ -2949,7 +3244,7 @@ def _render_pattern(pattern, bpm=120):
         remaining = total_samples - start
         # Render each hit for up to 0.5 seconds
         hit_len = min(int(SAMPLE_RATE * 0.5), remaining)
-        wave = _render_drum_hit(hit.sound.value, hit_len)
+        wave = _render_drum_hit_cached(hit.sound.value, hit_len)
         vel_scale = hit.velocity / 127.0
         buf[start:start + hit_len] += wave * vel_scale
 
@@ -4055,10 +4350,48 @@ def _render_notes_to_buf(notes, buf, samples_per_beat, total_samples,
                 start += _rnd.randint(-max_offset, max_offset)
                 start = max(0, start)
             dur_ms = note.beats * 60_000 / bpm
+            # Articulation: adjust duration and velocity
+            art = getattr(note, 'articulation', '')
+            art_vel_mult = 1.0
+            art_attack_mult = 1.0  # multiplier for envelope attack
+            if art == 'staccato':
+                dur_ms *= 0.4  # short and bouncy
+            elif art == 'legato':
+                dur_ms *= 1.15  # slight overlap into next note
+            elif art == 'marcato':
+                art_vel_mult = 1.25  # heavier
+                art_attack_mult = 0.3  # sharper attack
+            elif art == 'tenuto':
+                art_attack_mult = 1.8  # softer attack, full duration
+            elif art == 'accent':
+                art_vel_mult = 1.2
+            elif art == 'fermata':
+                dur_ms *= 1.5  # held longer
             n_samples = int(SAMPLE_RATE * dur_ms / 1000)
             if start + n_samples > total_samples:
                 n_samples = total_samples - start
             if n_samples > 0 and start >= 0:
+                # Drum hit via Part.hit() — use drum synth directly
+                from .rhythm import _DrumTone
+                if isinstance(note.tone, _DrumTone):
+                    drum_wave = _render_drum_hit(note.tone.sound.value, n_samples)
+                    mixed = drum_wave.astype(numpy.float32)
+                    # Staccato fade-out for drums
+                    if art == 'staccato':
+                        fade_len = min(int(SAMPLE_RATE * 0.01), len(mixed))
+                        if fade_len > 0:
+                            mixed[-fade_len:] *= numpy.linspace(1.0, 0.0, fade_len).astype(numpy.float32)
+                    vel = getattr(note, 'velocity', 100)
+                    vel = min(127, int(vel * art_vel_mult))
+                    if humanize > 0.0:
+                        vel_jitter = int(humanize * 15)
+                        vel = max(1, min(127, vel + _rnd.randint(-vel_jitter, vel_jitter)))
+                    vel_scale = vel / 127.0
+                    end = min(start + len(mixed), total_samples)
+                    buf[start:end] += mixed[:end - start] * volume * vel_scale
+                    if not getattr(note, '_hold', False):
+                        beat_pos += note.beats
+                    continue
                 # Get pitches
                 if hasattr(note.tone, 'tones'):
                     pitches = [t.pitch(temperament=temperament, reference_pitch=reference_pitch) for t in note.tone.tones]
@@ -4159,11 +4492,18 @@ def _render_notes_to_buf(notes, buf, samples_per_beat, total_samples,
                 if noise_mix > 0:
                     noise = numpy.random.uniform(-1, 1, n_samples).astype(numpy.float32)
                     mixed = mixed * (1.0 - noise_mix * 0.5) + noise * noise_mix * 0.5
-                # Amplitude envelope
-                if a > 0 or d > 0 or s < 1.0 or r > 0:
-                    mixed = _apply_envelope(mixed, a, d, s, r)
-                # Per-note velocity
+                # Amplitude envelope (articulation may adjust attack)
+                art_a = a * art_attack_mult
+                if art_a > 0 or d > 0 or s < 1.0 or r > 0:
+                    mixed = _apply_envelope(mixed, art_a, d, s, r)
+                # Staccato: apply a quick fade-out at the end
+                if art == 'staccato':
+                    fade_len = min(int(SAMPLE_RATE * 0.01), len(mixed))
+                    if fade_len > 0:
+                        mixed[-fade_len:] *= numpy.linspace(1.0, 0.0, fade_len).astype(numpy.float32)
+                # Per-note velocity (articulation may boost)
                 vel = getattr(note, 'velocity', 100)
+                vel = min(127, int(vel * art_vel_mult))
                 if humanize > 0.0:
                     vel_jitter = int(humanize * 15)
                     vel = max(1, min(127, vel + _rnd.randint(-vel_jitter, vel_jitter)))
@@ -4361,35 +4701,71 @@ def render_score(score):
                 synth_kwargs["mod_index"] = part.fm_index
             _temperament = getattr(score, 'temperament', 'equal')
             _ref_pitch = getattr(score, 'reference_pitch', 440.0)
-            if part.legato:
-                _render_legato_to_buf(
-                    part.notes, part_buf, samples_per_beat, total_samples,
-                    synth_fn, env_tuple, part.volume, score.bpm,
-                    glide_time=part.glide, swing=effective_swing,
-                    tempo_map=tempo_map if has_tempo_changes else None,
-                    temperament=_temperament, reference_pitch=_ref_pitch)
-            else:
-                _render_notes_to_buf(
-                    part.notes, part_buf, samples_per_beat, total_samples,
-                    synth_fn, env_tuple, part.volume, score.bpm,
-                    swing=effective_swing,
-                    tempo_map=tempo_map if has_tempo_changes else None,
-                    humanize=part.humanize,
-                    detune=part.detune,
-                    spread=part.spread,
-                    stereo_buf=stereo_buf,
-                    sub_osc=part.sub_osc,
-                    noise_mix=part.noise_mix,
-                    filter_attack=part.filter_attack,
-                    filter_decay=part.filter_decay,
-                    filter_sustain=part.filter_sustain,
-                    filter_amount=part.filter_amount,
-                    vel_to_filter=part.vel_to_filter,
-                    filter_q=part.lowpass_q,
-                    synth_kwargs=synth_kwargs,
-                    temperament=_temperament,
-                    reference_pitch=_ref_pitch,
-                    analog=part.analog)
+
+            n_ensemble = max(1, getattr(part, 'ensemble', 1))
+
+            for _ens_i in range(n_ensemble):
+                # Each ensemble voice gets its own buffer
+                ens_buf = part_buf if n_ensemble == 1 else numpy.zeros(total_samples, dtype=numpy.float32)
+                # Ensemble voices get micro-variations
+                ens_humanize = part.humanize
+                ens_analog = part.analog
+                if n_ensemble > 1:
+                    import random as _ens_rnd
+                    _ens_rnd.seed(42 + _ens_i * 7)
+                    # Hybrid approach:
+                    # 1. Consistent player tendency (rush/drag) — seeded per player
+                    _player_tendency = _ens_rnd.gauss(0, 0.018)
+                    # 2. Tiny per-note wobble on top
+                    ens_humanize = max(part.humanize, 0.012)
+                    # Each player's drum tuned slightly different
+                    ens_analog = max(part.analog, 0.06 + _ens_rnd.uniform(0, 0.08))
+
+                if part.legato:
+                    _render_legato_to_buf(
+                        part.notes, ens_buf, samples_per_beat, total_samples,
+                        synth_fn, env_tuple, part.volume, score.bpm,
+                        glide_time=part.glide, swing=effective_swing,
+                        tempo_map=tempo_map if has_tempo_changes else None,
+                        temperament=_temperament, reference_pitch=_ref_pitch)
+                else:
+                    _render_notes_to_buf(
+                        part.notes, ens_buf, samples_per_beat, total_samples,
+                        synth_fn, env_tuple, part.volume, score.bpm,
+                        swing=effective_swing,
+                        tempo_map=tempo_map if has_tempo_changes else None,
+                        humanize=ens_humanize,
+                        detune=part.detune,
+                        spread=part.spread,
+                        stereo_buf=stereo_buf,
+                        sub_osc=part.sub_osc,
+                        noise_mix=part.noise_mix,
+                        filter_attack=part.filter_attack,
+                        filter_decay=part.filter_decay,
+                        filter_sustain=part.filter_sustain,
+                        filter_amount=part.filter_amount,
+                        vel_to_filter=part.vel_to_filter,
+                        filter_q=part.lowpass_q,
+                        synth_kwargs=synth_kwargs,
+                        temperament=_temperament,
+                        reference_pitch=_ref_pitch,
+                        analog=ens_analog)
+
+                if n_ensemble > 1:
+                    # Shift the whole voice by the player's consistent tendency
+                    # (some players rush, some drag — this is fixed per player)
+                    shift_samples = int(_player_tendency * samples_per_beat)
+                    if shift_samples > 0 and shift_samples < total_samples:
+                        # Player drags — shift right
+                        shifted = numpy.zeros_like(ens_buf)
+                        shifted[shift_samples:] = ens_buf[:-shift_samples]
+                        ens_buf = shifted
+                    elif shift_samples < 0 and abs(shift_samples) < total_samples:
+                        # Player rushes — shift left
+                        shifted = numpy.zeros_like(ens_buf)
+                        shifted[:shift_samples] = ens_buf[-shift_samples:]
+                        ens_buf = shifted
+                    part_buf += ens_buf / n_ensemble
 
             # Apply effects — segmented if automation exists
             auto_points = part._get_automation_points()
@@ -4510,6 +4886,10 @@ def render_score(score):
         DrumSound.DJEMBE_BASS.value: 0.0,
         DrumSound.DJEMBE_TONE.value: 0.1,
         DrumSound.DJEMBE_SLAP.value: -0.1,
+        # Doumbek
+        DrumSound.DOUMBEK_DUM.value: 0.0,
+        DrumSound.DOUMBEK_TEK.value: 0.1,
+        DrumSound.DOUMBEK_KA.value: -0.1,
         # Cajon — centered (single instrument)
         DrumSound.CAJON_BASS.value: 0.0,
         DrumSound.CAJON_SLAP.value: 0.0,
@@ -4518,6 +4898,22 @@ def render_score(score):
         DrumSound.METAL_KICK.value: 0.0,
         DrumSound.METAL_SNARE.value: 0.0,
         DrumSound.METAL_HAT.value: 0.3,
+        # Marching — centered
+        DrumSound.MARCH_SNARE.value: 0.0,
+        DrumSound.MARCH_RIMSHOT.value: 0.0,
+        DrumSound.MARCH_CLICK.value: 0.0,
+        # Quads — spread across the field
+        DrumSound.QUAD_1.value: -0.3,
+        DrumSound.QUAD_2.value: -0.1,
+        DrumSound.QUAD_3.value: 0.1,
+        DrumSound.QUAD_4.value: 0.3,
+        DrumSound.QUAD_SPOCK.value: 0.0,
+        # Bass drums — spread wide
+        DrumSound.BASS_1.value: -0.5,
+        DrumSound.BASS_2.value: -0.25,
+        DrumSound.BASS_3.value: 0.0,
+        DrumSound.BASS_4.value: 0.25,
+        DrumSound.BASS_5.value: 0.5,
     }
 
     # Render all drum Parts (may be one "drums" or split into kick/snare/hats/etc.)
@@ -4533,6 +4929,7 @@ def render_score(score):
         # Track last hit position per sound for choke (new hit dampens
         # the previous ring on the same drum)
         _last_hit_start = {}
+        _resonance = {}  # sound_id → resonance level (0.0–1.0)
 
         for hit in drum_part._drum_hits:
             pos = hit.position
@@ -4565,14 +4962,76 @@ def render_score(score):
                         part_stereo[fade_start:start, ch] *= fade
             _last_hit_start[sound_id] = start
 
+            # Cross-choke: a new hit on one sound dampens the ring of
+            # related sounds on the same instrument (e.g. djembe slap
+            # kills the bass resonance, closed hat kills open hat).
+            _CHOKE_GROUPS = {
+                # Djembe — any strike dampens the others
+                DrumSound.DJEMBE_BASS.value: (DrumSound.DJEMBE_TONE.value, DrumSound.DJEMBE_SLAP.value),
+                DrumSound.DJEMBE_TONE.value: (DrumSound.DJEMBE_BASS.value, DrumSound.DJEMBE_SLAP.value),
+                DrumSound.DJEMBE_SLAP.value: (DrumSound.DJEMBE_BASS.value, DrumSound.DJEMBE_TONE.value),
+                # Hi-hats — closed chokes open
+                DrumSound.CLOSED_HAT.value: (DrumSound.OPEN_HAT.value,),
+                DrumSound.PEDAL_HAT.value: (DrumSound.OPEN_HAT.value,),
+                # Cajón — slap dampens bass ring
+                DrumSound.CAJON_SLAP.value: (DrumSound.CAJON_BASS.value,),
+                DrumSound.CAJON_TAP.value: (DrumSound.CAJON_BASS.value,),
+                # Doumbek — tek/ka dampen dum
+                DrumSound.DOUMBEK_TEK.value: (DrumSound.DOUMBEK_DUM.value,),
+                DrumSound.DOUMBEK_KA.value: (DrumSound.DOUMBEK_DUM.value,),
+            }
+            choke_targets = _CHOKE_GROUPS.get(sound_id, ())
+            for target_id in choke_targets:
+                if target_id in _last_hit_start:
+                    prev_start = _last_hit_start[target_id]
+                    fade_len = min(int(SAMPLE_RATE * 0.004), max(0, start - prev_start))
+                    if fade_len > 0 and start > 0:
+                        fade = numpy.linspace(1.0, 0.0, fade_len).astype(numpy.float32)
+                        fade_start = max(0, start - fade_len)
+                        for ch in range(2):
+                            part_stereo[fade_start:start, ch] *= fade
+
             remaining = total_samples - start
             hit_len = min(int(SAMPLE_RATE * 0.5), remaining)
-            wave = _render_drum_hit(hit.sound.value, hit_len)
+            wave = _render_drum_hit_cached(hit.sound.value, hit_len)
             vel = hit.velocity
             if drum_humanize > 0:
                 vel_jitter = int(drum_humanize * 10)
                 vel = max(1, min(127, vel + _drum_rnd.randint(-vel_jitter, vel_jitter)))
             vel_scale = vel / 127.0
+
+            # Sympathetic resonance: marching snare builds up buzz
+            # as hits accumulate. Each hit adds to a resonance counter
+            # that scales extra snare wire buzz into the sound.
+            _RESONANCE_SOUNDS = {
+                DrumSound.MARCH_SNARE.value, DrumSound.MARCH_RIMSHOT.value,
+            }
+            if sound_id in _RESONANCE_SOUNDS:
+                reso = _resonance.get(sound_id, 0.0)
+                # Decay based on gap since last hit
+                if sound_id in _last_hit_start:
+                    gap_samples = start - _last_hit_start[sound_id]
+                    gap_sec = gap_samples / SAMPLE_RATE
+                    if gap_sec > 1.0:
+                        reso *= 0.2
+                    elif gap_sec > 0.5:
+                        reso *= 0.5
+                    elif gap_sec > 0.25:
+                        reso *= 0.8
+                # Build up (caps at 0.6)
+                reso = min(0.6, reso + 0.08)
+                _resonance[sound_id] = reso
+                # Add sympathetic buzz proportional to resonance
+                if reso > 0.1:
+                    buzz_len = min(int(SAMPLE_RATE * 0.06), hit_len)
+                    buzz = _noise(buzz_len) * reso * 0.18
+                    if buzz_len > 20:
+                        bl, al = scipy.signal.butter(
+                            2, [3000, 9000], btype='band', fs=SAMPLE_RATE)
+                        buzz = scipy.signal.lfilter(bl, al, buzz)
+                    buzz *= _exp_decay(buzz_len, 25)
+                    wave[:buzz_len] = wave[:buzz_len] + buzz.astype(numpy.float32)
+
             mono_hit = wave * vel_scale * 0.7
             # Sidechain trigger — kick only
             if hit.sound.value == DrumSound.KICK.value:

pytheory/scales.py

@@ -2,8 +2,6 @@ from __future__ import annotations
 
 from typing import Optional, Union
 
-import numeral
-
 from .systems import SYSTEMS, System
 from .tones import Tone
 
@@ -49,7 +47,8 @@ class Scale:
     def __repr__(self) -> str:
         r = []
         for (i, tone) in enumerate(self.tones):
-            degree = numeral.int2roman(i + 1, only_ascii=True)
+            from ._statics import int2roman
+            degree = int2roman(i + 1)
             r += [f"{degree}={tone.full_name}"]
 
         r = " ".join(r)
@@ -200,7 +199,7 @@ class Scale:
             >>> scale.progression("I", "IV", "V", "I")
             [<Chord (C,E,G)>, <Chord (F,A,C)>, <Chord (G,B,D)>, <Chord (C,E,G)>]
         """
-        import numeral as numeral_mod
+        from ._statics import roman2int
         chords = []
         for num in numerals:
             is_seventh = num.endswith("7")
@@ -213,7 +212,7 @@ class Scale:
             elif clean.startswith("#") and len(clean) > 1:
                 clean = clean[1:]
                 flat_offset = 1  # one semitone up
-            degree = numeral_mod.roman2int(clean.upper()) - 1
+            degree = roman2int(clean.upper()) - 1
             if is_seventh:
                 chord = self.seventh(degree)
             else:
@@ -406,7 +405,8 @@ class Scale:
         if isinstance(item, str):
             degrees = []
             for (i, tone) in enumerate(self.tones):
-                degrees.append(numeral.int2roman(i + 1, only_ascii=True))
+                from ._statics import int2roman
+                degrees.append(int2roman(i + 1))
 
             if item in degrees:
                 item = degrees.index(item)

test_pytheory.py

@@ -4869,6 +4869,19 @@ def test_duration_values():
     assert abs(Duration.TRIPLET_QUARTER.value - 2 / 3) < 1e-9
 
 
+def test_duration_arithmetic():
+    # Multiplication
+    assert Duration.WHOLE * 2 == 8.0
+    assert 2 * Duration.HALF == 4.0
+    assert Duration.QUARTER * 3 == 3.0
+    # Division
+    assert Duration.WHOLE / 2 == 2.0
+    # Addition
+    assert Duration.HALF + Duration.QUARTER == 3.0
+    assert Duration.HALF + 1.0 == 3.0
+    assert 1.0 + Duration.HALF == 3.0
+
+
 def test_time_signature_from_string_4_4():
     ts = TimeSignature.from_string("4/4")
     assert ts.beats == 4
@@ -5320,7 +5333,7 @@ def test_supersaw_wave():
 @needs_portaudio
 def test_all_synths_in_enum():
     from pytheory.play import Synth
-    assert len(Synth) == 41
+    assert len(Synth) == 42
     for s in Synth:
         wave = s(440, n_samples=1000)
         assert len(wave) == 1000
@@ -7142,7 +7155,7 @@ def test_score_system_propagates():
 
 def test_synth_enum_count():
     from pytheory.play import Synth
-    assert len(Synth) == 41
+    assert len(Synth) == 42
 
 
 def test_all_synths_render_and_enum_match():
@@ -7151,3 +7164,200 @@ def test_all_synths_render_and_enum_match():
     for s in Synth:
         wave = s(440, n_samples=1000)
         assert len(wave) == 1000
+
+
+# ── Articulations ────────────────────────────────────────────────────────
+
+def test_articulation_field_on_note():
+    from pytheory.rhythm import Note, Duration
+    n = Note(tone=None, duration=Duration.QUARTER, articulation="staccato")
+    assert n.articulation == "staccato"
+
+
+def test_articulation_default_empty():
+    from pytheory.rhythm import Note, Duration
+    n = Note(tone=None, duration=Duration.QUARTER)
+    assert n.articulation == ""
+
+
+def test_part_add_articulation():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.add("C4", Duration.QUARTER, articulation="staccato")
+    p.add("D4", Duration.QUARTER, articulation="legato")
+    p.add("E4", Duration.QUARTER, articulation="marcato")
+    p.add("F4", Duration.QUARTER, articulation="tenuto")
+    p.add("G4", Duration.QUARTER, articulation="accent")
+    p.add("A4", Duration.QUARTER, articulation="fermata")
+    assert len(p.notes) == 6
+    assert p.notes[0].articulation == "staccato"
+    assert p.notes[5].articulation == "fermata"
+
+
+@needs_portaudio
+def test_articulations_render():
+    """Articulations should produce audio without errors."""
+    from pytheory.play import render_score
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine", volume=0.3)
+    for art in ["", "staccato", "legato", "marcato", "tenuto", "accent", "fermata"]:
+        p.add("C4", Duration.QUARTER, articulation=art)
+    buf = render_score(score)
+    assert len(buf) > 0
+
+
+# ── Dynamic curves ───────────────────────────────────────────────────────
+
+def test_crescendo_adds_notes():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.crescendo(["C4", "D4", "E4", "F4"], Duration.QUARTER,
+                start_vel=40, end_vel=100)
+    assert len(p.notes) == 4
+    assert p.notes[0].velocity == 40
+    assert p.notes[3].velocity == 100
+
+
+def test_decrescendo_adds_notes():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.decrescendo(["C4", "D4", "E4", "F4"], Duration.QUARTER,
+                  start_vel=110, end_vel=40)
+    assert len(p.notes) == 4
+    assert p.notes[0].velocity == 110
+    assert p.notes[3].velocity == 40
+
+
+def test_swell_velocity_shape():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.swell(["C4", "D4", "E4", "F4", "G4"], Duration.QUARTER,
+            low_vel=30, peak_vel=110)
+    assert len(p.notes) == 5
+    # First and last should be near low_vel
+    assert p.notes[0].velocity == 30
+    assert p.notes[4].velocity == 30
+    # Middle should be at or near peak
+    assert p.notes[2].velocity == 110
+
+
+def test_dynamics_custom_velocities():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.dynamics(["C4", "D4", "E4"], Duration.QUARTER,
+               velocities=[50, 100, 75])
+    assert p.notes[0].velocity == 50
+    assert p.notes[1].velocity == 100
+    assert p.notes[2].velocity == 75
+
+
+def test_dynamics_with_articulation():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="sine")
+    p.crescendo(["C4", "D4"], Duration.QUARTER,
+                start_vel=40, end_vel=100, articulation="staccato")
+    assert p.notes[0].articulation == "staccato"
+    assert p.notes[1].articulation == "staccato"
+
+
+# ── Part.hit() ───────────────────────────────────────────────────────────
+
+def test_part_hit_adds_note():
+    from pytheory.rhythm import DrumSound, _DrumTone
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("kit", synth="sine")
+    p.hit(DrumSound.KICK, Duration.QUARTER, velocity=100)
+    p.hit(DrumSound.SNARE, Duration.QUARTER, velocity=90, articulation="accent")
+    assert len(p.notes) == 2
+    assert isinstance(p.notes[0].tone, _DrumTone)
+    assert p.notes[0].tone.sound == DrumSound.KICK
+    assert p.notes[1].articulation == "accent"
+
+
+@needs_portaudio
+def test_part_hit_renders():
+    """Part.hit() drum sounds should render through the note pipeline."""
+    from pytheory.rhythm import DrumSound
+    from pytheory.play import render_score
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("kit", synth="sine", volume=0.5)
+    p.hit(DrumSound.KICK, Duration.QUARTER)
+    p.hit(DrumSound.SNARE, Duration.QUARTER)
+    p.hit(DrumSound.CLOSED_HAT, Duration.QUARTER)
+    p.hit(DrumSound.CRASH, Duration.QUARTER)
+    buf = render_score(score)
+    assert len(buf) > 0
+
+
+# ── Part.ramp() ──────────────────────────────────────────────────────────
+
+def test_ramp_generates_automation():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="saw", lowpass=200)
+    p.ramp(over=4.0, lowpass=8000)
+    # Should have generated automation points
+    assert len(p._automation) > 0
+    # First point should be near 200, last near 8000
+    first_lp = p._automation[0][1].get("lowpass", 0)
+    last_lp = p._automation[-1][1].get("lowpass", 0)
+    assert first_lp < 1000  # near start
+    assert last_lp > 7000  # near target
+
+
+def test_ramp_easing_curves():
+    score = pytheory.Score("4/4", bpm=120)
+    for curve in ["linear", "ease_in", "ease_out", "ease_in_out"]:
+        p = score.part(f"test_{curve}", synth="saw", lowpass=200)
+        p.ramp(over=4.0, curve=curve, lowpass=8000)
+        assert len(p._automation) > 0
+
+
+def test_ramp_multiple_params():
+    score = pytheory.Score("4/4", bpm=120)
+    p = score.part("test", synth="saw", lowpass=200)
+    p.ramp(over=4.0, lowpass=8000, reverb=0.5)
+    # Should have both params in automation points
+    last_point = p._automation[-1][1]
+    assert "lowpass" in last_point
+    assert "reverb_mix" in last_point  # mapped from "reverb"
+
+
+# ── Cross-choke ──────────────────────────────────────────────────────────
+
+def test_djembe_patterns_exist():
+    from pytheory.rhythm import Pattern
+    for name in ["djembe", "kuku", "soli", "dununba", "tiriba",
+                 "yankadi", "djansa", "mendiani"]:
+        p = Pattern.preset(name)
+        assert p.beats > 0
+        assert len(p.hits) > 0
+
+
+def test_djembe_fills_exist():
+    from pytheory.rhythm import Pattern
+    for name in ["djembe call", "djembe roll", "djembe break"]:
+        f = Pattern.fill(name)
+        assert f.beats == 4.0
+        assert len(f.hits) > 0
+
+
+def test_cajon_fills_exist():
+    from pytheory.rhythm import Pattern
+    for name in ["cajon flam", "cajon rumble", "cajon breakdown"]:
+        f = Pattern.fill(name)
+        assert f.beats == 4.0
+        assert len(f.hits) > 0
+
+
+def test_metal_fills_exist():
+    from pytheory.rhythm import Pattern
+    for name in ["metal triplet", "metal blast", "metal cascade"]:
+        f = Pattern.fill(name)
+        assert f.beats == 4.0
+        assert len(f.hits) > 0
+
+
+# ── render_score in __all__ ──────────────────────────────────────────────
+
+def test_render_score_exported():
+    assert "render_score" in pytheory.__all__

uv.lock

@@ -486,14 +486,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d3/ac/686789b9145413f1a61878c407210e41bfdb097976864e0913078b24098c/myst_parser-5.0.0-py3-none-any.whl", hash = "sha256:ab31e516024918296e169139072b81592336f2fef55b8986aa31c9f04b5f7211", size = 84533, upload-time = "2026-01-15T09:08:16.788Z" },
 ]
 
-[[package]]
-name = "numeral"
-version = "0.1.0.17"
-source = { registry = "https://pypi.org/simple" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/17/0d/ac6a186e169fcbdfea316f78fb5e34981bcf8d5c1d7cc8b6581f597e1e4c/numeral-0.1.0.17-py2.py3-none-any.whl", hash = "sha256:7dff0c1efb9b3655c9c1dc93b4666993741b15abcac0dc01dcb96b21cc20f6ae", size = 22066, upload-time = "2020-04-12T08:24:59.129Z" },
-]
-
 [[package]]
 name = "numpy"
 version = "2.2.6"
@@ -698,10 +690,9 @@ wheels = [
 
 [[package]]
 name = "pytheory"
-version = "0.36.3"
+version = "0.39.3"
 source = { editable = "." }
 dependencies = [
-    { name = "numeral" },
     { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "sounddevice" },
@@ -721,7 +712,6 @@ docs = [
 
 [package.metadata]
 requires-dist = [
-    { name = "numeral" },
     { name = "scipy" },
     { name = "sounddevice" },
 ]