@ugfoundation/swaralipi-js 0.9.2 → 0.10.0

package/dist/player/index.d.cts

@@ -1,13 +1,25 @@
 import { S as Swaralipi, T as Taal, O as Octave, a as SvaraLetter, N as Note } from '../schema-Cf_epUIC.cjs';
 import { a as LaySpeeds, T as TaalId } from '../lay-CfDlPhH2.cjs';
 export { b as LAYS, c as LAY_SPEEDS, L as Lay, p as printedLay, r as resolveLaySpeeds, d as rowLay } from '../lay-CfDlPhH2.cjs';
-import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice, T as TempoSegment } from '../schedule-CU-VECDH.cjs';
-export { A as ARC_RAW_RE, b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, G as GRACE_STEP, d as GlideLeg, e as INSTRUMENTS, M as MEEND_HOLD, P as PlayEvent, f as SALAMANDER_BASE, g as SAMPLED_TAALS, h as ScheduleOptions, i as TABLA_BPMS, j as TABLA_VARIATIONS, k as TONEJS_INSTRUMENTS_BASE, l as ToneModule, m as buildSchedule, n as createBuffers, o as drumPattern, p as glideTargets, q as graceTouches, r as instrumentSampleUrl, s as isArcRaw, t as meendContinuations, u as nearestSampleKey, v as nearestTablaBpm, w as normalizeBase, x as probeUrl, y as quantizeLoopEnd, z as santoorUrls, B as subsetUrls, C as tablaBpms, E as tablaUrl, F as triggerGlide } from '../schedule-CU-VECDH.cjs';
+import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice, T as TempoSegment } from '../schedule-IBu8lr-3.cjs';
+export { A as ARC_RAW_RE, b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, G as GRACE_STEP, d as GlideLeg, e as INSTRUMENTS, L as Line, M as MEEND_HOLD, P as PlayEvent, f as SALAMANDER_BASE, g as SAMPLED_TAALS, h as ScheduleOptions, i as TABLA_BPMS, j as TABLA_VARIATIONS, k as TONEJS_INSTRUMENTS_BASE, l as ToneModule, m as buildSchedule, n as createBuffers, o as drumPattern, p as eventAt, q as glideTargets, r as graceTouches, s as instrumentSampleUrl, t as isArcRaw, u as meendContinuations, v as nearestSampleKey, w as nearestTablaBpm, x as normalizeBase, y as probeUrl, z as quantizeLoopEnd, B as santoorUrls, C as scheduleLines, E as subsetUrls, F as tablaBpms, H as tablaUrl, J as triggerGlide } from '../schedule-IBu8lr-3.cjs';
 import 'zod';
 import 'tone';
 
 type PlayerState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused';
 type RhythmMode = 'tabla' | 'drums' | 'metronome' | 'none';
+/** Repeated lines, as `part.row` paths (the viewer's `data-row`), inclusive. */
+interface LineRange {
+    from: string;
+    to: string;
+}
+/** What the practice controls show: the repeated lines, whether the learner
+ * sings each pass back, and whether the pass now sounding is theirs. */
+interface PracticeState {
+    loop: LineRange | null;
+    echo: boolean;
+    yourTurn: boolean;
+}
 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
@@ -52,8 +64,12 @@ interface PlayerOptions {
     /** 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 with the active note's `part.row.note` path, or null when idle.
+     * `yourTurn` is true while the melody is silent for the learner to sing
+     * (see `setEcho`): the note is where they should be, not what is sounding. */
+    onHighlight?: (path: string | null, yourTurn?: boolean) => void;
+    /** Called whenever the repeat, the sing-back or the learner's turn changes. */
+    onLoop?: (state: PracticeState) => 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.
@@ -74,8 +90,10 @@ interface PlayerOptions {
  * 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;
+    highlight(path: string, yourTurn?: boolean): HTMLElement | null;
     clearHighlights(): void;
+    /** Shade the repeated lines, and mark the learner's turn on them. */
+    markLoop?(loop: LineRange | null, yourTurn: boolean): void;
 }
 interface BindSheetOptions {
     /** Keep the active note visible while playing by calling `scrollIntoView`
@@ -112,6 +130,12 @@ declare class SwaralipiPlayer {
     /** 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;
+    /** The note last played or sought (`part.row.note`), or null. */
+    get cursor(): string | null;
+    /** The repeated lines, or null. */
+    get loop(): LineRange | null;
+    /** Whether each repeat is followed by a silent pass for the learner. */
+    get echo(): boolean;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
     /**
@@ -123,11 +147,42 @@ declare class SwaralipiPlayer {
      * `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>;
+    /** 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. */
+    play(from?: string): Promise<void>;
     /** Pause; `play()` resumes from the same position. */
     pause(): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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?: string | null, to?: string): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * 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: number): void;
