@ugfoundation/swaralipi-js 0.7.4 → 0.7.6

package/dist/player/index.d.cts

@@ -48,6 +48,15 @@ interface PlayerOptions {
     onLimit?: () => void;
     /** Called with the active note's `part.row.note` path, or null when idle. */
     onHighlight?: (path: string | null) => void;
+    /** The same path, but fired on the AUDIO clock — Tone's worker ticker, the one
+     * that fires the notes themselves — so it keeps arriving while the page is
+     * hidden. `onHighlight` cannot: it runs on Tone.Draw, i.e.
+     * `requestAnimationFrame`, which stops the moment a screen locks, so anything
+     * hanging off it freezes until the reader looks at the page again. Use this for
+     * consumers that are not drawing (media-session metadata, analytics); it fires
+     * early — one transport lookahead (~0.1s) plus MEDIA_LEAD_SEC — and only in
+     * doc mode. */
+    onEvent?: (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. */
@@ -84,6 +93,19 @@ declare class SwaralipiPlayer {
     get taalId(): TaalId | undefined;
     /** Whether the effective rhythm will actually be a sampled tabla. */
     get usesTabla(): boolean;
+    /**
+     * Length of one play-through in seconds, for a progress bar (the OS media
+     * session's, typically). Derived from the loaded notation on every read and
+     * never stored, because every input can move: re-engrave the document, drag
+     * the tempo, switch the rhythm off, and this changes with it. `Infinity` in
+     * taal mode (one avartan looping, no end — the value the Media Session spec
+     * reserves for exactly that), 0 with nothing loaded, and clamped by a preview
+     * cap when one is set, since that is when playback will really stop.
+     */
+    get durationSec(): number;
+    /** 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(): number;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
     /**

package/dist/player/index.d.ts

@@ -48,6 +48,15 @@ interface PlayerOptions {
     onLimit?: () => void;
     /** Called with the active note's `part.row.note` path, or null when idle. */
     onHighlight?: (path: string | null) => void;
+    /** The same path, but fired on the AUDIO clock — Tone's worker ticker, the one
+     * that fires the notes themselves — so it keeps arriving while the page is
+     * hidden. `onHighlight` cannot: it runs on Tone.Draw, i.e.
+     * `requestAnimationFrame`, which stops the moment a screen locks, so anything
+     * hanging off it freezes until the reader looks at the page again. Use this for
+     * consumers that are not drawing (media-session metadata, analytics); it fires
+     * early — one transport lookahead (~0.1s) plus MEDIA_LEAD_SEC — and only in
+     * doc mode. */
+    onEvent?: (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. */
@@ -84,6 +93,19 @@ declare class SwaralipiPlayer {
     get taalId(): TaalId | undefined;
     /** Whether the effective rhythm will actually be a sampled tabla. */
     get usesTabla(): boolean;
+    /**
+     * Length of one play-through in seconds, for a progress bar (the OS media
+     * session's, typically). Derived from the loaded notation on every read and
+     * never stored, because every input can move: re-engrave the document, drag
+     * the tempo, switch the rhythm off, and this changes with it. `Infinity` in
+     * taal mode (one avartan looping, no end — the value the Media Session spec
+     * reserves for exactly that), 0 with nothing loaded, and clamped by a preview
+     * cap when one is set, since that is when playback will really stop.
+     */
+    get durationSec(): number;
+    /** 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(): number;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
     /**

package/dist/player/index.js

@@ -1,9 +1,10 @@
-import { DEFAULT_SOUNDS_BASE, INSTRUMENTS, SAMPLED_TAALS, instrumentSampleUrl, probeUrl, normalizeBase, nearestTablaBpm, tablaBpms, buildSchedule, quantizeLoopEnd, midiToSampleName, glideTargets, triggerGlide, createSampler, createBuffers, tablaUrl, tablaShiftSemitones, TABLA_GRAIN_OVERLAP_SEC, TABLA_GRAIN_SEC, createDrumKit, drumPattern, createMetronome, TANPURA_PCS, createTanpura, parseTonic, MEEND_HOLD, sCurve } from '../chunk-2SAZWTTK.js';
+import { DEFAULT_SOUNDS_BASE, INSTRUMENTS, SAMPLED_TAALS, buildSchedule, instrumentSampleUrl, probeUrl, normalizeBase, nearestTablaBpm, tablaBpms, quantizeLoopEnd, midiToSampleName, glideTargets, triggerGlide, createSampler, createBuffers, tablaUrl, tablaShiftSemitones, TABLA_GRAIN_OVERLAP_SEC, TABLA_GRAIN_SEC, createDrumKit, drumPattern, createMetronome, TANPURA_PCS, createTanpura, parseTonic, MEEND_HOLD, sCurve } from '../chunk-2SAZWTTK.js';
 export { ARC_RAW_RE, DEFAULT_SOUNDS_BASE, DRUM_KIT_BASE, INSTRUMENTS, MEEND_HOLD, OCTAVE_OFFSET, SALAMANDER_BASE, SAMPLED_TAALS, SHUDDHA, TABLA_BPMS, TABLA_VARIATIONS, TONEJS_INSTRUMENTS_BASE, buildSchedule, createBuffers, drumPattern, glideTargets, instrumentSampleUrl, isArcRaw, meendContinuations, midiToSampleName, nearestSampleKey, nearestTablaBpm, normalizeBase, parseTonic, probeUrl, quantizeLoopEnd, sCurve, sampleFileName, santoorUrls, subsetUrls, svaraSemitone, svaraToMidi, tablaBpms, tablaUrl, triggerGlide } from '../chunk-2SAZWTTK.js';
 import { TAALS } from '../chunk-UF5OSJRP.js';
 
 // src/player/player.ts
 var STOP_FADE_SEC = 0.5;
+var MEDIA_LEAD_SEC = 0.25;
 function midiRange(schedule) {
   let lo = Infinity;
   let hi = -Infinity;
@@ -17,6 +18,9 @@ function midiRange(schedule) {
   }
   return lo <= hi ? { lo, hi } : void 0;
 }
+function playDurationSec(schedule, spb, rhythm) {
+  return schedule.totalBeats * spb + (rhythm !== "none" ? schedule.pickupBeats * spb : 0) + spb;
+}
 async function loadedOrWarn(Tone) {
   try {
     await Tone.loaded();
@@ -63,6 +67,7 @@ var SwaralipiPlayer = class {
       tanpura: options.tanpura ?? true,
       previewLimitSec: options.previewLimitSec ?? Infinity,
       onHighlight: options.onHighlight,
+      onEvent: options.onEvent,
       onBeat: options.onBeat,
       onState: options.onState,
       onLimit: options.onLimit
@@ -96,6 +101,27 @@ var SwaralipiPlayer = class {
     const id = this.#taalId();
     return this.#opts.rhythm === "tabla" && id !== void 0 && SAMPLED_TAALS.has(id) && !!this.#opts.soundsBaseUrl;
   }
+  /**
+   * Length of one play-through in seconds, for a progress bar (the OS media
+   * session's, typically). Derived from the loaded notation on every read and
+   * never stored, because every input can move: re-engrave the document, drag
+   * the tempo, switch the rhythm off, and this changes with it. `Infinity` in
+   * taal mode (one avartan looping, no end — the value the Media Session spec
+   * reserves for exactly that), 0 with nothing loaded, and clamped by a preview
+   * cap when one is set, since that is when playback will really stop.
+   */
+  get durationSec() {
+    if (this.#taal !== void 0) return Infinity;
+    if (this.#doc === void 0) return 0;
+    const schedule = buildSchedule(this.#doc, { tonic: this.#opts.tonic, baseOctave: this.#opts.baseOctave });
+    const full = playDurationSec(schedule, 60 / this.#effectiveBpm(), this.#opts.rhythm);
+    return Math.min(full, this.#opts.previewLimitSec);
+  }
+  /** 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;
+  }
   /* ----------------------------------------------------------------- */
   /* Loading + transport control                                        */
   /* ----------------------------------------------------------------- */
@@ -408,6 +434,7 @@ var SwaralipiPlayer = class {
     }
     const draw = Tone.getDraw();
     const shift = this.#opts.rhythm !== "none" ? schedule.pickupBeats * spb : 0;
+    const mediaLead = Math.min(MEDIA_LEAD_SEC, spb);
     schedule.events.forEach((ev, i) => {
       const at = ev.beat * spb + shift;
       if (ev.midi !== null && ev.glide !== true) {
@@ -441,12 +468,14 @@ var SwaralipiPlayer = class {
           transport.scheduleOnce((time) => melody.triggerAttackRelease(name, dur, time), at);
         }
       }
-      transport.scheduleOnce((time) => {
-        draw.schedule(() => this.#emitHighlight(ev.path), time);
-      }, at);
+      if (this.#opts.onEvent !== void 0) {
+        transport.scheduleOnce(() => this.#opts.onEvent?.(ev.path), Math.max(at - mediaLead, 0));
+      }
+      transport.scheduleOnce((time) => draw.schedule(() => this.#emitHighlight(ev.path), time), at);
     });
-    const endAt = schedule.totalBeats * spb + shift + spb;
+    const endAt = playDurationSec(schedule, spb, this.#opts.rhythm);
     transport.scheduleOnce((time) => {
+      this.#opts.onEvent?.(null);
       draw.schedule(() => this.#emitHighlight(null), time);
     }, schedule.totalBeats * spb + shift);
     transport.scheduleOnce(() => this.stop(), endAt);