@ugfoundation/swaralipi-js 0.9.1 → 0.10.0

package/dist/player/index.js

@@ -1,15 +1,29 @@
-import { DEFAULT_SOUNDS_BASE, INSTRUMENTS, SAMPLED_TAALS, buildSchedule, quantizeLoopEnd, instrumentSampleUrl, probeUrl, normalizeBase, nearestTablaBpm, tablaBpms, graceTouches, midiToSampleName, glideTargets, triggerGlide, createSampler, createBuffers, tablaShiftSemitones, tablaUrl, TABLA_GRAIN_OVERLAP_SEC, TABLA_GRAIN_SEC, createDrumKit, drumPattern, createMetronome, TANPURA_PCS, createTanpura, parseTonic, GRACE_STEP, MEEND_HOLD, sCurve } from '../chunk-SEN266BY.js';
-export { ARC_RAW_RE, DEFAULT_SOUNDS_BASE, DRUM_KIT_BASE, GRACE_STEP, INSTRUMENTS, MEEND_HOLD, OCTAVE_OFFSET, SALAMANDER_BASE, SAMPLED_TAALS, SHUDDHA, TABLA_BPMS, TABLA_VARIATIONS, TONEJS_INSTRUMENTS_BASE, buildSchedule, createBuffers, drumPattern, glideTargets, graceTouches, instrumentSampleUrl, isArcRaw, meendContinuations, midiToSampleName, nearestSampleKey, nearestTablaBpm, normalizeBase, parseTonic, probeUrl, quantizeLoopEnd, sCurve, sampleFileName, santoorUrls, subsetUrls, svaraSemitone, svaraToMidi, tablaBpms, tablaUrl, triggerGlide } from '../chunk-SEN266BY.js';
+import { DEFAULT_SOUNDS_BASE, INSTRUMENTS, SAMPLED_TAALS, buildSchedule, eventAt, quantizeLoopEnd, instrumentSampleUrl, probeUrl, scheduleLines, GRACE_STEP, normalizeBase, nearestTablaBpm, tablaBpms, graceTouches, midiToSampleName, glideTargets, triggerGlide, createSampler, createBuffers, tablaShiftSemitones, tablaUrl, TABLA_GRAIN_OVERLAP_SEC, TABLA_GRAIN_SEC, createDrumKit, drumPattern, createMetronome, TANPURA_PCS, createTanpura, parseTonic, MEEND_HOLD, sCurve } from '../chunk-JEJYMKKZ.js';
+export { ARC_RAW_RE, DEFAULT_SOUNDS_BASE, DRUM_KIT_BASE, GRACE_STEP, INSTRUMENTS, MEEND_HOLD, OCTAVE_OFFSET, SALAMANDER_BASE, SAMPLED_TAALS, SHUDDHA, TABLA_BPMS, TABLA_VARIATIONS, TONEJS_INSTRUMENTS_BASE, buildSchedule, createBuffers, drumPattern, eventAt, glideTargets, graceTouches, instrumentSampleUrl, isArcRaw, meendContinuations, midiToSampleName, nearestSampleKey, nearestTablaBpm, normalizeBase, parseTonic, probeUrl, quantizeLoopEnd, sCurve, sampleFileName, santoorUrls, scheduleLines, subsetUrls, svaraSemitone, svaraToMidi, tablaBpms, tablaUrl, triggerGlide } from '../chunk-JEJYMKKZ.js';
 import { TAALS } from '../chunk-MYVIQU4O.js';
 export { LAYS, LAY_SPEEDS, printedLay, resolveLaySpeeds, rowLay } from '../chunk-MYVIQU4O.js';
 
 // src/player/player.ts
 var STOP_FADE_SEC = 0.5;
 var LAY_TAIL_SEC = 0.12;
+var START_PREROLL_SEC = 0.02;
 var TAAL_MODE_TEMPO = [
   { beat: 0, endBeat: Infinity, scale: 1, lay: "drut" }
 ];
 var MEDIA_LEAD_SEC = 0.25;