+    /** Move by single notes (rests and holds included — each is a column). */
+    stepNote(delta: number): void;
     /**
      * Stop and rewind to the start. When sounding, the accompaniment (tabla /
      * metronome / tanpura, which otherwise loop) is gently faded out over
@@ -144,8 +199,18 @@ declare class SwaralipiPlayer {
     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. */
+    /**
+     * 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: HighlightTarget, opts?: BindSheetOptions): void;
     /**
      * Check whether an instrument's samples are reachable (its CDN is up / the
@@ -342,4 +407,4 @@ declare function sampleFileName(midi: number): string;
  */
 declare function sCurve(x: number, steepness?: number): number;
 
-export { type AudioExportOptions, type AudioExportResult, type AudioFormat, type BindSheetOptions, DrumVoice, InstrumentDef, InstrumentId, LaySpeeds, type MidiExportOptions, type MidiExportResult, OCTAVE_OFFSET, type PlayerOptions, type PlayerState, type RhythmMode, SHUDDHA, Schedule, SwaralipiPlayer, TempoSegment, encodeMidi, encodeMp3, encodeWav, exportAudio, exportMidi, midiToSampleName, parseTonic, sCurve, sampleFileName, svaraSemitone, svaraToMidi };
+export { type AudioExportOptions, type AudioExportResult, type AudioFormat, type BindSheetOptions, DrumVoice, InstrumentDef, InstrumentId, LaySpeeds, type LineRange, type MidiExportOptions, type MidiExportResult, OCTAVE_OFFSET, type PlayerOptions, type PlayerState, type PracticeState, type RhythmMode, SHUDDHA, Schedule, SwaralipiPlayer, TempoSegment, encodeMidi, encodeMp3, encodeWav, exportAudio, exportMidi, midiToSampleName, parseTonic, sCurve, sampleFileName, svaraSemitone, svaraToMidi };

package/dist/player/index.d.ts

@@ -1,13 +1,25 @@
 import { S as Swaralipi, T as Taal, O as Octave, a as SvaraLetter, N as Note } from '../schema-Cf_epUIC.js';
 import { a as LaySpeeds, T as TaalId } from '../lay-CZIzR9cM.js';
 export { b as LAYS, c as LAY_SPEEDS, L as Lay, p as printedLay, r as resolveLaySpeeds, d as rowLay } from '../lay-CZIzR9cM.js';
-import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice, T as TempoSegment } from '../schedule-BaovCtmf.js';
-export { A as ARC_RAW_RE, b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, G as GRACE_STEP, d as GlideLeg, e as INSTRUMENTS, M as MEEND_HOLD, P as PlayEvent, f as SALAMANDER_BASE, g as SAMPLED_TAALS, h as ScheduleOptions, i as TABLA_BPMS, j as TABLA_VARIATIONS, k as TONEJS_INSTRUMENTS_BASE, l as ToneModule, m as buildSchedule, n as createBuffers, o as drumPattern, p as glideTargets, q as graceTouches, r as instrumentSampleUrl, s as isArcRaw, t as meendContinuations, u as nearestSampleKey, v as nearestTablaBpm, w as normalizeBase, x as probeUrl, y as quantizeLoopEnd, z as santoorUrls, B as subsetUrls, C as tablaBpms, E as tablaUrl, F as triggerGlide } from '../schedule-BaovCtmf.js';
+import { I as InstrumentId, a as InstrumentDef, S as Schedule, D as DrumVoice, T as TempoSegment } from '../schedule-BUopqmWm.js';
+export { A as ARC_RAW_RE, b as DEFAULT_SOUNDS_BASE, c as DRUM_KIT_BASE, G as GRACE_STEP, d as GlideLeg, e as INSTRUMENTS, L as Line, M as MEEND_HOLD, P as PlayEvent, f as SALAMANDER_BASE, g as SAMPLED_TAALS, h as ScheduleOptions, i as TABLA_BPMS, j as TABLA_VARIATIONS, k as TONEJS_INSTRUMENTS_BASE, l as ToneModule, m as buildSchedule, n as createBuffers, o as drumPattern, p as eventAt, q as glideTargets, r as graceTouches, s as instrumentSampleUrl, t as isArcRaw, u as meendContinuations, v as nearestSampleKey, w as nearestTablaBpm, x as normalizeBase, y as probeUrl, z as quantizeLoopEnd, B as santoorUrls, C as scheduleLines, E as subsetUrls, F as tablaBpms, H as tablaUrl, J as triggerGlide } from '../schedule-BUopqmWm.js';
 import 'zod';
 import 'tone';
 
 type PlayerState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused';
 type RhythmMode = 'tabla' | 'drums' | 'metronome' | 'none';
