@ugfoundation/swaralipi-js 0.3.2 → 0.3.3

package/dist/player/index.d.cts

@@ -1,4 +1,4 @@
-import { S as Swaralipi, O as Octave, a as SvaraLetter, N as Note } from '../schema-D3wyNRqM.cjs';
+import { S as Swaralipi, T as Taal, O as Octave, a as SvaraLetter, N as Note } from '../schema-D3wyNRqM.cjs';
 import { T as TaalId } from '../taals-DxJ8wRtF.cjs';
 import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice } from '../schedule-CHXz3V6T.cjs';
 export { b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, d as INSTRUMENTS, P as PlayEvent, e as SALAMANDER_BASE, f as SAMPLED_TAALS, g as ScheduleOptions, T as TABLA_BPMS, h as TABLA_VARIATIONS, i as TONEJS_INSTRUMENTS_BASE, j as ToneModule, k as buildSchedule, l as drumPattern, m as instrumentSampleUrl, n as nearestTablaBpm, o as normalizeBase, p as probeUrl, q as quantizeLoopEnd, s as santoorUrls, r as subsetUrls, t as tablaBpms, u as tablaUrl } from '../schedule-CHXz3V6T.cjs';
@@ -48,6 +48,10 @@ interface PlayerOptions {
     onLimit?: () => void;
     /** Called with the active note's `part.row.note` path, or null when idle. */
     onHighlight?: (path: string | null) => void;
+    /** Taal mode only (`loadTaal`): called on the draw thread once per matra with
+     * the beat index within the cycle (0-based, `< numBeats`), so a consumer can
+     * highlight the active theka bol / drum-staff note. Never fired in doc mode. */
+    onBeat?: (beatInCycle: number) => void;
     /** Called on every state transition. */
     onState?: (state: PlayerState) => void;
 }
@@ -82,6 +86,15 @@ declare class SwaralipiPlayer {
     get usesTabla(): boolean;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
+    /**
+     * Taal mode: loop one avartan of a taal's theka (rhythm only, no melody) —
+     * for a standalone theka player. `play()` loops indefinitely (tabla loop /
+     * drum sequence) and fires `onBeat(beatInCycle)` once per matra on the draw
+     * thread so the consumer can highlight the active bol / drum-staff note. The
+     * taal's `id` should be a sampled taal (see `SAMPLED_TAALS`) for tabla audio;
+     * `variation` picks a tabla loop variation. Stops any current playback.
+     */
+    loadTaal(taal: Taal): void;
     /** Start (or resume) playback. Must be triggered from a user gesture so the
      * browser permits `AudioContext` resume. */
     play(): Promise<void>;

package/dist/player/index.d.ts

@@ -1,4 +1,4 @@
-import { S as Swaralipi, O as Octave, a as SvaraLetter, N as Note } from '../schema-D3wyNRqM.js';
+import { S as Swaralipi, T as Taal, O as Octave, a as SvaraLetter, N as Note } from '../schema-D3wyNRqM.js';
 import { T as TaalId } from '../taals-DxJ8wRtF.js';
 import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice } from '../schedule-BaE3JGHe.js';
 export { b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, d as INSTRUMENTS, P as PlayEvent, e as SALAMANDER_BASE, f as SAMPLED_TAALS, g as ScheduleOptions, T as TABLA_BPMS, h as TABLA_VARIATIONS, i as TONEJS_INSTRUMENTS_BASE, j as ToneModule, k as buildSchedule, l as drumPattern, m as instrumentSampleUrl, n as nearestTablaBpm, o as normalizeBase, p as probeUrl, q as quantizeLoopEnd, s as santoorUrls, r as subsetUrls, t as tablaBpms, u as tablaUrl } from '../schedule-BaE3JGHe.js';
@@ -48,6 +48,10 @@ interface PlayerOptions {
     onLimit?: () => void;
     /** Called with the active note's `part.row.note` path, or null when idle. */
     onHighlight?: (path: string | null) => void;
+    /** Taal mode only (`loadTaal`): called on the draw thread once per matra with
+     * the beat index within the cycle (0-based, `< numBeats`), so a consumer can
+     * highlight the active theka bol / drum-staff note. Never fired in doc mode. */
+    onBeat?: (beatInCycle: number) => void;
     /** Called on every state transition. */
     onState?: (state: PlayerState) => void;
 }
