@weasel-js/audio 1.7.0 → 1.7.2

package/dist/index.js

@@ -70,6 +70,33 @@ function createAnalyserTap(ctx, source, opts = {}) {
   };
 }
 
+// src/audioTime.ts
+var defaultTimers = {
+  setTimer: (cb, ms) => setTimeout(cb, ms),
+  clearTimer: (h) => clearTimeout(h)
+};
+function atAudioTime(ctx, timers, at, cb) {
+  let handle = null;
+  let live = true;
+  const check = () => {
+    handle = null;
+    if (!live) return;
+    const left = at - ctx.currentTime;
+    if (ctx.state === "running" && left > 1e-6) {
+      handle = timers.setTimer(check, Math.max(1, left * 1e3));
+      return;
+    }
+    live = false;
+    cb();
+  };
+  check();
+  return () => {
+    live = false;
+    if (handle !== null) timers.clearTimer(handle);
+    handle = null;
+  };
+}
+
 // src/param.ts
 function writeParam(ctx, param, value, rampMs) {
   const now = ctx.currentTime;
@@ -82,15 +109,224 @@ function writeParam(ctx, param, value, rampMs) {
   }
 }
 
+// src/inserts.ts
+function createInsertChain(ctx, head, tail, opts = {}) {
+  const fadeMs = opts.fadeMs ?? 15;
+  const timers = {
+    setTimer: opts.setTimer ?? defaultTimers.setTimer,
+    clearTimer: opts.clearTimer ?? defaultTimers.clearTimer
+  };
+  const used = /* @__PURE__ */ new WeakSet();
+  const order = [];
+  const live = [];
+  const links = [];
+  let busy = false;
+  let cancel = null;
+  let disposed = false;
+  let waiters = [];
+  const fade = () => ctx.state === "running" ? fadeMs : 0;
+  const link = (from, to, gain) => {
+    const g = ctx.createGain();
+    g.gain.value = gain;
+    writeParam(ctx, g.gain, gain);
+    from.connect(g);
+    g.connect(to);
+    const l = { from, to, gain: g };
+    links.push(l);
+    return l;
+  };
+  const unlink = (l) => {
+    l.from.disconnect(l.gain);
+    l.gain.disconnect();
+    links.splice(links.indexOf(l), 1);
+  };
+  const find = (from, to) => links.find((l) => l.from === from && l.to === to);
+  const inOf = (s) => s ? s.nodes.in : tail;
+  const outOf = (s) => s ? s.nodes.out : head;
+  const setBypass = (s, ms) => {
+    if (!s.nodes) return;
+    writeParam(ctx, s.nodes.wet.gain, s.bypassed ? 0 : 1, ms);
+    writeParam(ctx, s.nodes.dry.gain, s.bypassed ? 1 : 0, ms);
+  };
+  const build = (s) => {
+    if (s.nodes) return;
+    const n = {
+      in: ctx.createGain(),
+      out: ctx.createGain(),
+      dry: ctx.createGain(),
+      wet: ctx.createGain()
+    };
+    n.in.connect(s.effect.input);
+    s.effect.output.connect(n.wet);
+    n.wet.connect(n.out);
+    n.in.connect(n.dry);
+    n.dry.connect(n.out);
+    s.nodes = n;
+    n.wet.gain.value = s.bypassed ? 0 : 1;
+    n.dry.gain.value = s.bypassed ? 1 : 0;
+    setBypass(s, 0);
+  };
+  const destroy = (s) => {
+    const n = s.nodes;
+    if (!n) return;
+    n.in.disconnect();
+    try {
+      s.effect.output.disconnect(n.wet);
+    } catch {
+    }
+    n.wet.disconnect();
+    n.dry.disconnect();
+    n.out.disconnect();
+    s.nodes = null;
+  };
+  const plan = () => {
+    const stale = live.find((s) => s.removed);
+    if (stale) return { kind: "out", slot: stale };
+    const wanted = order.filter((s) => live.includes(s));
+    for (let i2 = 0; i2 < wanted.length; i2 += 1) {
+      if (live[i2] !== wanted[i2]) return { kind: "out", slot: wanted[i2] };
+    }
+    const i = order.findIndex((s) => !live.includes(s));
+    if (i < 0) return null;
+    let at = 0;
+    for (let j = i - 1; j >= 0; j -= 1) {
+      const k = live.indexOf(order[j]);
+      if (k >= 0) {
+        at = k + 1;
+        break;
+      }
+    }
+    return { kind: "in", slot: order[i], at };
+  };
+  const begin = (step, ms) => {
+    const s = step.slot;
+    if (step.kind === "in") {
+      build(s);
+      const prev2 = live[step.at - 1] ?? null;
+      const next2 = live[step.at] ?? null;
+      const old = find(outOf(prev2), inOf(next2));
+      link(outOf(prev2), inOf(s), 1);
+      const incoming = link(outOf(s), inOf(next2), 0);
+      live.splice(step.at, 0, s);
+      writeParam(ctx, old.gain.gain, 0, ms);
+      writeParam(ctx, incoming.gain.gain, 1, ms);
+      return () => unlink(old);
+    }
+    const i = live.indexOf(s);
+    const prev = live[i - 1] ?? null;
+    const next = live[i + 1] ?? null;
+    const into = find(outOf(prev), inOf(s));
+    const from = find(outOf(s), inOf(next));
+    const direct = link(outOf(prev), inOf(next), 0);
+    live.splice(i, 1);
+    writeParam(ctx, from.gain.gain, 0, ms);
+    writeParam(ctx, direct.gain.gain, 1, ms);
+    return () => {
+      unlink(into);
+      unlink(from);
+      if (s.removed) {
+        destroy(s);
+        s.effect.dispose?.();
+      }
+    };
+  };
+  const pump = () => {
+    while (!busy && !disposed) {
+      const step = plan();
+      if (!step) {
+        const done = waiters;
+        waiters = [];
+        for (const w of done) w();
+        return;
+      }
+      const ms = fade();
+      const finish = begin(step, ms);
+      if (ms === 0) {
+        finish();
+        continue;
+      }
+      busy = true;
+      cancel = atAudioTime(ctx, timers, ctx.currentTime + ms / 1e3, () => {
+        cancel = null;
+        busy = false;
+        finish();
+        pump();
+      });
+    }
+  };
+  link(head, tail, 1);
+  const slotOf = (effect, bypassed) => {
+    const s = { effect, bypassed, removed: false, nodes: null, handle: null };
+    s.handle = {
+      effect,
+      bypass(on) {
+        if (s.bypassed === on) return;
+        s.bypassed = on;
+        setBypass(s, fade());
+      },
+      bypassed: () => s.bypassed,
+      moveTo(index) {
+        const from = order.indexOf(s);
+        if (from < 0) return;
+        order.splice(from, 1);
+        order.splice(Math.max(0, Math.min(index, order.length)), 0, s);
+        pump();
+      },
+      remove() {
+        const at = order.indexOf(s);
+        if (at < 0) return;
+        order.splice(at, 1);
+        s.removed = true;
+        pump();
+      },
+      index: () => order.indexOf(s)
+    };
+    return s;
+  };
+  const chain = {
+    add(effect, addOpts = {}) {
+      if (used.has(effect)) {
+        throw new Error("@weasel-js/audio: that effect is already in an insert slot");
+      }
+      used.add(effect);
+      const s = slotOf(effect, addOpts.bypassed ?? false);
+      const index = addOpts.index ?? order.length;
+      order.splice(Math.max(0, Math.min(index, order.length)), 0, s);
+      pump();
+      return s.handle;
+    },
+    slots: () => order.map((s) => s.handle),
+    clear() {
+      for (const s of [...order]) s.handle.remove();
+    },
+    settled() {
+      if (!busy && plan() === null) return Promise.resolve();
+      return new Promise((resolve) => {
+        waiters.push(resolve);
+      });
+    }
+  };
+  return {
+    chain,
+    dispose() {
+      disposed = true;
+      cancel?.();
+      cancel = null;
+    }
+  };
+}
+
 // src/buses.ts