+function lineOf(lines, path) {
+  const [p = 0, r = 0] = path.split(".").map(Number);
+  const k = lines.findIndex((line) => {
+    const [lp = 0, lr = 0] = line.row.split(".").map(Number);
+    return lp > p || lp === p && lr >= r;
+  });
+  return k < 0 ? lines.length - 1 : k;
+}
+var seekableGrain = (Tone) => class extends Tone.GrainPlayer {
+  _start(time, offset, duration) {
+    super._start(time, offset === void 0 ? offset : this.toSeconds(offset) * this.playbackRate, duration);
+  }
+};
 function midiRange(schedule) {
   let lo = Infinity;
   let hi = -Infinity;
@@ -58,9 +72,28 @@ var SwaralipiPlayer = class {
    * `fileSpb` is the recorded loop's OWN beat length, which is the unit
    * `quantizeLoopEnd` must snap in (loop points are buffer time). */
   #tabla = [];
+  #grain;
   #drums;
   #scheduleIds = [];
   #fadeTimer;
+  /* Practice: where the playhead is, what repeats, whose turn it is. */
+  /** The last note played or sought — what "this line" means to the controls. */
+  #cursor = null;
+  /** Where the next fresh play() starts (a seek made while stopped). */
+  #startAt = null;
+  #loop = null;
+  #echo = false;
+  /** With echo on, every other pass is the learner's: the melody rests. */
+  #turn = false;
+  /** The arranged timeline, so a seek or a loop can be placed while playing. */
+  #timeline;
+  /** Listeners on the bound sheet, removed on rebind. */
+  #unbind;
+  #sheet;
+  /** Preview cap, counted in listening time so a seek or a loop can't dodge it. */
+  #listened = 0;
+  #listenedSince = 0;
+  #limitId;
   constructor(options = {}) {
     this.#opts = {
       soundsBaseUrl: options.soundsBaseUrl ?? DEFAULT_SOUNDS_BASE,
@@ -76,6 +109,7 @@ var SwaralipiPlayer = class {
       tanpura: options.tanpura ?? true,
       previewLimitSec: options.previewLimitSec ?? Infinity,
       onHighlight: options.onHighlight,
+      onLoop: options.onLoop,
       onEvent: options.onEvent,
       onBeat: options.onBeat,
       onState: options.onState,
@@ -128,7 +162,19 @@ var SwaralipiPlayer = class {
   /** Seconds played so far, off the Transport's own clock — so it holds while
    * paused, and reads 0 before the first play and after stop(). */
   get positionSec() {
-    return this.#tone?.getTransport().seconds ?? 0;
+    return Math.max(this.#tone?.getTransport().seconds ?? 0, 0);
+  }
+  /** The note last played or sought (`part.row.note`), or null. */
+  get cursor() {
+    return this.#cursor;
+  }
+  /** The repeated lines, or null. */
+  get loop() {
+    return this.#loop && { ...this.#loop };
+  }
+  /** Whether each repeat is followed by a silent pass for the learner. */
+  get echo() {
+    return this.#echo;
   }
   /* ----------------------------------------------------------------- */
   /* Loading + transport control                                        */
@@ -140,6 +186,7 @@ var SwaralipiPlayer = class {
     this.#taal = void 0;
     this.#taalOverride = void 0;
     this.#bpmTweak = void 0;
+    this.#resetPractice();
     this.#setState("ready");
   }
   /**
@@ -156,43 +203,137 @@ var SwaralipiPlayer = class {
     this.#doc = void 0;
     this.#taalOverride = void 0;
     this.#bpmTweak = void 0;
+    this.#resetPractice();
     this.#setState("ready");
   }
-  /** Start (or resume) playback. Must be triggered from a user gesture so the
-   * browser permits `AudioContext` resume. */
-  async play() {
-    if (this.#doc === void 0 && this.#taal === void 0 || this.#state === "playing") return;
-    const Tone = await this.#ensureTone();
-    await Tone.start();
-    if (this.#state === "paused") {
+  /** Start (or resume) playback — from `from` (`part.row.note`, or `part.row`
+   * for a line's start) when given, which also jumps there mid-play. Must be
+   * triggered from a user gesture so the browser permits `AudioContext`
+   * resume. */
+  async play(from) {
+    if (this.#doc === void 0 && this.#taal === void 0) return;
+    if (from !== void 0) this.seek(from);
+    if (this.#state === "playing" || this.#state === "loading") return;
+    const resume = this.#state === "paused";
+    if (!resume) this.#setState("loading");
+    let Tone;
+    try {
+      Tone = await this.#ensureTone();
+      await Tone.start();
+    } catch (err) {
+      if (!resume) this.#setState("ready");
+      throw err;
+    }
+    if (resume) {
       Tone.getTransport().start();
       this.#setState("playing");
+      this.#armLimit();
       return;
     }
     this.#cancelFade();
-    Tone.getTransport().stop();
-    this.#setState("loading");
+    const transport = Tone.getTransport();
+    if (transport.state !== "stopped") transport.stop();
     await this.#arrange(Tone);
-    Tone.getTransport().start();
+    transport.start(void 0, this.#startSec() - this.#preroll());
+    this.#startAt = null;
     this.#setState("playing");
-    const limit = this.#opts.previewLimitSec;
-    if (Number.isFinite(limit)) {
-      Tone.getTransport().scheduleOnce(() => {
-        Tone.getDraw().schedule(() => {
-          if (this.#state === "playing") {
-            this.stop();
-            this.#opts.onLimit?.();
-          }
-        }, this.#tone.now());
-      }, limit);
-    }
+    this.#armLimit();
   }
   /** Pause; `play()` resumes from the same position. */
   pause() {
     if (this.#tone === void 0 || this.#state !== "playing") return;
     this.#tone.getTransport().pause();
+    this.#disarmLimit();
     this.#setState("paused");
   }
+  /**
+   * Move the playhead to `path` (`part.row.note`, or `part.row` for a line's
+   * start). Playing, it jumps and keeps playing; paused or stopped, the next
+   * `play()` starts there. A repeat follows the playhead: seeking outside the
+   * repeated lines moves the repeat to the new line.
+   */
+  seek(path) {
+    const plan = this.#plan();
+    const i = plan === void 0 ? -1 : eventAt(plan.schedule.events, path);
+    if (plan === void 0 || i < 0) return;
+    const { lines } = plan;
+    const at = plan.schedule.events[i].path;
+    this.#cursor = at;
+    this.#turn = false;
+    const k = lineOf(lines, at);
+    const [a, b] = this.#loopSpan(lines);
+    if (this.#loop !== null && (k < a || k > b)) this.#loop = { from: lines[k].row, to: lines[k].row };
+    this.#emitLoop();
+    if (this.#timeline !== void 0 && (this.#state === "playing" || this.#state === "paused")) {
+      this.#applyLoop();
+      this.#jump(this.#eventSec(i));
+      if (this.#state === "paused") this.#emitHighlight(at);
+    } else {
+      this.#startAt = at;
+      this.#emitHighlight(at);
+    }
+  }
+  /**
+   * Repeat lines `from`..`to` (`part.row`, either order, inclusive; `to`
+   * defaults to `from`). With no argument, the line under the playhead.
+   * `null` stops repeating, and ends the sing-back with it. A playhead
+   * outside the new repeat moves to its start; live while playing.
+   */
+  setLoop(from, to) {
+    this.#turn = false;
+    if (from === null) {
+      this.#loop = null;
+      this.#echo = false;
+    } else {
+      const lines = this.#lines();
+      if (lines.length === 0) return;
+      const here = this.#cursor === null ? -1 : lineOf(lines, this.#cursor);
+      const a = from === void 0 ? Math.max(here, 0) : lineOf(lines, from);
+      const b = to === void 0 ? a : lineOf(lines, to);
+      this.#loop = { from: lines[Math.min(a, b)].row, to: lines[Math.max(a, b)].row };
+      if (here < Math.min(a, b) || here > Math.max(a, b)) return this.seek(this.#loop.from);
+    }
+    this.#applyLoop();
+    this.#emitLoop();
+  }
+  /**
+   * Follow every pass of the repeat with a silent one: the tabla and tanpura
+   * keep time and the highlight keeps moving, but the melody rests so the
+   * learner can sing the line back — the teacher sings, the student answers.
+   * Turning it on with nothing repeating repeats the current line.
+   */
+  setEcho(on) {
+    this.#echo = on;
+    this.#turn = false;
+    if (on && this.#loop === null) this.setLoop();
+    else this.#emitLoop();
+  }
+  /**
+   * Move by whole lines. Like a player's previous-track button, a step back
+   * from more than a matra into the line restarts that line first.
+   * `±Infinity` goes to the first / last line.
+   */
+  stepLine(delta) {
+    const plan = this.#plan();
+    if (plan === void 0 || plan.lines.length === 0) return;
+    const { lines, schedule } = plan;
+    const k = this.#cursor === null ? -1 : lineOf(lines, this.#cursor);
+    const into = k < 0 ? 0 : schedule.events[eventAt(schedule.events, this.#cursor)].beat - lines[k].beat;
+    const step = delta < 0 && this.#state === "playing" && into > 1 ? delta + 1 : delta;
+    this.seek(lines[Math.min(Math.max(k + step, 0), lines.length - 1)].row);
+  }
+  /** Move by single notes (rests and holds included — each is a column). */
+  stepNote(delta) {
+    const events = this.#plan()?.schedule.events ?? [];
+    let i = this.#cursor === null ? -1 : eventAt(events, this.#cursor);
+    for (let left = Math.abs(delta); left > 0; left--) {
+      do
+        i += Math.sign(delta);
+      while (events[i]?.glide === true);
+    }
+    const ev = events[Math.min(Math.max(i, 0), events.length - 1)];
+    if (ev !== void 0) this.seek(ev.path);
+  }
   /**
    * Stop and rewind to the start. When sounding, the accompaniment (tabla /
    * metronome / tanpura, which otherwise loop) is gently faded out over
@@ -200,6 +341,13 @@ var SwaralipiPlayer = class {
    * playing or cut abruptly; otherwise it halts immediately.
    */
   stop() {
+    this.#disarmLimit();
+    this.#listened = 0;
+    this.#startAt = null;
+    if (this.#turn) {
+      this.#turn = false;
+      this.#emitLoop();
+    }
     if (this.#tone === void 0 || this.#state === "idle") {
       this.#halt();
       return;
@@ -220,11 +368,15 @@ var SwaralipiPlayer = class {
    * looping accompaniment, restore the master gain for the next play. */
   #halt() {
     this.#cancelFadeTimer();
+    this.#disarmLimit();
+    this.#timeline = void 0;
+    this.#fence = 0;
     if (this.#tone !== void 0) {
       const transport = this.#tone.getTransport();
       transport.stop();
       transport.cancel(0);
       transport.position = 0;
+      transport.loop = false;
     }
     this.#disposeTabla();
     this.#restoreMasterGain();
@@ -255,6 +407,27 @@ var SwaralipiPlayer = class {
       if (loop.buffer?.loaded) loop.loopEnd = quantizeLoopEnd(loop.buffer.duration, fileSpb);
     }
   }
+  /** Count down whatever listening time the preview cap has left. On the
+   * audio clock, which keeps running while the page is hidden. */
+  #armLimit() {
+    const left = this.#opts.previewLimitSec - this.#listened;
+    const context = this.#tone?.getContext();
+    if (!Number.isFinite(left) || context === void 0) return;
+    this.#listenedSince = context.now();
+    this.#limitId = context.setTimeout(() => {
+      this.#limitId = void 0;
+      if (this.#state !== "playing") return;
+      this.stop();
+      this.#opts.onLimit?.();
+    }, Math.max(left, 0));
+  }
+  #disarmLimit() {
+    const context = this.#tone?.getContext();
+    if (this.#limitId === void 0 || context === void 0) return;
+    context.clearTimeout(this.#limitId);
+    this.#limitId = void 0;
+    this.#listened += context.now() - this.#listenedSince;
+  }
   #restoreMasterGain() {
     if (this.#master !== void 0 && this.#tone !== void 0) {
       this.#master.gain.cancelScheduledValues(this.#tone.now());
@@ -294,18 +467,81 @@ var SwaralipiPlayer = class {
     this.#taalAuto = id === null;
     this.#reapply();
   }
-  /** Wire highlight output to a `<swaralipi-sheet>` (or any highlight target).
-   * Pass `{ autoScroll }` to keep the active note in view while playing. */
+  /**
+   * Wire highlight output to a `<swaralipi-sheet>` (or any highlight target).
+   * Pass `{ autoScroll }` to keep the active note in view while playing.
+   *
+   * A sheet element also becomes the practice surface: a tap on a line plays
+   * from the note under it (Shift stretches the repeat to that line), and
+   * while it has focus — only then, so no key is taken from the page — Space
+   * plays/pauses, ↑/↓ move by line, ←/→ by note, Home/End jump to the first /
+   * last line, R repeats the line, T turns sing-back on/off, Esc stops the
+   * repeat and Shift+↑/↓ stretch it. To gate a tap-to-play (a play quota, say),
+   * `preventDefault()` its `swaralipi-seek` event in a capturing listener.
+   */
   bindSheet(target, opts = {}) {
     const block = opts.autoScroll === true ? "center" : opts.autoScroll || void 0;
-    this.#opts.onHighlight = (path) => {
+    this.#opts.onHighlight = (path, yourTurn) => {
       target.clearHighlights();
       if (path === null) return;
-      const el = target.highlight(path);
-      if (block !== void 0 && el !== null) {
-        el.scrollIntoView({ block, inline: "nearest", behavior: "smooth" });
+      const el2 = target.highlight(path, yourTurn);
+      if (block !== void 0 && el2 !== null) {
+        el2.scrollIntoView({ block, inline: "nearest", behavior: "smooth" });
       }
     };
+    this.#sheet = target;
+    target.markLoop?.(this.#loop, this.#turn);
+    this.#unbind?.abort();
+    if (!(target instanceof EventTarget)) return;
+    const el = target;
+    const { signal } = this.#unbind = new AbortController();
+    el.setAttribute("seekable", "");
+    signal.addEventListener("abort", () => el.removeAttribute("seekable"));
+    el.addEventListener("swaralipi-seek", (e) => this.#onTap(e), { signal });
+    el.addEventListener("keydown", (e) => this.#onKey(e), { signal });
+  }
+  #onTap(e) {
+    if (e.defaultPrevented) return;
+    if (e.detail.extend) this.#extendLoop(e.detail.path);
+    else void this.play(e.detail.path);
+  }
+  #onKey(e) {
+    if (e.ctrlKey || e.metaKey || e.altKey) return;
+    const shift = e.shiftKey;
+    const act = {
+      Space: () => this.#state === "playing" ? this.pause() : void this.play(),
+      ArrowUp: () => shift ? this.#extendBy(-1) : this.stepLine(-1),
+      ArrowDown: () => shift ? this.#extendBy(1) : this.stepLine(1),
+      ArrowLeft: () => this.stepNote(-1),
+      ArrowRight: () => this.stepNote(1),
+      Home: () => this.stepLine(-Infinity),
+      End: () => this.stepLine(Infinity),
+      KeyR: () => this.setLoop(this.#loop === null ? void 0 : null),
+      KeyT: () => this.setEcho(!this.#echo),
+      Escape: this.#loop === null ? void 0 : () => this.setLoop(null)
+    };
+    const run = act[e.code];
+    if (run === void 0) return;
+    e.preventDefault();
+    run();
+  }
+  /** Grow the repeat (or start one from the current line) to take in `path`'s line. */
+  #extendLoop(path) {
+    const lines = this.#lines();
+    if (lines.length === 0) return;
+    const k = lineOf(lines, path);
+    const here = this.#cursor === null ? k : lineOf(lines, this.#cursor);
+    const [a, b] = this.#loop === null ? [here, here] : this.#loopSpan(lines);
+    this.setLoop(lines[Math.min(a, k)].row, lines[Math.max(b, k)].row);
+  }
+  /** Shift+↑/↓: one more line above / below the repeat. */
+  #extendBy(delta) {
+    const lines = this.#lines();
+    if (lines.length === 0) return;
+    const here = this.#cursor === null ? 0 : lineOf(lines, this.#cursor);
+    const [a, b] = this.#loop === null ? [here, here] : this.#loopSpan(lines);
+    const k = Math.min(Math.max((delta < 0 ? a : b) + delta, 0), lines.length - 1);
+    this.#extendLoop(lines[k].row);
   }
   /**
    * Check whether an instrument's samples are reachable (its CDN is up / the
@@ -334,6 +570,8 @@ var SwaralipiPlayer = class {
   /** Release all audio resources. The instance is unusable afterward. */
   dispose() {
     this.#halt();
+    this.#unbind?.abort();
+    this.#tone?.getTransport().off("loop", this.#onPass);
     for (const { sampler } of this.#samplers.values()) sampler.dispose();
     this.#samplers.clear();
     for (const { buffers } of this.#glide.values()) buffers.dispose();
@@ -354,9 +592,110 @@ var SwaralipiPlayer = class {
     this.#state = state;
     this.#opts.onState?.(state);
   }
-  #emitHighlight(path) {
-    this.#opts.onHighlight?.(path);
+  #emitHighlight(path, yourTurn = false) {
+    this.#opts.onHighlight?.(path, yourTurn);
+  }
+  #emitLoop() {
+    this.#opts.onLoop?.({ loop: this.loop, echo: this.#echo, yourTurn: this.#turn });
+    this.#sheet?.markLoop?.(this.#loop, this.#turn);
+  }
+  /** A new document starts with nothing repeated, from the top. */
+  #resetPractice() {
+    this.#cursor = this.#startAt = this.#loop = null;
+    this.#echo = this.#turn = false;
+    this.#listened = 0;
+    this.#emitLoop();
+  }
+  /** The timeline to navigate: the arranged one while playing, else built
+   * fresh — it is pure and cheap, and a stopped player may have a new tonic
+   * or tempo since. */
+  #plan() {
+    if (this.#timeline !== void 0) return this.#timeline;
+    if (this.#doc === void 0) return void 0;
+    const schedule = buildSchedule(this.#doc, this.#scheduleOpts());
+    return { schedule, lines: scheduleLines(schedule) };
+  }
+  #lines() {
+    return this.#plan()?.lines ?? [];
+  }
+  /** The repeat as line indices (`[0, -1]`, i.e. empty, when off). */
+  #loopSpan(lines) {
+    return this.#loop === null ? [0, -1] : [lineOf(lines, this.#loop.from), lineOf(lines, this.#loop.to)];
   }
+  /** The repeat's lines on the arranged timeline, cached for the per-note
+   * checks (#hears), which run on every note. */
+  #loopLines = [0, -1];
+  /** Whether line `k` may sound: any line, unless a repeat holds others. */
+  #hears(k) {
+    return this.#loop === null || k >= this.#loopLines[0] && k <= this.#loopLines[1];
+  }
+  /** Transport seconds of event `i`, pulled back by its কণ so the grace is
+   * heard too. */
+  #eventSec(i) {
+    const { schedule, spb, shift } = this.#timeline;
+    const ev = schedule.events[i];
+    return Math.max((ev.beat - GRACE_STEP * ev.kan.length) * spb + shift, 0);
+  }
+  /** The repeat in transport seconds: from its first note's own start (its
+   * কণ included) for exactly the lines' length, so every pass keeps the
+   * tabla's phase. */
+  #loopSec() {
+    const { lines, spb } = this.#timeline;
+    const [a, b] = this.#loopLines;
+    const start = this.#eventSec(lines[a].first);
+    return [start, start + (lines[b].endBeat - lines[a].beat) * spb];
+  }
+  /** Put the repeat on the transport, or take it off. */
+  #applyLoop() {
+    const transport = this.#tone?.getTransport();
+    if (transport === void 0 || this.#timeline === void 0) return;
+    this.#loopLines = this.#loopSpan(this.#timeline.lines);
+    if (this.#loop === null) {
+      transport.loop = false;
+      return;
+    }
+    transport.setLoopPoints(...this.#loopSec());
+    transport.loop = true;
+  }
+  /** Where a fresh play() starts: a seek made while stopped, else the repeat,
+   * else the top. */
+  #startSec() {
+    const events = this.#timeline?.schedule.events ?? [];
+    if (this.#startAt !== null) return this.#eventSec(Math.max(eventAt(events, this.#startAt), 0));
+    return this.#loop === null ? 0 : this.#loopSec()[0];
+  }
+  /** Move the transport; notes still ringing from the old place are let go. */
+  #jump(sec) {
+    const Tone = this.#tone;
+    const transport = Tone.getTransport();
+    this.#fence = Tone.now();
+    if (transport.loop) {
+      transport.loopEnd = this.#loopSec()[1] + 3600;
+      Tone.getContext().setTimeout(() => this.#applyLoop(), 0.15);
+    }
+    transport.seconds = sec - this.#preroll();
+    this.#voice?.releaseAll();
+  }
+  /** Audio time before which a note callback belongs to the timeline a seek
+   * just left (see #jump). */
+  #fence = 0;
+  /** START_PREROLL_SEC in whole transport ticks: an offset between ticks
+   * would shift every later repeat wrap by the remainder — measured, a
+   * 0.8 ms splice in the tabla at each pass. */
+  #preroll() {
+    const transport = this.#tone.getTransport();
+    const perSec = transport.bpm.value / 60 * transport.PPQ;
+    return Math.ceil(START_PREROLL_SEC * perSec) / perSec;
+  }
+  /** The melody voice of the arrangement, for #jump. */
+  #voice;
+  /** The repeat wrapped. With sing-back on, the turn passes between the
+   * player and the learner; the sheet is told at the wrap itself. */
+  #onPass = (time) => {
+    if (this.#loop === null || !this.#echo) return;
+    this.#turn = !this.#turn;
+    this.#tone?.getDraw().schedule(() => this.#emitLoop(), time);
+  };
   /** The taal one accompaniment segment plays: taal mode's, an explicit
    * setTaal override (pinned across the whole song, তালফেরতা included), else
    * the segment's own. `null` = a মুক্তছন্দ passage. */
@@ -426,11 +765,13 @@ var SwaralipiPlayer = class {
     return this.#tone;
   }
   /** Hard stop → rebuild → restart, only while playing; otherwise just store.
-   * Uses #halt (not the stop() fade) so a setting change restarts instantly. */
+   * Uses #halt (not the stop() fade) so a setting change restarts instantly,
+   * from the note it was on — slowing down a repeated line keeps repeating it. */
   #reapply() {
     if (this.#state !== "playing") return;
+    const at = this.#cursor;
     this.#halt();
-    void this.play();
+    void this.play(at ?? void 0);
   }
   /** The master bus everything routes through (created once, → destination). */
   #ensureMaster(Tone) {
@@ -446,6 +787,7 @@ var SwaralipiPlayer = class {
     const transport = Tone.getTransport();
     transport.cancel(0);
     transport.position = 0;
+    transport.off("loop", this.#onPass).on("loop", this.#onPass);
     this.#scheduleIds = [];
     this.#ensureMaster(Tone);
     this.#restoreMasterGain();
@@ -453,24 +795,34 @@ var SwaralipiPlayer = class {
     transport.bpm.value = bpm;
     const spb = 60 / bpm;
     const schedule = buildSchedule(this.#doc, this.#scheduleOpts());
+    const lines = scheduleLines(schedule);
     const range = midiRange(schedule);
     const id = this.#effectiveInstrument();
     const def = this.#resolveDef(id) ?? INSTRUMENTS.harmonium;
     const melody = this.#buildMelody(Tone, id, base, range);
+    this.#voice = melody;
     const glide = schedule.events.some((ev) => ev.glide === true) ? this.#buildGlide(Tone, id, base, range) : void 0;
     const shift = this.#opts.rhythm !== "none" ? schedule.pickupBeats * spb : 0;
+    this.#timeline = { schedule, lines, spb, shift };
     this.#buildRhythm(Tone, transport, base, spb, schedule.tempo, shift);
     this.#buildTanpura(Tone, transport, base, spb, schedule.tempo, shift);
     await loadedOrWarn(Tone);
     this.#quantizeTablaLoops();
     const draw = Tone.getDraw();
     const mediaLead = Math.min(MEDIA_LEAD_SEC, spb);
+    let line = 0;
     schedule.events.forEach((ev, i) => {
+      while (lines[line + 1] !== void 0 && lines[line + 1].first <= i) line++;
+      const k = line;
+      const heard = (time) => time >= this.#fence && this.#hears(k);
+      const sounds = (time) => heard(time) && !this.#turn;
       const at = ev.beat * spb + shift;
       if (ev.glide !== true) {
         for (const g of graceTouches(ev)) {
           const graceName = midiToSampleName(g.midi);
-          transport.scheduleOnce((time) => melody.triggerAttackRelease(graceName, spb * 0.4, time), Math.max(g.beat * spb + shift, 0));
+          transport.schedule((time) => {
+            if (sounds(time)) melody.triggerAttackRelease(graceName, spb * 0.4, time);
+          }, Math.max(g.beat * spb + shift, 0));
         }
       }
       if (ev.midi !== null && ev.glide !== true) {
@@ -484,7 +836,8 @@ var SwaralipiPlayer = class {
             ...targets.map((t) => ({ midi: t.midi, at: (t.beat - ev.beat) * spb }))
           ];
           const end = (last.beat + last.durationBeats - ev.beat) * spb;
-          transport.scheduleOnce((time) => {
+          transport.schedule((time) => {
+            if (!sounds(time)) return;
             triggerGlide(
               Tone,
               glide.buffers,
@@ -496,14 +849,24 @@ var SwaralipiPlayer = class {
             );
           }, at);
         } else {
-          transport.scheduleOnce((time) => melody.triggerAttackRelease(name, dur, time), at);
+          transport.schedule((time) => {
+            if (sounds(time)) melody.triggerAttackRelease(name, dur, time);
+          }, at);
         }
       }
       if (this.#opts.onEvent !== void 0) {
-        transport.scheduleOnce(() => this.#opts.onEvent?.(ev.path), Math.max(at - mediaLead, 0));
+        transport.schedule((time) => {
+          if (heard(time)) this.#opts.onEvent?.(ev.path);
+        }, Math.max(at - mediaLead, 0));
       }
-      transport.scheduleOnce((time) => draw.schedule(() => this.#emitHighlight(ev.path), time), at);
+      transport.schedule((time) => {
+        if (!heard(time)) return;
+        const turn = this.#turn;
+        this.#cursor = ev.path;
+        draw.schedule(() => this.#emitHighlight(ev.path, turn), time);
+      }, at);
     });
+    this.#applyLoop();
     const endAt = playDurationSec(schedule, spb, this.#opts.rhythm);
     transport.scheduleOnce((time) => {
       this.#opts.onEvent?.(null);
@@ -595,13 +958,15 @@ var SwaralipiPlayer = class {
       const to = i === segments.length - 1 ? Infinity : seg.endBeat * spb + shift;
       const beatSec = spb / seg.scale;
       const span = to === Infinity ? void 0 : to - from;
+      const beatAt = (time) => Math.round((transport.getSecondsAtTime(time) - from) / beatSec);
       if (rhythm === "tabla" && taalId !== void 0 && SAMPLED_TAALS.has(taalId) && base !== void 0) {
         const bpm = 60 / beatSec;
         const fileBpm = nearestTablaBpm(bpm, tablaBpms(taalId));
         const rate = bpm / fileBpm;
         const semis = tablaShiftSemitones(this.#tonicSemitone());
         const url = tablaUrl(base, taalId, fileBpm, this.#variation(own));
-        const loop = (rate === 1 && semis === 0 ? new Tone.Player({ url, loop: true }) : new Tone.GrainPlayer({
+        this.#grain ??= seekableGrain(Tone);
+        const loop = (rate === 1 && semis === 0 ? new Tone.Player({ url, loop: true }) : new this.#grain({
           url,
           loop: true,
           playbackRate: rate,
@@ -612,9 +977,10 @@ var SwaralipiPlayer = class {
         loop.sync().start(from);
         if (span !== void 0) {
           this.#scheduleIds.push(
-            transport.scheduleOnce((t) => {
+            transport.schedule((t) => {
               loop.volume.setValueAtTime(0, t);
               loop.volume.linearRampToValueAtTime(-40, t + LAY_TAIL_SEC);
+              loop.volume.setValueAtTime(0, t + LAY_TAIL_SEC + 0.05);
             }, to)
           );
           loop.stop(to + LAY_TAIL_SEC);
@@ -626,13 +992,11 @@ var SwaralipiPlayer = class {
         this.#drums ??= createDrumKit(Tone).connect(master);
         const drums = this.#drums;
         const pattern = drumPattern(this.#taal ?? (taalId !== void 0 ? TAALS[taalId] : own) ?? { numBeats: 4, sam: 0 });
-        let beat2 = 0;
         this.#scheduleIds.push(
           transport.scheduleRepeat(
             (time) => {
-              const voice = pattern[beat2 % pattern.length];
+              const voice = pattern[beatAt(time) % pattern.length];
               if (drums.has(voice)) drums.player(voice).start(time);
-              beat2 += 1;
             },
             beatSec,
             from,
@@ -644,13 +1008,11 @@ var SwaralipiPlayer = class {
       this.#metronome ??= createMetronome(Tone, base).connect(master);
       const metro = this.#metronome;
       const cycle = (this.#taal ?? seg.taal)?.numBeats ?? 4;
-      let beat = 0;
       this.#scheduleIds.push(
         transport.scheduleRepeat(
           (time) => {
-            metro.volume.setValueAtTime(beat % cycle === 0 ? 0 : -8, time);
+            metro.volume.setValueAtTime(beatAt(time) % cycle === 0 ? 0 : -8, time);
             metro.start(time);
-            beat += 1;
           },
           beatSec,
           from,
@@ -676,15 +1038,14 @@ var SwaralipiPlayer = class {
     segments.forEach((seg, k) => {
       const from = k === 0 ? 0 : seg.beat * spb + shift;
       const to = k === segments.length - 1 ? Infinity : seg.endBeat * spb + shift;
-      let i = 0;
+      const every = spb * 2 / seg.scale;
       this.#scheduleIds.push(
         transport.scheduleRepeat(
           (time) => {
-            const stem = pattern[i % pattern.length];
+            const stem = pattern[Math.round((transport.getSecondsAtTime(time) - from) / every) % pattern.length];
             if (players.has(stem)) players.player(stem).start(time);
-            i += 1;
           },
-          spb * 2 / seg.scale,
+          every,
           from,
           to === Infinity ? void 0 : to - from
         )