@@ -82,6 +86,15 @@ declare class SwaralipiPlayer {
     get usesTabla(): boolean;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
+    /**
+     * Taal mode: loop one avartan of a taal's theka (rhythm only, no melody) —
+     * for a standalone theka player. `play()` loops indefinitely (tabla loop /
+     * drum sequence) and fires `onBeat(beatInCycle)` once per matra on the draw
+     * thread so the consumer can highlight the active bol / drum-staff note. The
+     * taal's `id` should be a sampled taal (see `SAMPLED_TAALS`) for tabla audio;
+     * `variation` picks a tabla loop variation. Stops any current playback.
+     */
+    loadTaal(taal: Taal): void;
     /** Start (or resume) playback. Must be triggered from a user gesture so the
      * browser permits `AudioContext` resume. */
     play(): Promise<void>;

package/dist/player/index.js

@@ -22,6 +22,9 @@ var SwaralipiPlayer = class {
   /** Per-song setBpm tweak: beats meta.bpm but is cleared by the next load(). */
   #bpmTweak;
   #doc;
+  /** Taal mode (`loadTaal`): loops one avartan of this taal's theka with no
+   * melody. Mutually exclusive with `#doc`. */
+  #taal;
   #state = "idle";
   #tone;
   /** Master bus everything routes through, so stop() can fade it out. */
@@ -50,6 +53,7 @@ var SwaralipiPlayer = class {
       tanpura: options.tanpura ?? true,
       previewLimitSec: options.previewLimitSec ?? Infinity,
       onHighlight: options.onHighlight,
+      onBeat: options.onBeat,
       onState: options.onState,
       onLimit: options.onLimit
     };
@@ -89,6 +93,23 @@ var SwaralipiPlayer = class {
   load(doc) {
     this.#halt();
     this.#doc = doc;
+    this.#taal = void 0;
+    this.#taalOverride = void 0;
+    this.#bpmTweak = void 0;
+    this.#setState("ready");
+  }
+  /**
+   * Taal mode: loop one avartan of a taal's theka (rhythm only, no melody) —
+   * for a standalone theka player. `play()` loops indefinitely (tabla loop /
+   * drum sequence) and fires `onBeat(beatInCycle)` once per matra on the draw
+   * thread so the consumer can highlight the active bol / drum-staff note. The
+   * taal's `id` should be a sampled taal (see `SAMPLED_TAALS`) for tabla audio;
+   * `variation` picks a tabla loop variation. Stops any current playback.
+   */
+  loadTaal(taal) {
+    this.#halt();
+    this.#taal = taal;
+    this.#doc = void 0;
     this.#taalOverride = void 0;
     this.#bpmTweak = void 0;
     this.#setState("ready");
@@ -96,7 +117,7 @@ var SwaralipiPlayer = class {
   /** 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.#state === "playing") return;
+    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") {
@@ -144,7 +165,7 @@ var SwaralipiPlayer = class {
       this.#master.gain.cancelScheduledValues(now);
       this.#master.gain.rampTo(0, STOP_FADE_SEC, now);
       this.#emitHighlight(null);
-      this.#setState(this.#doc ? "ready" : "idle");
+      this.#setState(this.#doc || this.#taal ? "ready" : "idle");
       this.#cancelFadeTimer();
       this.#fadeTimer = setTimeout(() => this.#halt(), STOP_FADE_SEC * 1e3 + 60);
       return;
@@ -166,7 +187,7 @@ var SwaralipiPlayer = class {
     this.#restoreMasterGain();
     this.#scheduleIds = [];
     this.#emitHighlight(null);
-    if (this.#state !== "idle") this.#setState(this.#doc ? "ready" : "idle");
+    if (this.#state !== "idle") this.#setState(this.#doc || this.#taal ? "ready" : "idle");
   }
   #cancelFadeTimer() {
     if (this.#fadeTimer !== void 0) {
@@ -280,15 +301,16 @@ var SwaralipiPlayer = class {
   #emitHighlight(path) {
     this.#opts.onHighlight?.(path);
   }
-  /** The tabla variation to play: the doc's own (in auto mode), else none — an
-   * explicit setTaal override plays the taal's default variation. */
+  /** The tabla variation to play: taal-mode taal's, the doc's own (auto mode),
+   * else none — an explicit setTaal override plays the taal's default variation. */
   #variation() {
+    if (this.#taal !== void 0) return this.#taal.variation;
     return this.#taalAuto ? this.#doc?.meta.taal?.variation : void 0;
   }
-  /** Resolve the active taal: an explicit override, else the doc's. */
+  /** Resolve the active taal id: taal mode's taal, an explicit override, else
+   * the doc's — but only when it names a sampled taal. */
   #taalId() {
-    if (!this.#taalAuto && this.#taalOverride !== void 0) return this.#taalOverride;
-    const id = this.#doc?.meta.taal?.id;
+    const id = this.#taal?.id ?? (!this.#taalAuto && this.#taalOverride !== void 0 ? this.#taalOverride : this.#doc?.meta.taal?.id);
     return id !== void 0 && id in TAALS ? id : void 0;
   }
   /** Resolve an instrument id to its def (custom overrides built-ins; the
@@ -345,6 +367,7 @@ var SwaralipiPlayer = class {
   /** Build the melody instrument(s)/rhythm/drone for the current settings and
    * wait for their buffers, then schedule everything on the Transport. */
   async #arrange(Tone) {
+    if (this.#taal !== void 0) return this.#arrangeTaal(Tone);
     if (this.#doc === void 0) return;
     const base = this.#opts.soundsBaseUrl;
     const transport = Tone.getTransport();
@@ -390,6 +413,40 @@ var SwaralipiPlayer = class {
     }, schedule.totalBeats * spb);
     transport.scheduleOnce(() => this.stop(), endAt);
   }
+  /** Taal mode: loop one avartan forever (tabla loop / drum sequence via
+   * #buildRhythm), firing onBeat + a `String(beatInCycle)` highlight each matra
+   * on the draw thread. No melody, no tanpura, no auto-stop — it plays until
+   * stop(). */
+  async #arrangeTaal(Tone) {
+    if (this.#taal === void 0) return;
+    const base = this.#opts.soundsBaseUrl;
+    const transport = Tone.getTransport();
+    transport.cancel(0);
+    transport.position = 0;
+    this.#scheduleIds = [];
+    this.#ensureMaster(Tone);
+    this.#restoreMasterGain();
+    const bpm = this.#effectiveBpm();
+    transport.bpm.value = bpm;
+    const spb = 60 / bpm;
+    this.#buildRhythm(Tone, transport, base, spb);
+    await Tone.loaded();
+    if (this.#tabla?.buffer?.loaded) {
+      this.#tabla.loopEnd = quantizeLoopEnd(this.#tabla.buffer.duration, spb);
+    }
+    const draw = Tone.getDraw();
+    const n = Math.max(1, this.#taal.numBeats);
+    let beat = 0;
+    const id = transport.scheduleRepeat((time) => {
+      const b = beat % n;
+      draw.schedule(() => {
+        this.#emitHighlight(String(b));
+        this.#opts.onBeat?.(b);
+      }, time);
+      beat += 1;
+    }, spb, 0);
+    this.#scheduleIds.push(id);
+  }
   /** Build (or reuse) the melody sampler for `id`, loading only the samples
    * covering `range`. A cached sampler is reused while it still covers the
    * range; otherwise it's rebuilt (so changing songs/tonic widens it lazily). */
@@ -420,7 +477,7 @@ var SwaralipiPlayer = class {
     if (this.#opts.rhythm === "drums") {
       this.#drums ??= createDrumKit(Tone).connect(master);
       const drums = this.#drums;
-      const taal = taalId !== void 0 ? TAALS[taalId] : { numBeats: 4, sam: 0 };
+      const taal = this.#taal ?? (taalId !== void 0 ? TAALS[taalId] : { numBeats: 4, sam: 0 });
       const pattern = drumPattern(taal);
       let beat2 = 0;
       const id2 = transport.scheduleRepeat((time) => {
@@ -434,7 +491,7 @@ var SwaralipiPlayer = class {
     if (this.#opts.rhythm === "none" || base === void 0) return;
     this.#metronome ??= createMetronome(Tone, base).connect(master);
     const metro = this.#metronome;
-    const cycle = taalId !== void 0 ? TAALS[taalId].numBeats : 4;
+    const cycle = this.#taal?.numBeats ?? (taalId !== void 0 ? TAALS[taalId].numBeats : 4);
     let beat = 0;
     const id = transport.scheduleRepeat((time) => {
       metro.volume.setValueAtTime(beat % cycle === 0 ? 0 : -8, time);