@ugfoundation/swaralipi-js 0.1.0

package/dist/player/index.d.ts

@@ -0,0 +1,285 @@
+import { S as Swaralipi, O as Octave, a as SvaraLetter, N as Note } from '../schema-gxhG45OK.js';
+import { T as TaalId } from '../taals-DguYW0wf.js';
+import * as tone from 'tone';
+import 'zod';
+
+/** 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) — CC-BY, redistribution-verified and 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.)
+ */
+declare const DEFAULT_SOUNDS_BASE = "https://cdn.daserve.in/swaralipijs-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[];
+/** 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 an arbitrary bpm to the nearest available tabla tempo. */
+declare function nearestTablaBpm(bpm: number): number;
+/** URL of the tabla loop for a taal at a (snapped) bpm. */
+declare function tablaUrl(base: string, taalId: string, bpm: number): string;
+
+type PlayerState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused';
+type RhythmMode = 'tabla' | 'metronome' | 'none';
+interface PlayerOptions {
+    /** Base URL for the project's samples (santoor/tabla/tanpura/metronome).
+     * Defaults to `DEFAULT_SOUNDS_BASE` (the project's CORS-enabled CDN), so the
+     * player works with zero config; override to self-host. */
+    soundsBaseUrl?: string;
+    /** Grand-piano sample host. Default: the Salamander CDN (see SALAMANDER_BASE).
+     * Set this to self-host the piano under your own URL. */
+    pianoBaseUrl?: string;
+    /** Tonic (Sa). Accepts `C`, `C#`, `cs`… Default: doc tonic, else `C`. */
+    tonic?: string;
+    /** Tempo in matra/min. Default 90. Snapped to the 15-grid while tabla plays. */
+    bpm?: number;
+    /** Octave of madhyam Sa (C4 = MIDI 60). Default 4. */
+    baseOctave?: number;
+    /** Active melody instrument id (a built-in or a `customInstruments` key).
+     * Default `piano` (CDN-hosted, zero-config). Built-ins: piano, santoor,
+     * harmonium, violin, flute. */
+    instrument?: InstrumentId;
+    /** Instrument ids the UI may expose. Default: all built-ins. Narrow it to
+     * e.g. `['santoor','harmonium']` to limit the picker. */
+    instruments?: InstrumentId[];
+    /** Extra melody instruments, keyed by id — e.g. a self-hosted sitar/sarod.
+     * (True sampled sitar/sarod/sarangi/esraj have no free web set; supply your
+     * own Tone.Sampler `urls` + `baseUrl` here and they slot into the picker.) */
+    customInstruments?: Record<string, InstrumentDef>;
+    /** Rhythm accompaniment. Default `tabla` (→ metronome for unsampled taals). */
+    rhythm?: RhythmMode;
+    /** Play the tanpura drone. Default true. */
+    tanpura?: boolean;
+    /** Stop playback after this many seconds (a policy-neutral preview cap).
+     * Default `Infinity` (unlimited). The library only enforces the number it is
+     * handed; who is capped / the value / the upsell is the consumer's policy. */
+    previewLimitSec?: number;
+    /** Called when the preview cap stops playback (so the consumer can show an
+     * upsell). Not called on a normal stop()/end. */
+    onLimit?: () => void;
+    /** Called with the active note's `part.row.note` path, or null when idle. */
+    onHighlight?: (path: string | null) => void;
+    /** Called on every state transition. */
+    onState?: (state: PlayerState) => void;
+}
+/** Minimal shape of the viewer element the player drives (avoids a hard
+ * dependency on the viewer module). `highlight` returns the highlighted node
+ * (or null) so bindSheet can optionally scroll it into view. */
+interface HighlightTarget {
+    highlight(path: string): HTMLElement | null;
+    clearHighlights(): void;
+}
+interface BindSheetOptions {
+    /** Keep the active note visible while playing by calling `scrollIntoView`
+     * on it. `true` → `'center'` (keeps the note's lyric, rendered just below it,
+     * on screen too); or pass an explicit block position (`'nearest'`, `'start'`,
+     * …). Default off so it never fights a host that manages its own scrolling.
+     * Works through the shadow boundary, so it scrolls the page, not just the
+     * sheet. */
+    autoScroll?: boolean | ScrollLogicalPosition;
+}
+declare class SwaralipiPlayer {
+    #private;
+    constructor(options?: PlayerOptions);
+    get state(): PlayerState;
+    get bpm(): number;
+    /** The preview cap in seconds (`Infinity` = unlimited). */
+    get previewLimitSec(): number;
+    get instrument(): InstrumentId;
+    get instruments(): InstrumentId[];
+    /** The taal currently driving the rhythm (auto from the doc, or an override). */
+    get taalId(): TaalId | undefined;
+    /** Whether the effective rhythm will actually be a sampled tabla. */
+    get usesTabla(): boolean;
+    /** Set the document to play. Stops any current playback. */
+    load(doc: Swaralipi): void;
+    /** Start (or resume) playback. Must be triggered from a user gesture so the
+     * browser permits `AudioContext` resume. */
+    play(): Promise<void>;
+    /** Pause; `play()` resumes from the same position. */
+    pause(): void;
+    /**
+     * Stop and rewind to the start. When sounding, the accompaniment (tabla /
+     * metronome / tanpura, which otherwise loop) is gently faded out over
+     * STOP_FADE_SEC before the transport is halted, so the rhythm doesn't keep
+     * playing or cut abruptly; otherwise it halts immediately.
+     */
+    stop(): void;
+    setTonic(tonic: string): void;
+    setBpm(bpm: number): void;
+    /** Update the preview cap (`Infinity` lifts it). Takes effect on next play. */
+    setPreviewLimit(sec: number): void;
+    setInstrument(instrument: InstrumentId): void;
+    setRhythm(rhythm: RhythmMode): void;
+    setTanpura(on: boolean): void;
+    /** Override the taal (null restores auto-detection from `meta.taal`). */
+    setTaal(id: TaalId | null): void;
+    /** Wire highlight output to a `<swaralipi-sheet>` (or any highlight target).
+     * Pass `{ autoScroll }` to keep the active note in view while playing. */
+    bindSheet(target: HighlightTarget, opts?: BindSheetOptions): void;
+    /**
+     * Check whether an instrument's samples are reachable (its CDN is up / the
+     * local files exist), via a one-byte ranged fetch of a representative sample.
+     * A pass means Tone can actually load it. `false` for unknown ids, local
+     * instruments with no `soundsBaseUrl`, or any network failure/timeout.
+     */
+    checkInstrument(id: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Probe several instruments at once (default: the exposed `instruments`),
+     * returning `{ id: available }`. Use it to disable picker options whose CDN
+     * or files are down. Probes run concurrently; a check never throws.
+     */
+    checkInstruments(ids?: string[], timeoutMs?: number): Promise<Record<string, boolean>>;
+    /** Release all audio resources. The instance is unusable afterward. */
+    dispose(): void;
+}
+
+/**
+ * Pure spec-doc → playback timeline. No Tone, no audio — the player turns
+ * this `Schedule` into Transport events, but it is fully unit-testable on its
+ * own and mirrors the viewer's spec-driven (not raw-driven) reading.
+ *
+ * Timing unit is the মাত্রা (matra / beat). One global beat cursor runs across
+ * every part and row: NLTR "systems" (rows) are wraps of one continuous line,
+ * and parts (asthayi → antara …) play back-to-back, so the music never pauses
+ * at a row or part boundary.
+ *
+ * Each audible column carries the same `data-note` path the viewer emits
+ * (`part.row.note`, note = absolute index into `row.notes`; see
+ * src/viewer/render.ts), so `SwaralipiPlayer` can drive `highlight()` directly.
+ */
+
+interface PlayEvent {
+    /** Onset in matra from the start of the document. */
+    beat: number;
+    /** Ring length in matra (extended by following আ-কার holds). */
+    durationBeats: number;
+    /** Pitch as MIDI, or null for a rest / আ-কার hold column. */
+    midi: number | null;
+    /** Grace-note MIDI struck just before the main attack, when present. */
+    kan: number | null;
+    /** `part.row.note` highlight path. */
+    path: string;
+    kind: 'note' | 'rest' | 'sustain';
+}
+interface Schedule {
+    events: PlayEvent[];
+    /** Total length in matra (the cursor's final value). */
+    totalBeats: number;
+}
+interface ScheduleOptions {
+    /** Tonic; accepts `C`, `C#`, `cs`… (see parseTonic). Default C. */
+    tonic?: string;
+    /** Octave of madhyam Sa (C4 = MIDI 60). Default 4. */
+    baseOctave?: number;
+}
+/**
+ * Walk a document into a flat, time-ordered list of play events.
+ *
+ *  - svara note → an attack at the cursor; advances by `durationMatra ?? 1`.
+ *  - rest → a silent column that still advances the cursor.
+ *  - sustain **with** svara (melisma) → a fresh attack (the pitch moves under
+ *    a held vowel); advances.
+ *  - sustain **without** svara (আ-কার hold) → no attack, but the previous
+ *    audible note's ring is extended; still emitted (midi null) so the lyric
+ *    column highlights; advances.
+ *  - bar / bracket-only / carrier / raw-only → ignored (no event, no advance).
+ */
+declare function buildSchedule(doc: Swaralipi, opts?: ScheduleOptions): Schedule;
+
+/**
+ * Pure svara → pitch math for the player. No Tone, no audio — unit-testable
+ * in plain Node and shared by the scheduler.
+ *
+ * The model: a tonic (Sa) pitch-class + a per-note scale degree + octave
+ * register + komal/tivra/microtone accidentals → an absolute MIDI number,
+ * which the Tone.Sampler pitch-shifts from the nearest santoor sample.
+ */
+
+/** Octave register offset in octaves, relative to madhyam (middle). */
+declare const OCTAVE_OFFSET: Record<Octave, number>;
+/**
+ * Shuddha (natural) scale degrees in semitones above Sa — the Bilawal/major
+ * thaat that Rabindrasangeet swaralipi notates against. `d` = dha, `n` = ni
+ * (standard sargam letter convention).
+ */
+declare const SHUDDHA: Record<SvaraLetter, number>;
+/**
+ * Parse a tonic string to a pitch-class 0–11. Accepts `C`, `C#`, `Db`, and
+ * the player/sample lowercase-`s` sharp form (`cs`, `Cs`); case-insensitive.
+ * Unknown input falls back to 0 (C).
+ */
+declare function parseTonic(tonic: string | undefined): number;
+/**
+ * Semitone of a note relative to Sa (degree + accidentals), ignoring octave.
+ * Returns null when the note carries no pitch (rest/sustain-hold/bar).
+ *
+ * Microtones (অল্পকোমল/অতিকোমল) are approximated to the komal pitch — a
+ * documented v1 limitation (the sampler can't bend a sub-komal microtone
+ * cleanly per note); matches the viewer's placeholder treatment.
+ */
+declare function svaraSemitone(note: Note): number | null;
+/**
+ * Absolute MIDI for a note, or null when it has no pitch. madhyam Sa lands on
+ * the tonic in octave `baseOctave` (C4 = MIDI 60). Out-of-sample registers
+ * are produced by the Sampler pitch-shifting from the nearest recorded note.
+ */
+declare function svaraToMidi(note: Note, tonicPc: number, baseOctave?: number): number | null;
+/** MIDI → Tone note name (`C#4`). */
+declare function midiToSampleName(midi: number): string;
+/** MIDI → santoor sample filename stem (`cs4`): lowercase, `#` → `s`. */
+declare function sampleFileName(midi: number): string;
+
+export { type BindSheetOptions, DEFAULT_SOUNDS_BASE, INSTRUMENTS, type InstrumentDef, type InstrumentId, OCTAVE_OFFSET, type PlayEvent, type PlayerOptions, type PlayerState, type RhythmMode, SALAMANDER_BASE, SAMPLED_TAALS, SHUDDHA, type Schedule, type ScheduleOptions, SwaralipiPlayer, TABLA_BPMS, TONEJS_INSTRUMENTS_BASE, type ToneModule, buildSchedule, instrumentSampleUrl, midiToSampleName, nearestTablaBpm, normalizeBase, parseTonic, probeUrl, sampleFileName, santoorUrls, subsetUrls, svaraSemitone, svaraToMidi, tablaUrl };