@ugfoundation/swaralipi-js 0.13.1 → 0.14.1

package/dist/{schedule-ClyON98C.d.ts → instruments-NcUb0ozc.d.ts}

@@ -1,143 +1,6 @@
-import * as tone from 'tone';
 import { T as Taal, S as Swaralipi, N as Note } from './schema-DZag9qkF.js';
-import { T as TaalId, L as Lay, a as LaySpeeds } from './lay-CWlEhImP.js';
-
-/** The dynamically-imported Tone module, typed without importing it. */
-type ToneModule = typeof tone;
-/** A melodic instrument: a Tone.Sampler note→filename map + where to find it. */
-interface InstrumentDef {
-    /** Human label for UIs. */
-    label: string;
-    /** Tone.Sampler `urls`: note name (`C#4`) → filename (`Cs4.mp3`). */
-    urls: Record<string, string>;
-    /** Sample directory: an absolute URL, or — when `local` — a path segment
-     * appended to the player's `soundsBaseUrl`. */
-    baseUrl: string;
-    /** `baseUrl` is relative to `soundsBaseUrl` (needs it set). */
-    local?: boolean;
-    /** Sampler release time in seconds. */
-    release?: number;
-}
-/** Built-in melody instrument ids (consumers may add their own via the
- * player's `customInstruments`, so the runtime id type stays open). */
-type InstrumentId = string;
-/**
- * Default host for the project's samples (santoor / tabla / tanpura /
- * metronome) — CORS-enabled, so the player works with zero config. Override via
- * the player's `soundsBaseUrl` to self-host. (Melody defaults to the CDN-hosted
- * piano, so it needs no host.) Licences: see THIRD-PARTY.md.
- */
-declare const DEFAULT_SOUNDS_BASE = "https://bitoron.pages.dev/audio/instruments/";
-/** CC-BY Salamander Grand Piano (Tone's de-facto piano), CDN-hosted. */
-declare const SALAMANDER_BASE = "https://tonejs.github.io/audio/salamander/";
-/** CC-BY tonejs-instruments sample CDN (harmonium/violin/flute). */
-declare const TONEJS_INSTRUMENTS_BASE = "https://nbrosowsky.github.io/tonejs-instruments/samples/";
-/** Built-in melody instruments. santoor is local; the rest are CDN-hosted
- * (CC-BY) so they need only network — `pianoBaseUrl`/`customInstruments`
- * override for self-hosting. */
-declare const INSTRUMENTS: Record<string, InstrumentDef>;
-/** Taals with recorded tabla loops (everything else → metronome fallback). */
-declare const SAMPLED_TAALS: ReadonlySet<TaalId>;
-/** Available tabla loop tempos (file suffix `…<bpm>bpm.mp3`). */
-declare const TABLA_BPMS: readonly number[];
-/**
- * Tabla loop variations per taal. Most taals have one unnamed loop at
- * `tabla/<id>/`; an entry here overrides that:
- *  - `variations` lists the variation suffixes, **first = default**.
- *    A lone named variation (shashthi → `pro`, i.e. `tabla/shashthi-pro/`) IS
- *    the default; later entries are premium upsells the player never auto-selects.
- *    An empty-string entry (kehrwa → `''`) means the unnamed `tabla/<id>/` loop
- *    is the default and a named entry follows it as an upsell.
- *  - `skipBpms` are grid tempos this taal's loops were not recorded at.
- * Consumers read this to build a variation/upsell UI; the player itself only
- * ever plays the default (or whatever a doc's `meta.taal.variation` pins).
- */
-declare const TABLA_VARIATIONS: Record<string, {
-    variations: string[];
-    skipBpms?: number[];
-}>;
-/** Tabla tempos actually available for a taal: the grid minus any it lacks. */
-declare function tablaBpms(taalId: string): readonly number[];
-/** Ensure exactly one trailing slash. */
-declare function normalizeBase(url: string): string;
-/** The 37 santoor samples, as a Tone.Sampler `urls` map (`C4` → `c4.mp3`). */
-declare function santoorUrls(): Record<string, string>;
-/**
- * Restrict a Sampler `urls` map to just the samples needed to cover MIDI
- * `[lo, hi]`: every sample inside the range, plus the nearest one below and
- * above it (so Tone interpolates the edges without extrapolating). Cuts a
- * typical song from ~37 santoor files to a handful — a big win on mobile and
- * never worse on fast links (Tone fetches what's left in parallel). The
- * Sampler pitch-shifts from the nearest sample, so audio is unchanged.
- */
-declare function subsetUrls(urls: Record<string, string>, lo: number, hi: number): Record<string, string>;
-/** Resolve a representative sample URL for an instrument (its first sample),
- * used to probe availability. undefined when a local instrument has no
- * `soundsBaseUrl` or the def has no samples. */
-declare function instrumentSampleUrl(def: InstrumentDef, soundsBaseUrl?: string): string | undefined;
-/**
- * Liveness check for a sample URL: a single tiny ranged GET (one byte), the
- * same CORS-enabled fetch Tone uses to load the buffer — so a pass means Tone
- * can actually load it. Resolves false on any error/timeout/non-2xx, and false
- * (no throw) when `fetch` is unavailable (Node/SSR). `Range: bytes=0-0` is a
- * CORS-safelisted header, so no preflight.
- */
-declare function probeUrl(url: string, timeoutMs?: number): Promise<boolean>;
-/**
- * Snap a tabla loop's end to the nearest whole beat of its measured length so a
- * slightly-mistrimmed file still phase-locks to the melody grid instead of
- * drifting a fraction of a beat each cycle. `spb` = seconds per beat (60/bpm).
- * No-op for correctly trimmed loops (already an integer beat count); never
- * extends past the buffer — a too-short file can't be repaired here.
- *
- * ponytail: belt-and-braces for off-spec audio; the real fix is trimming each
- * loop to exactly `cycles × numBeats × 60/bpm` seconds at production time.
- */
-declare function quantizeLoopEnd(durationSec: number, spb: number): number;
-/** Snap an arbitrary bpm to the nearest available tabla tempo (default grid;
- * pass a taal's `tablaBpms()` so it never snaps to a tempo that taal lacks). */
-declare function nearestTablaBpm(bpm: number, bpms?: readonly number[]): number;
-/** URL of the tabla loop for a taal at a (snapped) bpm, optionally a named
- * variation (defaults to the taal's default variation — see TABLA_VARIATIONS). */
-declare function tablaUrl(base: string, taalId: string, bpm: number, variation?: string): string;
-declare const DRUM_KIT_BASE = "https://tonejs.github.io/audio/drum-samples/acoustic-kit/";
-type DrumVoice = 'kick' | 'snare' | 'hihat' | 'tom1' | 'tom2' | 'tom3';
-/**
- * Per-beat drumset voice for one তাল cycle, following sam/tali/khaali theory:
- * sam (cycle start) → kick, the first beat of each accented (non-khaali)
- * vibhag → snare (the tali clap), the first beat of a khaali vibhag → closed
- * hihat (the khaali "wave off"), every other beat → hihat (fill, keeping the
- * kit's groove going the way a tabla's filler strokes do).
- */
-declare function drumPattern(taal: Pick<Taal, 'numBeats' | 'sam' | 'bhaags' | 'khaali'>): DrumVoice[];
-/**
- * Fraction of the gap between two মীড় notes spent holding the source pitch
- * before the slide begins. 0 = slide the whole way (an alaap-slow meend);
- * 0.5 = hold half the note, then roll into the target.
- */
-declare const MEEND_HOLD = 0.5;
-/** Sampler `urls` key whose pitch is nearest `midi` (the sample to slide). */
-declare function nearestSampleKey(urls: Record<string, string>, midi: number): string;
-/** The same samples `createSampler` loads, as raw buffers for the glide voice. */
-declare function createBuffers(Tone: ToneModule, def: InstrumentDef, soundsBaseUrl: string | undefined, range?: {
-    lo: number;
-    hi: number;
-}): {
-    buffers: tone.ToneAudioBuffers;
-    urls: Record<string, string>;
-};
-/** One মীড় leg: the pitch to reach and the absolute time to reach it by. */
-interface GlideLeg {
-    midi: number;
-    /** Seconds on the transport; `legs[0]` is the attack itself. */
-    at: number;
-}
-/**
- * Sound one মীড় phrase: a single attack on `legs[0]` whose pitch then slides
- * through every following leg, ending at `endSec`. Used by both the live
- * player and the offline export.
- */
-declare function triggerGlide(Tone: ToneModule, buffers: InstanceType<ToneModule['ToneAudioBuffers']>, urls: Record<string, string>, dest: InstanceType<ToneModule['Gain']>, legs: readonly GlideLeg[], endSec: number, release?: number, hold?: number): void;
+import { L as Lay, a as LaySpeeds, T as TaalId } from './lay-CWlEhImP.js';
+import * as tone from 'tone';
 
 /**
  * Pure spec-doc → playback timeline. No Tone, no audio — the player turns
@@ -231,6 +94,9 @@ interface ScheduleOptions {
      * anything grouping events by row rely on; the player and the audio/MIDI
      * exports turn it on. */
     repeats?: boolean;