+/** Repeated lines, as `part.row` paths (the viewer's `data-row`), inclusive. */
+interface LineRange {
+    from: string;
+    to: string;
+}
+/** What the practice controls show: the repeated lines, whether the learner
+ * sings each pass back, and whether the pass now sounding is theirs. */
+interface PracticeState {
+    loop: LineRange | null;
+    echo: boolean;
+    yourTurn: boolean;
+}
 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
@@ -52,8 +64,12 @@ interface PlayerOptions {
     /** 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 with the active note's `part.row.note` path, or null when idle.
+     * `yourTurn` is true while the melody is silent for the learner to sing
+     * (see `setEcho`): the note is where they should be, not what is sounding. */
+    onHighlight?: (path: string | null, yourTurn?: boolean) => void;
+    /** Called whenever the repeat, the sing-back or the learner's turn changes. */
+    onLoop?: (state: PracticeState) => 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.
@@ -74,8 +90,10 @@ interface PlayerOptions {
  * 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;
+    highlight(path: string, yourTurn?: boolean): HTMLElement | null;
     clearHighlights(): void;
+    /** Shade the repeated lines, and mark the learner's turn on them. */
+    markLoop?(loop: LineRange | null, yourTurn: boolean): void;
 }
 interface BindSheetOptions {
     /** Keep the active note visible while playing by calling `scrollIntoView`
@@ -112,6 +130,12 @@ declare class SwaralipiPlayer {
     /** 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;
+    /** The note last played or sought (`part.row.note`), or null. */
+    get cursor(): string | null;
+    /** The repeated lines, or null. */
+    get loop(): LineRange | null;
+    /** Whether each repeat is followed by a silent pass for the learner. */
+    get echo(): boolean;
     /** Set the document to play. Stops any current playback. */
     load(doc: Swaralipi): void;
     /**
@@ -123,11 +147,42 @@ declare class SwaralipiPlayer {
      * `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>;
+    /** 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. */
+    play(from?: string): Promise<void>;
     /** Pause; `play()` resumes from the same position. */
     pause(): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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?: string | null, to?: string): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * 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: number): void;
+    /** Move by single notes (rests and holds included — each is a column). */
+    stepNote(delta: number): void;
     /**
      * Stop and rewind to the start. When sounding, the accompaniment (tabla /
      * metronome / tanpura, which otherwise loop) is gently faded out over
@@ -144,8 +199,18 @@ declare class SwaralipiPlayer {
     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. */
+    /**
+     * 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: HighlightTarget, opts?: BindSheetOptions): void;
     /**
      * Check whether an instrument's samples are reachable (its CDN is up / the
@@ -342,4 +407,4 @@ declare function sampleFileName(midi: number): string;
  */
 declare function sCurve(x: number, steepness?: number): number;
 
-export { type AudioExportOptions, type AudioExportResult, type AudioFormat, type BindSheetOptions, DrumVoice, InstrumentDef, InstrumentId, LaySpeeds, type MidiExportOptions, type MidiExportResult, OCTAVE_OFFSET, type PlayerOptions, type PlayerState, type RhythmMode, SHUDDHA, Schedule, SwaralipiPlayer, TempoSegment, encodeMidi, encodeMp3, encodeWav, exportAudio, exportMidi, midiToSampleName, parseTonic, sCurve, sampleFileName, svaraSemitone, svaraToMidi };
+export { type AudioExportOptions, type AudioExportResult, type AudioFormat, type BindSheetOptions, DrumVoice, InstrumentDef, InstrumentId, LaySpeeds, type LineRange, type MidiExportOptions, type MidiExportResult, OCTAVE_OFFSET, type PlayerOptions, type PlayerState, type PracticeState, type RhythmMode, SHUDDHA, Schedule, SwaralipiPlayer, TempoSegment, encodeMidi, encodeMp3, encodeWav, exportAudio, exportMidi, midiToSampleName, parseTonic, sCurve, sampleFileName, svaraSemitone, svaraToMidi };