-function createBusGraph(ctx, names) {
+function createBusGraph(ctx, names, opts = {}) {
   const master = ctx.createGain();
   master.connect(ctx.destination);
   const states = /* @__PURE__ */ new Map();
   for (const name of names) {
+    const input = ctx.createGain();
     const node = ctx.createGain();
     node.connect(master);
-    states.set(name, { node, gain: 1, muted: false, soloed: false });
+    const inserts = createInsertChain(ctx, input, node, opts);
+    states.set(name, { input, node, inserts, gain: 1, muted: false, soloed: false });
   }
   const anySoloed = () => {
     for (const s of states.values()) if (s.soloed) return true;
@@ -111,8 +347,12 @@ function createBusGraph(ctx, names) {
   };
   return {
     master,
+    input: (name) => get(name).input,
     node: (name) => get(name).node,
     names: () => [...states.keys()],
+    dispose() {
+      for (const s of states.values()) s.inserts.dispose();
+    },
     bus(name) {
       const s = get(name);
       return {
@@ -131,7 +371,8 @@ function createBusGraph(ctx, names) {
         gain: () => s.gain,
         muted: () => s.muted,
         soloed: () => s.soloed,
-        audible: () => audibleUnder(s, anySoloed())
+        audible: () => audibleUnder(s, anySoloed()),
+        inserts: s.inserts.chain
       };
     }
   };
@@ -348,6 +589,212 @@ function createTickTimer() {
   };
 }
 
+// src/envelope.ts
+function resolveEnvelope(env = {}) {
+  return {
+    attack: Math.max(0, env.attack ?? 5),
+    decay: Math.max(0, env.decay ?? 0),
+    sustain: Math.min(1, Math.max(0, env.sustain ?? 1)),
+    release: Math.max(0, env.release ?? 30)
+  };
+}
+var heldLevel = (e, t) => {
+  if (t < e.attack) return t / e.attack;
+  if (t < e.attack + e.decay) return 1 - (1 - e.sustain) * (t - e.attack) / e.decay;
+  return e.sustain;
+};
+function envelopeLevel(e, t, gate) {
+  if (gate === void 0 || t <= gate) return heldLevel(e, t);
+  if (e.release === 0) return 0;
+  return Math.max(0, heldLevel(e, gate) * (1 - (t - gate) / e.release));
+}
+function envelopePoints(e, gate) {
+  const end = gate ?? Infinity;
+  const points = [{ at: 0, value: e.attack > 0 ? 0 : 1 }];
+  for (const at of [e.attack, e.attack + e.decay]) {
+    if (at <= points[points.length - 1].at) continue;
+    if (at >= end) break;
+    points.push({ at, value: heldLevel(e, at) });
+  }
+  if (gate === void 0) return points;
+  if (gate > points[points.length - 1].at) points.push({ at: gate, value: heldLevel(e, gate) });
+  points.push({ at: gate + e.release, value: 0 });
+  return points;
+}
+
+// src/pitch.ts
+function midiToFrequency(midi) {
+  return 440 * 2 ** ((midi - 69) / 12);
+}
+var LETTERS = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+function noteToMidi(name) {
+  const m = /^([A-Ga-g])([#b]*)(-?\d+)$/.exec(name.trim());
+  if (!m) throw new Error(`@weasel-js/audio: cannot read "${name}" as a note name`);
+  let semitone = LETTERS[m[1].toLowerCase()];
+  for (const acc of m[2]) semitone += acc === "#" ? 1 : -1;
+  return (Number(m[3]) + 1) * 12 + semitone;
+}
+function toFrequency(pitch) {
+  const hz = typeof pitch === "number" ? pitch : typeof pitch === "string" ? midiToFrequency(noteToMidi(pitch)) : midiToFrequency(pitch.midi);
+  if (!(hz > 0) || !Number.isFinite(hz)) {
+    throw new RangeError(`@weasel-js/audio: a pitch must be a positive frequency, got ${hz}`);
+  }
+  return hz;
+}
+
+// src/synthVoice.ts
+var NOISE_SECONDS = 2;
+var NOISE_RMS = 0.25;
+var noiseCache = /* @__PURE__ */ new WeakMap();
+function noiseSamples(color, length) {
+  const out = new Float32Array(length);
+  let s = 2654435769;
+  const white = () => {
+    s = Math.imul(s, 1664525) + 1013904223 >>> 0;
+    return s / 4294967296 * 2 - 1;
+  };
+  if (color === "white") {
+    for (let i = 0; i < length; i += 1) out[i] = white();
+  } else if (color === "pink") {
+    let b0 = 0, b1 = 0, b2 = 0, b3 = 0, b4 = 0, b5 = 0, b6 = 0;
+    for (let i = 0; i < length; i += 1) {
+      const w = white();
+      b0 = 0.99886 * b0 + w * 0.0555179;
+      b1 = 0.99332 * b1 + w * 0.0750759;
+      b2 = 0.969 * b2 + w * 0.153852;
+      b3 = 0.8665 * b3 + w * 0.3104856;
+      b4 = 0.55 * b4 + w * 0.5329522;
+      b5 = -0.7616 * b5 - w * 0.016898;
+      out[i] = b0 + b1 + b2 + b3 + b4 + b5 + b6 + w * 0.5362;
+      b6 = w * 0.115926;
+    }
+  } else {
+    let y = 0;
+    for (let i = 0; i < length; i += 1) {
+      y = (y + 0.02 * white()) / 1.02;
+      out[i] = y;
+    }
+  }
+  const step = (out[length - 1] - out[0]) / Math.max(1, length - 1);
+  let mean = 0;
+  for (let i = 0; i < length; i += 1) {
+    out[i] -= step * i;
+    mean += out[i];
+  }
+  mean /= length;
+  let sq = 0;
+  for (let i = 0; i < length; i += 1) {
+    out[i] -= mean;
+    sq += out[i] * out[i];
+  }
+  const scale = sq > 0 ? NOISE_RMS / Math.sqrt(sq / length) : 0;
+  for (let i = 0; i < length; i += 1) out[i] *= scale;
+  return out;
+}
+function noiseBuffer(ctx, color) {
+  let byColor = noiseCache.get(ctx);
+  if (!byColor) {
+    byColor = /* @__PURE__ */ new Map();
+    noiseCache.set(ctx, byColor);
+  }
+  let buffer = byColor.get(color);
+  if (!buffer) {
+    const length = Math.round(ctx.sampleRate * NOISE_SECONDS);
+    buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+    buffer.getChannelData(0).set(noiseSamples(color, length));
+    byColor.set(color, buffer);
+  }
+  return buffer;
+}
+var isInharmonic = (wave) => typeof wave === "object" && !Array.isArray(wave);
+function resolvePartials(wave) {
+  if (wave.partials.length === 0) {
+    throw new RangeError("@weasel-js/audio: an inharmonic wave needs at least one partial");
+  }
+  let total = 0;
+  for (const p of wave.partials) {
+    if (!(p.ratio > 0) || !Number.isFinite(p.ratio)) {
+      throw new RangeError(`@weasel-js/audio: partial ratio must be a positive number, got ${p.ratio}`);
+    }
+    if (p.decay !== void 0 && !(p.decay > 0)) {
+      throw new RangeError(`@weasel-js/audio: partial decay must be a positive number of ms, got ${p.decay}`);
+    }
+    total += Math.abs(p.gain ?? 1);
+  }
+  return wave.partials.map((p) => ({
+    ratio: p.ratio,
+    gain: total > 0 ? (p.gain ?? 1) / total : 0,
+    decay: p.decay
+  }));
+}
+function envelopeOnParam(param, env, gate, t0, map) {
+  const [first, ...rest] = envelopePoints(env, gate);
+  param.setValueAtTime(map(first.value), t0);
+  for (const p of rest) param.linearRampToValueAtTime(map(p.value), t0 + p.at / 1e3);
+  return {
+    release(at) {
+      const elapsed = Math.max(0, (at - t0) * 1e3);
+      param.cancelScheduledValues(at);
+      param.setValueAtTime(map(envelopeLevel(env, elapsed)), at);
+      param.linearRampToValueAtTime(map(0), at + env.release / 1e3);
+    }
+  };
+}
+function voiceFilter(ctx, spec, gate, t0) {
+  const node = ctx.createBiquadFilter();
+  node.type = spec.type ?? "lowpass";
+  node.Q.setValueAtTime(spec.Q ?? 1, t0);
+  if (spec.gain !== void 0) node.gain.setValueAtTime(spec.gain, t0);
+  const amount = spec.amount ?? 0;
+  if (!spec.envelope || amount === 0) {
+    node.frequency.setValueAtTime(spec.frequency, t0);
+    return { node, release: () => {
+    } };
+  }
+  const cutoff = envelopeOnParam(
+    node.frequency,
+    resolveEnvelope(spec.envelope),
+    gate,
+    t0,
+    (v) => spec.frequency + amount * v
+  );
+  return { node, release: cutoff.release };
+}
+var partialPresets = {
+  /** A church bell's hum, prime, tierce, quint and nominal, and above. */
+  bell: {
+    partials: [
+      { ratio: 0.5, gain: 0.6, decay: 1800 },
+      { ratio: 1, gain: 1, decay: 1200 },
+      { ratio: 1.183, gain: 0.7, decay: 900 },
+      { ratio: 1.506, gain: 0.4, decay: 700 },
+      { ratio: 2, gain: 0.8, decay: 600 },
+      { ratio: 2.514, gain: 0.3, decay: 400 },
+      { ratio: 2.662, gain: 0.25, decay: 350 },
+      { ratio: 3.011, gain: 0.2, decay: 300 }
+    ]
+  },
+  /** A tuned bar: its overtones sit near 4 and 10 times the fundamental and die fast. */
+  marimba: {
+    partials: [
+      { ratio: 1, gain: 1, decay: 350 },
+      { ratio: 3.984, gain: 0.35, decay: 90 },
+      { ratio: 9.95, gain: 0.12, decay: 30 }
+    ]
+  },
+  /** Struck sheet metal: modes nowhere near the harmonic series. */
+  metal: {
+    partials: [
+      { ratio: 1, gain: 1, decay: 160 },
+      { ratio: 1.71, gain: 0.53, decay: 120 },
+      { ratio: 2.43, gain: 0.36, decay: 94 },
+      { ratio: 3.19, gain: 0.27, decay: 78 },
+      { ratio: 4.61, gain: 0.22, decay: 66 },
+      { ratio: 5.87, gain: 0.18, decay: 58 }
+    ]
+  }
+};
+
 // src/voicePool.ts
 function createVoicePool(opts) {
   if (!(opts.limit >= 1)) {
@@ -398,6 +845,25 @@ function createVoicePool(opts) {
 }
 
 // src/createAudioEngine.ts
+var sourceGroup = (nodes) => ({
+  get onended() {
+    return nodes[0].onended;
+  },
+  set onended(fn) {
+    nodes[0].onended = fn;
+  },
+  stop(when) {
+    for (const n of nodes) {
+      try {
+        n.stop(when);
+      } catch {
+      }
+    }
+  },
+  disconnect() {
+    for (const n of nodes) n.disconnect();
+  }
+});
 function createAudioEngine(opts = {}) {
   const ctx = opts.context ?? new AudioContext();
   const ownsContext = opts.context === void 0;
@@ -405,7 +871,6 @@ function createAudioEngine(opts = {}) {
   if (busNames.length === 0) {
     throw new Error("@weasel-js/audio: an engine needs at least one bus");
   }
-  const graph = createBusGraph(ctx, busNames);
   const sounds = createSoundCache(ctx, opts.fetchFn);
   const slotsByBus = /* @__PURE__ */ new Map();
   for (const name of busNames) {
@@ -421,17 +886,22 @@ function createAudioEngine(opts = {}) {
   };
   const now = () => ctx.currentTime * 1e3;
   const tickTimer = opts.setTimer === void 0 && opts.clearTimer === void 0 ? createTickTimer() : null;
+  const timers = {
+    setTimer: tickTimer?.setTimer ?? opts.setTimer ?? defaultTimers.setTimer,
+    clearTimer: tickTimer?.clearTimer ?? opts.clearTimer ?? defaultTimers.clearTimer
+  };
   const scheduler = createScheduler({
     now,
     // One-shot, not repeating: the scheduler re-arms at the end of every pass,
     // so an interval would leave the previous one running and double the live
     // timer count per tick.
-    setTimer: tickTimer?.setTimer ?? opts.setTimer ?? ((cb, ms) => setTimeout(cb, ms)),
-    clearTimer: tickTimer?.clearTimer ?? opts.clearTimer ?? ((h) => clearTimeout(h)),
+    setTimer: timers.setTimer,
+    clearTimer: timers.clearTimer,
     lookahead: opts.lookahead,
     interval: opts.tickInterval
   });
   scheduler.start();
+  const graph = createBusGraph(ctx, busNames, { ...timers, fadeMs: opts.insertFadeMs });
   let listener = { x: 0, y: 0 };
   let spatialOpts = {};
   let nextVoiceId = 1;
@@ -524,6 +994,10 @@ function createAudioEngine(opts = {}) {
       voice.source.disconnect();
     }
     voice.source = null;
+    voice.retune = null;
+    voice.release = null;
+    voice.env?.disconnect();
+    voice.env = null;
     if (voice.chain) {
       voice.chain.gain.disconnect();
       if (idleChains.length < idleChainLimit) idleChains.push(voice.chain);
@@ -539,6 +1013,8 @@ function createAudioEngine(opts = {}) {
     id,
     stop: () => {
     },
+    release: () => {
+    },
     setGain: () => {
     },
     setRate: () => {
@@ -551,6 +1027,207 @@ function createAudioEngine(opts = {}) {
     },
     isPlaying: () => false
   });
+  const launch = (common, starter) => {
+    const id = nextVoiceId++;
+    if (disposed) {
+      warnDisposed();
+      return dropped(id);
+    }
+    if (ctx.state !== "running") {
+      warnLocked();
+      return dropped(id);
+    }
+    const busName = common.bus ?? busNames[0];
+    const slots = slotsFor(busName);
+    const bookedAt = now();
+    const when = common.when ?? bookedAt;
+    const baseGain = common.gain ?? 1;
+    const spatial = common.position ? spatialize(common.position, listener, spatialOpts) : { gain: 1, pan: common.pan ?? 0 };
+    const voice = {
+      id,
+      slots,
+      slot: null,
+      token: 0,
+      key: common.cancelKey,
+      source: null,
+      env: null,
+      retune: null,
+      release: null,
+      releasing: false,
+      chain: takeChain(graph.input(busName), baseGain * spatial.gain, spatial.pan),
+      baseGain,
+      spatialGain: spatial.gain,
+      rate: common.rate ?? 1,
+      detune: common.detune ?? 0,
+      position: common.position,
+      playing: true,
+      cancelled: false
+    };
+    live.set(id, voice);
+    scheduler.schedule(when, (scheduledWhen) => {
+      if (voice.cancelled) return;
+      if (bookedAt < staleFloor && scheduledWhen < staleFloor) {
+        teardown(voice);
+        return;
+      }
+      if (!starter.ready()) {
+        teardown(voice);
+        return;
+      }
+      const acquired = slots.pool.acquire({
+        startedAt: scheduledWhen,
+        gain: voice.baseGain * voice.spatialGain
+      });
+      voice.slot = acquired.slot;
+      voice.token = acquired.token;
+      slots.byToken.set(acquired.token, voice);
+      if (acquired.stolen !== null) {
+        const victim = slots.byToken.get(acquired.stolen);
+        if (victim) teardown(victim);
+      }
+      const source = starter.start(voice, scheduledWhen);
+      source.onended = () => {
+        teardown(voice);
+        common.onDone?.();
+      };
+      voice.source = source;
+    }, common.cancelKey);
+    return {
+      id,
+      stop(fadeMs) {
+        if (fadeMs && fadeMs > 0 && voice.source && voice.chain && !voice.cancelled) {
+          voice.cancelled = true;
+          writeParam(ctx, voice.chain.gain.gain, 0, fadeMs);
+          try {
+            voice.source.stop(ctx.currentTime + fadeMs / 1e3);
+          } catch {
+          }
+          return;
+        }
+        teardown(voice);
+      },
+      release() {
+        if (voice.releasing) return;
+        if (voice.release && voice.source && !voice.cancelled) {
+          voice.releasing = true;
+          voice.cancelled = true;
+          voice.release();
+          return;
+        }
+        teardown(voice);
+      },
+      setGain(value, rampMs) {
+        voice.baseGain = value;
+        if (!voice.chain) return;
+        writeParam(ctx, voice.chain.gain.gain, value * voice.spatialGain, rampMs);
+        poolGain(voice);
+      },
+      setRate(value) {
+        voice.rate = value;
+        voice.retune?.();
+      },
+      setDetune(cents) {
+        voice.detune = cents;
+        voice.retune?.();
+      },
+      setPan(value) {
+        voice.position = void 0;
+        if (voice.chain) voice.chain.panner.pan.value = value;
+      },
+      setPosition(p) {
+        voice.position = p;
+        applySpatial(voice);
+      },
+      isPlaying: () => voice.playing
+    };
+  };
+  const synthStart = (voice, whenMs, patch, make) => {
+    const t0 = whenMs / 1e3;
+    const env = resolveEnvelope(patch.envelope);
+    const gate = patch.duration;
+    const shaper = ctx.createGain();
+    const amp = envelopeOnParam(shaper.gain, env, gate, t0, (v) => v);
+    const filter = patch.filter ? voiceFilter(ctx, patch.filter, gate, t0) : null;
+    filter?.node.connect(shaper);
+    shaper.connect(voice.chain.panner);
+    voice.env = shaper;
+    const { nodes, retune } = make(t0, filter?.node ?? shaper);
+    voice.retune = retune;
+    retune();
+    const stopAll = (at) => {
+      for (const n of nodes) n.stop(at);
+    };
+    voice.release = () => {
+      const at = ctx.currentTime;
+      if (gate !== void 0 && at * 1e3 - whenMs >= gate) return;
+      amp.release(at);
+      filter?.release(at);
+      stopAll(at + env.release / 1e3);
+    };
+    if (gate !== void 0) stopAll(t0 + (gate + env.release) / 1e3);
+    return nodes.length === 1 ? nodes[0] : sourceGroup(nodes);
+  };
+  const waves = /* @__PURE__ */ new Map();
+  const applyWave = (osc, wave) => {
+    if (typeof wave === "string") {
+      osc.type = wave;
+      return;
+    }
+    const key = wave.join(",");
+    let periodic = waves.get(key);
+    if (!periodic) {
+      const imag = new Float32Array(wave.length + 1);
+      imag.set(wave, 1);
+      periodic = ctx.createPeriodicWave(new Float32Array(wave.length + 1), imag);
+      waves.set(key, periodic);
+    }
+    osc.setPeriodicWave(periodic);
+  };
+  const mediaSources = /* @__PURE__ */ new WeakMap();
+  const streaming = /* @__PURE__ */ new WeakMap();
+  const openMedia = (url, crossOrigin) => {
+    const el = new Audio();
+    if (crossOrigin !== void 0) el.crossOrigin = crossOrigin;
+    el.preload = "auto";
+    el.src = url;
+    return el;
+  };
+  const mediaSource = (el, node, into) => {
+    let ended = false;
+    let cancelWait = null;
+    const finish = () => {
+      if (ended) return;
+      ended = true;
+      cancelWait?.();
+      el.pause();
+      el.removeEventListener("ended", finish);
+      el.removeEventListener("error", finish);
+      queueMicrotask(() => shim.onended?.());
+    };
+    const shim = {
+      onended: null,
+      stop(when) {
+        if (ended) return;
+        cancelWait?.();
+        cancelWait = when !== void 0 && when > ctx.currentTime ? atAudioTime(ctx, timers, when, finish) : null;
+        if (!cancelWait) finish();
+      },
+      disconnect() {
+        try {
+          node.disconnect(into);
+        } catch {
+        }
+      }
+    };
+    el.addEventListener("ended", finish);
+    el.addEventListener("error", finish);
+    el.play().catch((err) => {
+      if (ended) return;
+      console.warn(`@weasel-js/audio: a stream would not start \u2014 ${String(err)}`);
+      finish();
+    });
+    return shim;
+  };
   const engine = {
     context: ctx,
     state: () => ctx.state,
@@ -564,112 +1241,119 @@ function createAudioEngine(opts = {}) {
     decode: sounds.decode,
     register: sounds.register,
     play(sound, playOpts = {}) {
-      const id = nextVoiceId++;
-      if (disposed) {
-        warnDisposed();
-        return dropped(id);
-      }
-      if (ctx.state !== "running") {
-        warnLocked();
-        return dropped(id);
-      }
-      const busName = playOpts.bus ?? busNames[0];
-      const slots = slotsFor(busName);
-      const bookedAt = now();
-      const when = playOpts.when ?? bookedAt;
-      const baseGain = playOpts.gain ?? 1;
-      const spatial = playOpts.position ? spatialize(playOpts.position, listener, spatialOpts) : { gain: 1, pan: playOpts.pan ?? 0 };
-      const voice = {
-        id,
-        slots,
-        slot: null,
-        token: 0,
-        key: playOpts.cancelKey,
-        source: null,
-        chain: takeChain(graph.node(busName), baseGain * spatial.gain, spatial.pan),
-        baseGain,
-        spatialGain: spatial.gain,
-        rate: playOpts.rate ?? 1,
-        detune: playOpts.detune ?? 0,
-        position: playOpts.position,
-        playing: true,
-        cancelled: false
-      };
-      live.set(id, voice);
-      scheduler.schedule(when, (scheduledWhen) => {
-        if (voice.cancelled) return;
-        if (bookedAt < staleFloor && scheduledWhen < staleFloor) {
-          teardown(voice);
-          return;
-        }
-        const buffer = sounds.buffer(sound);
-        if (!buffer) {
+      return launch(playOpts, {
+        ready() {
+          if (sounds.buffer(sound)) return true;
           warnUnknownSound(sound.id);
-          teardown(voice);
-          return;
-        }
-        const acquired = slots.pool.acquire({
-          startedAt: scheduledWhen,
-          gain: voice.baseGain * voice.spatialGain
-        });
-        voice.slot = acquired.slot;
-        voice.token = acquired.token;
-        slots.byToken.set(acquired.token, voice);
-        if (acquired.stolen !== null) {
-          const victim = slots.byToken.get(acquired.stolen);
-          if (victim) teardown(victim);
+          return false;
+        },
+        start(voice, when) {
+          const source = ctx.createBufferSource();
+          source.buffer = sounds.buffer(sound);
+          source.loop = playOpts.loop ?? false;
+          voice.retune = () => {
+            source.playbackRate.value = voice.rate;
+            source.detune.value = voice.detune;
+          };
+          voice.retune();
+          source.connect(voice.chain.panner);
+          source.start(when / 1e3);
+          return source;
         }
-        const source = ctx.createBufferSource();
-        source.buffer = buffer;
-        source.loop = playOpts.loop ?? false;
-        source.playbackRate.value = voice.rate;
-        source.detune.value = voice.detune;
-        source.connect(voice.chain.panner);
-        source.onended = () => {
-          teardown(voice);
-          playOpts.onDone?.();
-        };
-        voice.source = source;
-        source.start(scheduledWhen / 1e3);
-      }, playOpts.cancelKey);
-      return {
-        id,
-        stop(fadeMs) {
-          if (fadeMs && fadeMs > 0 && voice.source && voice.chain && !voice.cancelled) {
-            voice.cancelled = true;
-            writeParam(ctx, voice.chain.gain.gain, 0, fadeMs);
-            try {
-              voice.source.stop(ctx.currentTime + fadeMs / 1e3);
-            } catch {
+      });
+    },
+    playNote(note) {
+      const from = toFrequency(note.pitch);
+      const glideTo = note.glide ? toFrequency(note.glide.to) : void 0;
+      const wave = note.wave ?? "sine";
+      const partials = isInharmonic(wave) ? resolvePartials(wave) : null;
+      return launch(note, {
+        ready: () => true,
+        start: (voice, whenMs) => synthStart(voice, whenMs, note, (t0, into) => {
+          const tone = (ratio) => {
+            const osc = ctx.createOscillator();
+            osc.frequency.setValueAtTime(from * ratio, t0);
+            if (glideTo !== void 0) {
+              const end = t0 + (note.glide.ms ?? note.duration ?? 100) / 1e3;
+              if (note.glide.curve === "linear") osc.frequency.linearRampToValueAtTime(glideTo * ratio, end);
+              else osc.frequency.exponentialRampToValueAtTime(glideTo * ratio, end);
             }
-            return;
+            return osc;
+          };
+          let oscs;
+          if (partials) {
+            oscs = partials.map((p) => {
+              const osc = tone(p.ratio);
+              const level = ctx.createGain();
+              level.gain.setValueAtTime(p.gain, t0);
+              if (p.decay !== void 0) level.gain.setTargetAtTime(0, t0, p.decay / 1e3);
+              osc.connect(level);
+              level.connect(into);
+              return osc;
+            });
+          } else {
+            const osc = tone(1);
+            applyWave(osc, wave);
+            osc.connect(into);
+            oscs = [osc];
           }
-          teardown(voice);
-        },
-        setGain(value, rampMs) {
-          voice.baseGain = value;
-          if (!voice.chain) return;
-          writeParam(ctx, voice.chain.gain.gain, value * voice.spatialGain, rampMs);
-          poolGain(voice);
-        },
-        setRate(value) {
-          voice.rate = value;
-          if (voice.source) voice.source.playbackRate.value = value;
-        },
-        setDetune(cents) {
-          voice.detune = cents;
-          if (voice.source) voice.source.detune.value = cents;
-        },
-        setPan(value) {
-          voice.position = void 0;
-          if (voice.chain) voice.chain.panner.pan.value = value;
-        },
-        setPosition(p) {
-          voice.position = p;
-          applySpatial(voice);
-        },
-        isPlaying: () => voice.playing
-      };
+          for (const osc of oscs) osc.start(t0);
+          return {
+            nodes: oscs,
+            retune: () => {
+              for (const osc of oscs) osc.detune.value = voice.detune + 1200 * Math.log2(voice.rate);
+            }
+          };
+        })
+      });
+    },
+    playNoise(noise) {
+      return launch(noise, {
+        ready: () => true,
+        start: (voice, whenMs) => synthStart(voice, whenMs, noise, (t0, into) => {
+          const source = ctx.createBufferSource();
+          source.buffer = noiseBuffer(ctx, noise.noise);
+          source.loop = true;
+          source.connect(into);
+          source.start(t0, Math.random() * source.buffer.duration);
+          return {
+            nodes: [source],
+            retune: () => {
+              source.playbackRate.value = voice.rate;
+              source.detune.value = voice.detune;
+            }
+          };
+        })
+      });
+    },
+    stream(media, streamOpts = {}) {
+      const el = typeof media === "string" ? openMedia(media, streamOpts.crossOrigin) : media;
+      streaming.get(el)?.stop();
+      const handle = launch(streamOpts, {
+        ready: () => true,
+        start(voice) {
+          let node = mediaSources.get(el);
+          if (!node) {
+            node = ctx.createMediaElementSource(el);
+            mediaSources.set(el, node);
+          }
+          el.loop = streamOpts.loop ?? false;
+          if (streamOpts.offset !== void 0) el.currentTime = streamOpts.offset / 1e3;
+          voice.retune = () => {
+            el.playbackRate = voice.rate;
+          };
+          voice.retune();
+          const into = voice.chain.panner;
+          node.connect(into);
+          return mediaSource(el, node, into);
+        }
+      });
+      streaming.set(el, handle);
+      return handle;
+    },
+    schedule(when, fire, key) {
+      if (disposed) return;
+      scheduler.schedule(when, fire, key);
     },
     stopKey(key) {
       scheduler.cancelKey(key);
@@ -716,6 +1400,7 @@ function createAudioEngine(opts = {}) {
       taps.clear();
       disarmGestures();
       ctx.removeEventListener("statechange", onStateChange);
+      graph.dispose();
       graph.master.disconnect();
       if (ownsContext) void ctx.close().catch(() => void 0);
     }
@@ -723,6 +1408,207 @@ function createAudioEngine(opts = {}) {
   return engine;
 }
 
-export { createAnalyserTap, createAudioEngine, createBusGraph, createScheduler, createSoundCache, createTickTimer, createVoicePool, spatialize };
+// src/effects.ts
+function createFilterEffect(ctx, opts = {}) {
+  const filter = ctx.createBiquadFilter();
+  filter.type = opts.type ?? "lowpass";
+  if (opts.frequency !== void 0) writeParam(ctx, filter.frequency, opts.frequency);
+  if (opts.Q !== void 0) writeParam(ctx, filter.Q, opts.Q);
+  if (opts.gain !== void 0) writeParam(ctx, filter.gain, opts.gain);
+  return { input: filter, output: filter, filter };
+}
+var checkMix = (mix) => {
+  if (!(mix >= 0 && mix <= 1)) throw new RangeError(`@weasel-js/audio: mix ${mix} is outside 0..1`);
+  return mix;
+};
+function wetDry(ctx, wetIn, wetOut, initial) {
+  const input = ctx.createGain();
+  const output = ctx.createGain();
+  const dry = ctx.createGain();
+  const wet = ctx.createGain();
+  input.connect(dry);
+  dry.connect(output);
+  input.connect(wetIn);
+  wetOut.connect(wet);
+  wet.connect(output);
+  let mix = checkMix(initial);
+  const write = (rampMs) => {
+    writeParam(ctx, dry.gain, 1 - mix, rampMs);
+    writeParam(ctx, wet.gain, mix, rampMs);
+  };
+  write();
+  return {
+    input,
+    output,
+    mix: () => mix,
+    setMix(value, rampMs) {
+      mix = checkMix(value);
+      write(rampMs);
+    }
+  };
+}
+function createReverbEffect(ctx, opts) {
+  const convolver = ctx.createConvolver();
+  convolver.normalize = opts.normalize ?? true;
+  convolver.buffer = opts.impulse;
+  const m = wetDry(ctx, convolver, convolver, opts.mix ?? 0.3);
+  return { input: m.input, output: m.output, convolver, mix: m.mix, setMix: m.setMix };
+}
+var checkFeedback = (value) => {
+  if (!(value > -1 && value < 1)) {
+    throw new RangeError(`@weasel-js/audio: feedback ${value} must be inside -1..1, or the repeats grow`);
+  }
+  return value;
+};
+function createDelayEffect(ctx, opts = {}) {
+  const time = opts.time ?? 250;
+  const maxTime = opts.maxTime ?? Math.max(1e3, time);
+  let fb = checkFeedback(opts.feedback ?? 0.35);
+  const delay = ctx.createDelay(maxTime / 1e3);
+  const loop = ctx.createGain();
+  const m = wetDry(ctx, delay, delay, opts.mix ?? 0.35);
+  delay.connect(loop);
+  loop.connect(delay);
+  writeParam(ctx, delay.delayTime, time / 1e3);
+  writeParam(ctx, loop.gain, fb);
+  return {
+    input: m.input,
+    output: m.output,
+    delay,
+    mix: m.mix,
+    setMix: m.setMix,
+    setTime(ms, rampMs) {
+      if (!(ms >= 0 && ms <= maxTime)) {
+        throw new RangeError(`@weasel-js/audio: delay time ${ms} is outside 0..${maxTime} ms`);
+      }
+      writeParam(ctx, delay.delayTime, ms / 1e3, rampMs);
+    },
+    feedback: () => fb,
+    setFeedback(value, rampMs) {
+      fb = checkFeedback(value);
+      writeParam(ctx, loop.gain, fb, rampMs);
+    },
+    dispose() {
+      delay.disconnect();
+      loop.disconnect();
+    }
+  };
+}
+function createCompressorEffect(ctx, opts = {}) {
+  const compressor = ctx.createDynamicsCompressor();
+  const makeup = ctx.createGain();
+  compressor.connect(makeup);
+  const set = (param, value) => {
+    if (value !== void 0) writeParam(ctx, param, value);
+  };
+  set(compressor.threshold, opts.threshold);
+  set(compressor.knee, opts.knee);
+  set(compressor.ratio, opts.ratio);
+  set(compressor.attack, opts.attack === void 0 ? void 0 : opts.attack / 1e3);
+  set(compressor.release, opts.release === void 0 ? void 0 : opts.release / 1e3);
+  set(makeup.gain, opts.makeup ?? 1);
+  return { input: compressor, output: makeup, compressor, makeup };
+}
+
+// src/patternPlayer.ts
+var nextPlayer = 1;
+var checkTempo = (bpm) => {
+  if (!(bpm > 0) || !Number.isFinite(bpm)) {
+    throw new RangeError(`@weasel-js/audio: tempo must be a positive number of bpm, got ${bpm}`);
+  }
+};
+function createPatternPlayer(engine, opts) {
+  checkTempo(opts.tempo);
+  const stepsPerBeat = opts.stepsPerBeat ?? 4;
+  const loop = opts.loop ?? true;
+  const key = `\0pattern:${nextPlayer++}`;
+  let bpm = opts.tempo;
+  let length = 1;
+  let byStep = /* @__PURE__ */ new Map();
+  const setEvents = (events, len) => {
+    byStep = /* @__PURE__ */ new Map();
+    let last = -1;
+    for (const e of events) {
+      const list = byStep.get(e.step);
+      if (list) list.push(e);
+      else byStep.set(e.step, [e]);
+      last = Math.max(last, e.step);
+    }
+    length = len ?? Math.max(1, Math.ceil((last + 1) / stepsPerBeat)) * stepsPerBeat;
+  };
+  setEvents(opts.events ?? [], opts.length);
+  let running = false;
+  let count = 0;
+  let lastAt = null;
+  let nextAt = 0;
+  const voices = /* @__PURE__ */ new Set();
+  const stepMs = () => 6e4 / bpm / stepsPerBeat;
+  const book = () => {
+    engine.schedule(nextAt, fire, key);
+  };
+  const fire = (scheduled) => {
+    if (!running) return;
+    let when = scheduled;
+    const behind = engine.now() - when;
+    if (behind > stepMs()) {
+      const skip = Math.ceil(behind / stepMs());
+      count += skip;
+      when += skip * stepMs();
+    }
+    if (!loop && count >= length) {
+      running = false;
+      return;
+    }
+    const step = count % length;
+    for (const v of voices) if (!v.isPlaying()) voices.delete(v);
+    for (const e of byStep.get(step) ?? []) {
+      if ("sound" in e) {
+        const { step: _s, sound, ...play } = e;
+        voices.add(engine.play(sound, { ...play, when }));
+      } else if ("noise" in e) {
+        const { step: _s, length: steps = 1, ...noise } = e;
+        voices.add(engine.playNoise({ ...noise, when, duration: steps * stepMs() }));
+      } else {
+        const { step: _s, length: steps = 1, ...note } = e;
+        voices.add(engine.playNote({ ...note, when, duration: steps * stepMs() }));
+      }
+    }
+    opts.onStep?.(step, when);
+    count += 1;
+    lastAt = when;
+    nextAt = when + stepMs();
+    book();
+  };
+  return {
+    start(when) {
+      if (running) return;
+      running = true;
+      count = 0;
+      lastAt = null;
+      nextAt = when ?? engine.now();
+      book();
+    },
+    stop() {
+      if (!running) return;
+      running = false;
+      engine.stopKey(key);
+      for (const v of voices) v.release();
+      voices.clear();
+    },
+    playing: () => running,
+    tempo: () => bpm,
+    setTempo(next) {
+      checkTempo(next);
+      bpm = next;
+      if (!running || lastAt === null) return;
+      engine.stopKey(key);
+      nextAt = Math.max(lastAt + stepMs(), engine.now());
+      book();
+    },
+    setEvents
+  };
+}
+
+export { createAnalyserTap, createAudioEngine, createBusGraph, createCompressorEffect, createDelayEffect, createFilterEffect, createPatternPlayer, createReverbEffect, createScheduler, createSoundCache, createTickTimer, createVoicePool, envelopeLevel, envelopePoints, midiToFrequency, noiseSamples, noteToMidi, partialPresets, resolveEnvelope, spatialize, toFrequency };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map