+    /** Play only the notes singing these stretches of the song's text (see
+     * alignLyrics / excerptVisits). Taken from the order above. */
+    excerpt?: Excerpt;
 }
 /**
  * Below-annotation raws that are মীড় arc drawing segments (codec known-raw):
@@ -331,4 +197,172 @@ declare function eventAt(events: PlayEvent[], path: string, near?: number): numb
  */
 declare function buildSchedule(doc: Swaralipi, opts?: ScheduleOptions): Schedule;
 
-export { ARC_RAW_RE as A, santoorUrls as B, scheduleLines as C, type DrumVoice as D, subsetUrls as E, tablaBpms as F, GRACE_STEP as G, tablaUrl as H, type InstrumentId as I, triggerGlide as J, type Line as L, MEEND_HOLD as M, type PlayEvent as P, type Schedule as S, type TempoSegment as T, type InstrumentDef as a, DEFAULT_SOUNDS_BASE as b, DRUM_KIT_BASE as c, type GlideLeg as d, INSTRUMENTS as e, SALAMANDER_BASE as f, SAMPLED_TAALS as g, type ScheduleOptions as h, TABLA_BPMS as i, TABLA_VARIATIONS as j, TONEJS_INSTRUMENTS_BASE as k, type ToneModule as l, buildSchedule as m, createBuffers as n, drumPattern as o, eventAt as p, glideTargets as q, graceTouches as r, instrumentSampleUrl as s, isArcRaw as t, meendContinuations as u, nearestSampleKey as v, nearestTablaBpm as w, normalizeBase as x, probeUrl as y, quantizeLoopEnd as z };
+/**
+ * Where in the song's text each note sings, and which notes sing a stretch of it.
+ *
+ * A swaralipi's lyric row is phonetic and split into syllables (আ|বা|র্, চি|ৎ|ত,
+ * ৹ for a held syllable), and it often writes a refrain out again. So the
+ * notation's letters are aligned to the text by global alignment
+ * (Needleman–Wunsch) that may also jump to any word start, the way JumpDTW lets
+ * a score re-enter its own repeat blocks (Fremerey, Müller & Clausen, ISMIR
+ * 2010). Over gitabitan's 1827 song/notation pairs it aligns 97.9 % of the
+ * notation's letters; the rest are songs whose text is only a fragment.
+ */
+
+/** `part.row.note` → the `[start, end)` UTF-16 offsets of the text it sings. */
+type LyricMap = Map<string, [number, number]>;
+/** The text's lines as the events sing them, each word timed by its first note — an LRC's
+ * cues. A line sung again (a repeat) is a new cue. Words are the text's whitespace runs. */
+declare function lyricCues(events: PlayEvent[], map: LyricMap, text: string): {
+    beat: number;
+    words: {
+        beat: number;
+        text: string;
+    }[];
+}[];
+/** Play only the notes singing these `[start, end)` stretches of the text, in order. */
+interface Excerpt {
+    lyrics: LyricMap;
+    ranges: [number, number][];
+}
+/** Each note of `doc` that sings a letter of `text`, with the stretch of `text` it sings. */
+declare function alignLyrics(doc: Swaralipi, text: string): LyricMap;
+
+/** The dynamically-imported Tone module, typed without importing it. */
+type ToneModule = typeof tone;
+/** A melodic instrument: a Tone.Sampler note→filename map + where to find it. */
+interface InstrumentDef {
+    /** Human label for UIs. */
+    label: string;
+    /** Tone.Sampler `urls`: note name (`C#4`) → filename (`Cs4.mp3`). */
+    urls: Record<string, string>;
+    /** Sample directory: an absolute URL, or — when `local` — a path segment
+     * appended to the player's `soundsBaseUrl`. */
+    baseUrl: string;
+    /** `baseUrl` is relative to `soundsBaseUrl` (needs it set). */
+    local?: boolean;
+    /** Sampler release time in seconds. */
+    release?: number;
+}
+/** Built-in melody instrument ids (consumers may add their own via the
+ * player's `customInstruments`, so the runtime id type stays open). */
+type InstrumentId = string;
+/**
+ * Default host for the project's samples (santoor / tabla / tanpura /
+ * metronome) — CORS-enabled, so the player works with zero config. Override via
+ * the player's `soundsBaseUrl` to self-host. (Melody defaults to the CDN-hosted
+ * piano, so it needs no host.) Licences: see THIRD-PARTY.md.
+ */
+declare const DEFAULT_SOUNDS_BASE = "https://bitoron.pages.dev/audio/instruments/";
+/** CC-BY Salamander Grand Piano (Tone's de-facto piano), CDN-hosted. */
+declare const SALAMANDER_BASE = "https://tonejs.github.io/audio/salamander/";
+/** CC-BY tonejs-instruments sample CDN (harmonium/violin/flute). */
+declare const TONEJS_INSTRUMENTS_BASE = "https://nbrosowsky.github.io/tonejs-instruments/samples/";
+/** Built-in melody instruments. santoor is local; the rest are CDN-hosted
+ * (CC-BY) so they need only network — `pianoBaseUrl`/`customInstruments`
+ * override for self-hosting. */
+declare const INSTRUMENTS: Record<string, InstrumentDef>;
+/** Taals with recorded tabla loops (everything else → metronome fallback). */
+declare const SAMPLED_TAALS: ReadonlySet<TaalId>;
+/** Available tabla loop tempos (file suffix `…<bpm>bpm.mp3`). */
+declare const TABLA_BPMS: readonly number[];
+/**
+ * Tabla loop variations per taal. Most taals have one unnamed loop at
+ * `tabla/<id>/`; an entry here overrides that:
+ *  - `variations` lists the variation suffixes, **first = default**.
+ *    A lone named variation (shashthi → `pro`, i.e. `tabla/shashthi-pro/`) IS
+ *    the default; later entries are premium upsells the player never auto-selects.
+ *    An empty-string entry (kehrwa → `''`) means the unnamed `tabla/<id>/` loop
+ *    is the default and a named entry follows it as an upsell.
+ *  - `skipBpms` are grid tempos this taal's loops were not recorded at.
+ * Consumers read this to build a variation/upsell UI; the player itself only
+ * ever plays the default (or whatever a doc's `meta.taal.variation` pins).
+ */
+declare const TABLA_VARIATIONS: Record<string, {
+    variations: string[];
+    skipBpms?: number[];
+}>;
+/** Tabla tempos actually available for a taal: the grid minus any it lacks. */
+declare function tablaBpms(taalId: string): readonly number[];
+/** Ensure exactly one trailing slash. */
+declare function normalizeBase(url: string): string;
+/** The 37 santoor samples, as a Tone.Sampler `urls` map (`C4` → `c4.mp3`). */
+declare function santoorUrls(): Record<string, string>;
+/**
+ * Restrict a Sampler `urls` map to just the samples needed to cover MIDI
+ * `[lo, hi]`: every sample inside the range, plus the nearest one below and
+ * above it (so Tone interpolates the edges without extrapolating). Cuts a
+ * typical song from ~37 santoor files to a handful — a big win on mobile and
+ * never worse on fast links (Tone fetches what's left in parallel). The
+ * Sampler pitch-shifts from the nearest sample, so audio is unchanged.
+ */
+declare function subsetUrls(urls: Record<string, string>, lo: number, hi: number): Record<string, string>;
+/** Resolve a representative sample URL for an instrument (its first sample),
+ * used to probe availability. undefined when a local instrument has no
+ * `soundsBaseUrl` or the def has no samples. */
+declare function instrumentSampleUrl(def: InstrumentDef, soundsBaseUrl?: string): string | undefined;
+/**
+ * Liveness check for a sample URL: a single tiny ranged GET (one byte), the
+ * same CORS-enabled fetch Tone uses to load the buffer — so a pass means Tone
+ * can actually load it. Resolves false on any error/timeout/non-2xx, and false
+ * (no throw) when `fetch` is unavailable (Node/SSR). `Range: bytes=0-0` is a
+ * CORS-safelisted header, so no preflight.
+ */
+declare function probeUrl(url: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Snap a tabla loop's end to the nearest whole beat of its measured length so a
+ * slightly-mistrimmed file still phase-locks to the melody grid instead of
+ * drifting a fraction of a beat each cycle. `spb` = seconds per beat (60/bpm).
+ * No-op for correctly trimmed loops (already an integer beat count); never
+ * extends past the buffer — a too-short file can't be repaired here.
+ *
+ * ponytail: belt-and-braces for off-spec audio; the real fix is trimming each
+ * loop to exactly `cycles × numBeats × 60/bpm` seconds at production time.
+ */
+declare function quantizeLoopEnd(durationSec: number, spb: number): number;
+/** Snap an arbitrary bpm to the nearest available tabla tempo (default grid;
+ * pass a taal's `tablaBpms()` so it never snaps to a tempo that taal lacks). */
+declare function nearestTablaBpm(bpm: number, bpms?: readonly number[]): number;
+/** URL of the tabla loop for a taal at a (snapped) bpm, optionally a named
+ * variation (defaults to the taal's default variation — see TABLA_VARIATIONS). */
+declare function tablaUrl(base: string, taalId: string, bpm: number, variation?: string): string;
+declare const DRUM_KIT_BASE = "https://tonejs.github.io/audio/drum-samples/acoustic-kit/";
+type DrumVoice = 'kick' | 'snare' | 'hihat' | 'tom1' | 'tom2' | 'tom3';
+/**
+ * Per-beat drumset voice for one তাল cycle, following sam/tali/khaali theory:
+ * sam (cycle start) → kick, the first beat of each accented (non-khaali)
+ * vibhag → snare (the tali clap), the first beat of a khaali vibhag → closed
+ * hihat (the khaali "wave off"), every other beat → hihat (fill, keeping the
+ * kit's groove going the way a tabla's filler strokes do).
+ */
+declare function drumPattern(taal: Pick<Taal, 'numBeats' | 'sam' | 'bhaags' | 'khaali'>): DrumVoice[];
+/**
+ * Fraction of the gap between two মীড় notes spent holding the source pitch
+ * before the slide begins. 0 = slide the whole way (an alaap-slow meend);
+ * 0.5 = hold half the note, then roll into the target.
+ */
+declare const MEEND_HOLD = 0.5;
+/** Sampler `urls` key whose pitch is nearest `midi` (the sample to slide). */
+declare function nearestSampleKey(urls: Record<string, string>, midi: number): string;
+/** The same samples `createSampler` loads, as raw buffers for the glide voice. */
+declare function createBuffers(Tone: ToneModule, def: InstrumentDef, soundsBaseUrl: string | undefined, range?: {
+    lo: number;
+    hi: number;
+}): {
+    buffers: tone.ToneAudioBuffers;
+    urls: Record<string, string>;
+};
+/** One মীড় leg: the pitch to reach and the absolute time to reach it by. */
+interface GlideLeg {
+    midi: number;
+    /** Seconds on the transport; `legs[0]` is the attack itself. */
+    at: number;
+}
+/**
+ * Sound one মীড় phrase: a single attack on `legs[0]` whose pitch then slides
+ * through every following leg, ending at `endSec`. Used by both the live
+ * player and the offline export.
+ */
+declare function triggerGlide(Tone: ToneModule, buffers: InstanceType<ToneModule['ToneAudioBuffers']>, urls: Record<string, string>, dest: InstanceType<ToneModule['Gain']>, legs: readonly GlideLeg[], endSec: number, release?: number, hold?: number): void;
+
+export { ARC_RAW_RE as A, normalizeBase as B, probeUrl as C, type DrumVoice as D, type Excerpt as E, quantizeLoopEnd as F, GRACE_STEP as G, santoorUrls as H, type InstrumentId as I, scheduleLines as J, subsetUrls as K, type Line as L, MEEND_HOLD as M, tablaBpms as N, tablaUrl as O, type PlayEvent as P, triggerGlide as Q, type Schedule as S, type TempoSegment as T, type InstrumentDef as a, DEFAULT_SOUNDS_BASE as b, DRUM_KIT_BASE as c, type GlideLeg as d, INSTRUMENTS as e, type LyricMap as f, SALAMANDER_BASE as g, SAMPLED_TAALS as h, type ScheduleOptions as i, TABLA_BPMS as j, TABLA_VARIATIONS as k, TONEJS_INSTRUMENTS_BASE as l, type ToneModule as m, alignLyrics as n, buildSchedule as o, createBuffers as p, drumPattern as q, eventAt as r, glideTargets as s, graceTouches as t, instrumentSampleUrl as u, isArcRaw as v, lyricCues as w, meendContinuations as x, nearestSampleKey as y, nearestTablaBpm as z };