@mcptoolshop/ai_jam_session 0.1.0

package/dist/teaching/live-midi-feedback.js

@@ -0,0 +1,259 @@
+// ─── Live MIDI Teaching Feedback (Position-Aware) ───────────────────────────
+//
+// Position-aware teaching hook that uses the PositionTracker to provide
+// measure-level feedback during MIDI playback. Unlike the basic
+// createMidiFeedbackHook (which reacts to individual note events), this
+// hook operates at the measure level — detecting patterns, phrasing,
+// section transitions, and difficulty ahead of time.
+//
+// This is what makes the teacher feel like they're sitting next to you:
+// they see what's coming and comment on it before you get there.
+// ─────────────────────────────────────────────────────────────────────────────
+import { PositionTracker } from "../playback/position.js";
+import { midiToNoteName } from "../note-parser.js";
+// ─── Pattern Detection ──────────────────────────────────────────────────────
+/** Detect if a measure has a large range (hands spread wide). */
+function detectWideRange(minNote, maxNote) {
+    const range = maxNote - minNote;
+    if (range >= 24)
+        return `Wide range — ${midiToNoteName(minNote)} to ${midiToNoteName(maxNote)} (${range} semitones). Stretch those hands.`;
+    if (range >= 18)
+        return `Spread out: ${midiToNoteName(minNote)} to ${midiToNoteName(maxNote)}. Keep your wrists relaxed.`;
+    return null;
+}
+/** Detect sudden velocity shift compared to previous measure. */
+function detectVelocityShift(prevAvg, currAvg) {
+    const diff = currAvg - prevAvg;
+    if (diff > 30)
+        return "Sudden jump in volume — lean into it with confidence.";
+    if (diff < -30)
+        return "Dropping to a whisper — lighten your touch gradually.";
+    return null;
+}
+/** Detect dense measure (lots of notes). */
+function detectDensity(noteCount) {
+    if (noteCount >= 12)
+        return `Busy passage ahead — ${noteCount} notes in this measure. Stay steady.`;
+    if (noteCount >= 8)
+        return `Active measure — ${noteCount} notes. Keep the tempo even.`;
+    return null;
+}
+/** Detect sparse measure (breathing room). */
+function detectSparse(noteCount, prevCount) {
+    if (noteCount <= 2 && prevCount >= 6)
+        return "Space to breathe — let the notes ring.";
+    return null;
+}
+/** Detect if we're approaching a section boundary (long gap between measures). */
+function detectSectionBoundary(tracker, measure) {
+    if (measure >= tracker.totalMeasures)
+        return null;
+    const currEvents = tracker.eventsInMeasure(measure);
+    const nextEvents = tracker.eventsInMeasure(measure + 1);
+    if (currEvents.length === 0 || nextEvents.length === 0)
+        return null;
+    const lastNoteEnd = Math.max(...currEvents.map((e) => e.time + e.duration));
+    const nextNoteStart = Math.min(...nextEvents.map((e) => e.time));
+    const gap = nextNoteStart - lastNoteEnd;
+    // A full measure's rest or more suggests a section boundary
+    if (gap > 2.0)
+        return "Natural break coming up — good place to breathe.";
+    return null;
+}
+// ─── Encouragement Phrases ──────────────────────────────────────────────────
+const MEASURE_ENCOURAGEMENTS = [
+    "Great flow!",
+    "Keep that steady pulse!",
+    "Nice touch!",
+    "Solid rhythm!",
+    "Beautiful!",
+    "You're in the groove!",
+    "Smooth!",
+    "That's the way!",
+];
+const MILESTONE_MESSAGES = {
+    25: "Quarter of the way through — you're doing great!",
+    50: "Halfway there — keep the energy up!",
+    75: "Three quarters done — bring it home!",
+};
+// ─── Hook ───────────────────────────────────────────────────────────────────
+/**
+ * Create a position-aware live feedback hook for MIDI playback.
+ *
+ * Uses PositionTracker to analyse measure context before each measure plays.
+ * Provides: range warnings, velocity shift detection, density alerts,
+ * section boundary markers, milestone announcements, periodic encouragement.
+ *
+ * Designed to be composed with createSingOnMidiHook for the full experience.
+ */
+export function createLiveMidiFeedbackHook(voiceSink, asideSink, midi, options = {}) {
+    const { voiceInterval = 8, warnOnWideRange = true, warnOnVelocityShift = true, warnOnDensity = true, detectSections = true, announceMilestones = true, voice, speechSpeed = 1.0, } = options;
+    const tracker = new PositionTracker(midi);
+    const voiceDirectives = [];
+    const asideDirectives = [];
+    // Pre-compute measure summaries for lookahead
+    const measureSummaries = new Map();
+    for (let m = 1; m <= tracker.totalMeasures; m++) {
+        measureSummaries.set(m, tracker.measureSummary(m));
+    }
+    let lastMeasureAnnounced = 0;
+    let measureCounter = 0;
+    let lastAnnouncedMilestone = 0;
+    let prevMeasureSummary = null;
+    async function emitVoice(directive) {
+        voiceDirectives.push(directive);
+        await voiceSink(directive);
+    }
+    async function emitAside(directive) {
+        asideDirectives.push(directive);
+        await asideSink(directive);
+    }
+    return {
+        voiceDirectives,
+        asideDirectives,
+        tracker,
+        async onMeasureStart(eventIndex, _teachingNote, _dynamics) {
+            // Map event index to measure number via position tracker
+            const event = midi.events[eventIndex - 1];
+            if (!event)
+                return;
+            const snapshot = tracker.snapshotAt(event.time);
+            const currentMeasure = snapshot.measure;
+            // Only process each measure once
+            if (currentMeasure === lastMeasureAnnounced)
+                return;
+            lastMeasureAnnounced = currentMeasure;
+            measureCounter++;
+            const summary = measureSummaries.get(currentMeasure);
+            if (!summary || summary.noteCount === 0)
+                return;
+            // ── Wide range warning ──
+            if (warnOnWideRange) {
+                const rangeWarning = detectWideRange(summary.minNote, summary.maxNote);
+                if (rangeWarning) {
+                    await emitAside({
+                        text: `Measure ${currentMeasure}: ${rangeWarning}`,
+                        priority: "med",
+                        reason: "difficulty-warning",
+                        source: `measure-${currentMeasure}`,
+                        tags: ["piano-teacher", "live-feedback", "range"],
+                    });
+                }
+            }
+            // ── Velocity shift ──
+            if (warnOnVelocityShift && prevMeasureSummary && prevMeasureSummary.noteCount > 0) {
+                const shift = detectVelocityShift(prevMeasureSummary.avgVelocity, summary.avgVelocity);
+                if (shift) {
+                    await emitAside({
+                        text: `Measure ${currentMeasure}: ${shift}`,
+                        priority: "low",
+                        reason: "dynamics-change",
+                        source: `measure-${currentMeasure}`,
+                        tags: ["piano-teacher", "live-feedback", "dynamics"],
+                    });
+                }
+            }
+            // ── Density warning ──
+            if (warnOnDensity) {
+                const densityWarning = detectDensity(summary.noteCount);
+                if (densityWarning) {
+                    await emitAside({
+                        text: `Measure ${currentMeasure}: ${densityWarning}`,
+                        priority: "low",
+                        reason: "difficulty-warning",
+                        source: `measure-${currentMeasure}`,
+                        tags: ["piano-teacher", "live-feedback", "density"],
+                    });
+                }
+                if (prevMeasureSummary) {
+                    const sparseMsg = detectSparse(summary.noteCount, prevMeasureSummary.noteCount);
+                    if (sparseMsg) {
+                        await emitAside({
+                            text: `Measure ${currentMeasure}: ${sparseMsg}`,
+                            priority: "low",
+                            reason: "style-tip",
+                            source: `measure-${currentMeasure}`,
+                            tags: ["piano-teacher", "live-feedback", "phrasing"],
+                        });
+                    }
+                }
+            }
+            // ── Section boundary ──
+            if (detectSections) {
+                const boundary = detectSectionBoundary(tracker, currentMeasure);
+                if (boundary) {
+                    await emitAside({
+                        text: `Measure ${currentMeasure}: ${boundary}`,
+                        priority: "low",
+                        reason: "style-tip",
+                        source: `measure-${currentMeasure}`,
+                        tags: ["piano-teacher", "live-feedback", "section"],
+                    });
+                }
+            }
+            // ── Milestone announcements ──
+            if (announceMilestones && tracker.totalMeasures > 0) {
+                const percent = Math.round((currentMeasure / tracker.totalMeasures) * 100);
+                for (const [milestone, msg] of Object.entries(MILESTONE_MESSAGES)) {
+                    const ms = Number(milestone);
+                    if (percent >= ms && lastAnnouncedMilestone < ms) {
+                        lastAnnouncedMilestone = ms;
+                        await emitVoice({
+                            text: msg,
+                            voice,
+                            speed: speechSpeed,
+                            blocking: false,
+                        });
+                    }
+                }
+            }
+            // ── Periodic encouragement ──
+            if (voiceInterval > 0 && measureCounter % voiceInterval === 0) {
+                const phrase = MEASURE_ENCOURAGEMENTS[measureCounter % MEASURE_ENCOURAGEMENTS.length];
+                await emitVoice({
+                    text: phrase,
+                    voice,
+                    speed: speechSpeed,
+                    blocking: false,
+                });
+            }
+            prevMeasureSummary = summary;
+        },
+        async onKeyMoment(moment) {
+            await emitVoice({
+                text: moment,
+                voice,
+                speed: speechSpeed,
+                blocking: false,
+            });
+        },
+        async onSongComplete(eventsPlayed, songTitle) {
+            const durationMin = Math.round(midi.durationSeconds / 60);
+            const timeStr = durationMin > 0
+                ? `${durationMin} minute${durationMin !== 1 ? "s" : ""}`
+                : "less than a minute";
+            await emitVoice({
+                text: `Excellent work on ${songTitle}! ${eventsPlayed} notes across ${tracker.totalMeasures} measures in ${timeStr}.`,
+                voice,
+                speed: speechSpeed,
+                blocking: false,
+            });
+            await emitAside({
+                text: `Session complete: ${songTitle} — ${tracker.totalMeasures} measures, ${eventsPlayed} notes at ${midi.bpm} BPM.`,
+                priority: "low",
+                reason: "session-complete",
+                tags: ["piano-teacher", "live-feedback", "completion"],
+            });
+        },
+        async push(interjection) {
+            await emitAside({
+                text: interjection.text,
+                priority: interjection.priority,
+                reason: interjection.reason,
+                source: interjection.source,
+                tags: ["piano-teacher", "live-feedback", interjection.reason],
+            });
+        },
+    };
+}
+//# sourceMappingURL=live-midi-feedback.js.map

package/dist/teaching/live-midi-feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-midi-feedback.js","sourceRoot":"","sources":["../../src/teaching/live-midi-feedback.ts"],"names":[],"mappings":"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"}

package/dist/teaching/midi-feedback.d.ts

@@ -0,0 +1,33 @@
+import type { ParsedMidi } from "../midi/types.js";
+import type { TeachingHook, VoiceDirective, VoiceSink, AsideDirective, AsideSink, LiveFeedbackHookOptions } from "../types.js";
+export interface MidiFeedbackOptions extends LiveFeedbackHookOptions {
+    /**
+     * Warn about large leaps (interval > this many semitones).
+     * Default: 12 (one octave).
+     */
+    leapWarnSemitones?: number;
+    /**
+     * Warn about dense chords (more notes than this at once).
+     * Default: 4.
+     */
+    denseChordThreshold?: number;
+}
+/**
+ * Create a live feedback hook for MIDI file playback.
+ *
+ * Analyses the raw MIDI events to provide:
+ * - Voice encouragement every N notes
+ * - Aside tips on dynamics changes (velocity zones)
+ * - Aside warnings for wide leaps and dense chords
+ *
+ * @param voiceSink - Voice output callback.
+ * @param asideSink - Aside output callback.
+ * @param midi - Parsed MIDI file data.
+ * @param options - Configuration.
+ * @returns Teaching hook with recorded directives for inspection.
+ */
+export declare function createMidiFeedbackHook(voiceSink: VoiceSink, asideSink: AsideSink, midi: ParsedMidi, options?: MidiFeedbackOptions): TeachingHook & {
+    voiceDirectives: VoiceDirective[];
+    asideDirectives: AsideDirective[];
+};
+//# sourceMappingURL=midi-feedback.d.ts.map

package/dist/teaching/midi-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-feedback.d.ts","sourceRoot":"","sources":["../../src/teaching/midi-feedback.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,cAAc,EACd,SAAS,EACT,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAuCrB,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,mBAAwB,GAChC,YAAY,GAAG;IAAE,eAAe,EAAE,cAAc,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAqKzF"}

package/dist/teaching/midi-feedback.js

@@ -0,0 +1,208 @@
+// ─── Live Feedback for MIDI Files ───────────────────────────────────────────
+//
+// Teaching hook that provides real-time encouragement and context-aware
+// asides during MIDI file playback. Unlike the library feedback hook (which
+// reads SongEntry teaching notes and dynamics), this analyses the raw MIDI
+// event stream: velocity shifts, wide leaps, chord density, tempo changes.
+//
+// Designed to work with PlaybackController's event system.
+// ─────────────────────────────────────────────────────────────────────────────
+import { midiToNoteName } from "../note-parser.js";
+// ─── Analysis Helpers ───────────────────────────────────────────────────────
+/** Detect velocity zone: pp, p, mp, mf, f, ff based on MIDI velocity. */
+function velocityToDynamic(velocity) {
+    if (velocity < 20)
+        return "pp";
+    if (velocity < 45)
+        return "p";
+    if (velocity < 65)
+        return "mp";
+    if (velocity < 85)
+        return "mf";
+    if (velocity < 105)
+        return "f";
+    return "ff";
+}
+/** Dynamics-aware tips (same as library hook). */
+const DYNAMICS_TIPS = {
+    pp: "Very soft passage — light touch, barely pressing the keys.",
+    p: "Soft passage — gentle, controlled touch.",
+    mp: "Moderately soft — warm, balanced tone.",
+    mf: "Moderately loud — confident, full sound.",
+    f: "Loud passage — strong, powerful playing.",
+    ff: "Very loud — give it full energy!",
+};
+/** Encouragement phrases. */
+const ENCOURAGEMENTS = [
+    "Keep it up!",
+    "Sounding great!",
+    "Nice rhythm!",
+    "Beautiful phrasing!",
+    "You've got this!",
+    "Smooth playing!",
+    "Lovely tone!",
+    "Great hands!",
+];
+// ─── MIDI Feedback Hook ─────────────────────────────────────────────────────
+/**
+ * Create a live feedback hook for MIDI file playback.
+ *
+ * Analyses the raw MIDI events to provide:
+ * - Voice encouragement every N notes
+ * - Aside tips on dynamics changes (velocity zones)
+ * - Aside warnings for wide leaps and dense chords
+ *
+ * @param voiceSink - Voice output callback.
+ * @param asideSink - Aside output callback.
+ * @param midi - Parsed MIDI file data.
+ * @param options - Configuration.
+ * @returns Teaching hook with recorded directives for inspection.
+ */
+export function createMidiFeedbackHook(voiceSink, asideSink, midi, options = {}) {
+    const { voiceInterval = 16, encourageOnDynamics = true, warnOnDifficult = true, voice, speechSpeed = 1.0, leapWarnSemitones = 12, denseChordThreshold = 4, } = options;
+    const voiceDirectives = [];
+    const asideDirectives = [];
+    let noteCount = 0;
+    let lastDynamic = "";
+    let lastNote = -1;
+    // Pre-compute chord density map (count notes at each time cluster)
+    const chordDensityMap = new Map();
+    const events = midi.events;
+    if (events.length > 0) {
+        let clusterStart = events[0].time;
+        let clusterCount = 1;
+        for (let i = 1; i < events.length; i++) {
+            if (events[i].time - clusterStart < 0.01) { // 10ms threshold
+                clusterCount++;
+            }
+            else {
+                if (clusterCount >= denseChordThreshold) {
+                    // Mark all events in this cluster
+                    for (let j = i - clusterCount; j < i; j++) {
+                        chordDensityMap.set(j, clusterCount);
+                    }
+                }
+                clusterStart = events[i].time;
+                clusterCount = 1;
+            }
+        }
+        // Handle last cluster
+        if (clusterCount >= denseChordThreshold) {
+            for (let j = events.length - clusterCount; j < events.length; j++) {
+                chordDensityMap.set(j, clusterCount);
+            }
+        }
+    }
+    async function emitVoice(directive) {
+        voiceDirectives.push(directive);
+        await voiceSink(directive);
+    }
+    async function emitAside(directive) {
+        asideDirectives.push(directive);
+        await asideSink(directive);
+    }
+    return {
+        voiceDirectives,
+        asideDirectives,
+        async onMeasureStart(eventIndex, _teachingNote, _dynamics) {
+            noteCount++;
+            const midiEvent = events[eventIndex - 1]; // 1-based to 0-based
+            if (!midiEvent)
+                return;
+            // ── Dynamics change detection (velocity zones) ──
+            if (encourageOnDynamics) {
+                const dynamic = velocityToDynamic(midiEvent.velocity);
+                if (dynamic !== lastDynamic && lastDynamic !== "") {
+                    const tip = DYNAMICS_TIPS[dynamic];
+                    if (tip) {
+                        await emitAside({
+                            text: `${tip}`,
+                            priority: "low",
+                            reason: "dynamics-change",
+                            source: `note-${eventIndex}`,
+                            tags: ["piano-teacher", "midi-feedback", "dynamics"],
+                        });
+                    }
+                }
+                lastDynamic = dynamic;
+            }
+            // ── Wide leap warning ──
+            if (warnOnDifficult && lastNote >= 0) {
+                const interval = Math.abs(midiEvent.note - lastNote);
+                if (interval >= leapWarnSemitones) {
+                    const fromName = midiToNoteName(lastNote);
+                    const toName = midiToNoteName(midiEvent.note);
+                    await emitAside({
+                        text: `Big leap: ${fromName} → ${toName} (${interval} semitones). Prepare your hand position.`,
+                        priority: "med",
+                        reason: "difficulty-warning",
+                        source: `note-${eventIndex}`,
+                        tags: ["piano-teacher", "midi-feedback", "leap"],
+                    });
+                }
+            }
+            lastNote = midiEvent.note;
+            // ── Dense chord warning (first note of a dense cluster only) ──
+            if (warnOnDifficult && chordDensityMap.has(eventIndex - 1)) {
+                const density = chordDensityMap.get(eventIndex - 1);
+                // Only warn on the first note of each dense cluster
+                const prevInSameCluster = eventIndex >= 2 &&
+                    events[eventIndex - 2] &&
+                    Math.abs(events[eventIndex - 2].time - midiEvent.time) < 0.01;
+                if (!prevInSameCluster) {
+                    await emitAside({
+                        text: `Dense chord ahead: ${density} notes at once. Spread your fingers.`,
+                        priority: "med",
+                        reason: "difficulty-warning",
+                        source: `note-${eventIndex}`,
+                        tags: ["piano-teacher", "midi-feedback", "chord"],
+                    });
+                }
+            }
+            // ── Periodic voice encouragement ──
+            if (voiceInterval > 0 && noteCount % voiceInterval === 0) {
+                const phrase = ENCOURAGEMENTS[noteCount % ENCOURAGEMENTS.length];
+                await emitVoice({
+                    text: phrase,
+                    voice,
+                    speed: speechSpeed,
+                    blocking: false,
+                });
+            }
+        },
+        async onKeyMoment(moment) {
+            // MIDI files don't have key moments, but support the interface
+            await emitVoice({
+                text: moment,
+                voice,
+                speed: speechSpeed,
+                blocking: false,
+            });
+        },
+        async onSongComplete(eventsPlayed, songTitle) {
+            const durationMin = Math.round(midi.durationSeconds / 60);
+            await emitVoice({
+                text: `Great work on ${songTitle}! ${eventsPlayed} notes over ${durationMin > 0 ? `${durationMin} minute${durationMin !== 1 ? "s" : ""}` : "less than a minute"}.`,
+                voice,
+                speed: speechSpeed,
+                blocking: false,
+            });
+            await emitAside({
+                text: `Session complete: ${songTitle} — ${eventsPlayed} notes played at ${midi.bpm} BPM.`,
+                priority: "low",
+                reason: "session-complete",
+                tags: ["piano-teacher", "midi-feedback", "completion"],
+            });
+        },
+        async push(interjection) {
+            await emitAside({
+                text: interjection.text,
+                priority: interjection.priority,
+                reason: interjection.reason,
+                source: interjection.source,
+                tags: ["piano-teacher", "midi-feedback", interjection.reason],
+            });
+        },
+    };
+}
+//# sourceMappingURL=midi-feedback.js.map

package/dist/teaching/midi-feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-feedback.js","sourceRoot":"","sources":["../../src/teaching/midi-feedback.ts"],"names":[],"mappings":"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"}

package/dist/teaching/sing-on-midi.d.ts

@@ -0,0 +1,77 @@
+import type { ParsedMidi, MidiNoteEvent } from "../midi/types.js";
+import type { TeachingHook, VoiceDirective, VoiceSink } from "../types.js";
+import type { SingAlongMode } from "../note-parser.js";
+/**
+ * Convert a MIDI note number to a singable syllable.
+ *
+ * - "note-names": "C4", "F#5", "Bb3"
+ * - "solfege": "Do", "Re", "Mi" (based on pitch class, not key)
+ * - "syllables": always "da"
+ * - "contour": not applicable for individual notes (returns note name)
+ */
+export declare function midiNoteToSingable(note: number, mode: SingAlongMode): string;
+/**
+ * Convert a cluster (chord or single note) to singable text.
+ *
+ * - Single note: just the syllable
+ * - Chord: syllables joined with " and " (e.g. "Do and Mi and Sol")
+ * - Contour mode between clusters: "up", "down", "same"
+ */
+export declare function clusterToSingable(events: readonly MidiNoteEvent[], mode: SingAlongMode): string;
+/**
+ * Generate contour direction between two clusters.
+ * Compares the highest note of each cluster.
+ */
+export declare function contourDirection(prev: readonly MidiNoteEvent[], curr: readonly MidiNoteEvent[]): string;
+/**
+ * Which notes to sing from each cluster:
+ * - "all" — sing every note (chords become "C and E and G")
+ * - "melody-only" — highest note per cluster (typical RH melody)
+ * - "harmony" — lowest note per cluster (bass line / LH)
+ */
+export type SingVoiceFilter = "all" | "melody-only" | "harmony";
+/**
+ * Filter a cluster of events based on the voice filter.
+ * Returns a subset of events to sing.
+ */
+export declare function filterClusterForVoice(events: readonly MidiNoteEvent[], filter: SingVoiceFilter): MidiNoteEvent[];
+export interface SingOnMidiOptions {
+    /** Singable mode. Default: "note-names". */
+    mode?: SingAlongMode;
+    /** Voice filter: which notes to sing per cluster. Default: "all". */
+    voiceFilter?: SingVoiceFilter;
+    /** Voice preset for speech synthesis. */
+    voice?: string;
+    /** Speech speed multiplier. Default: 1.0. */
+    speechSpeed?: number;
+    /** Whether to announce cluster/beat numbers. Default: false. */
+    announcePosition?: boolean;
+    /** Max clusters to announce per batch (to avoid overwhelming). Default: 8. */
+    batchSize?: number;
+    /**
+     * Threshold in ms for grouping simultaneous notes into a chord.
+     * Default: 10ms.
+     */
+    chordThresholdMs?: number;
+    /** Whether the voice should block before piano plays. Default: true. */
+    blocking?: boolean;
+}
+/**
+ * Create a teaching hook that sings along with MIDI file playback.
+ *
+ * Pre-processes the ParsedMidi events into time clusters (chords/single notes),
+ * then emits singable text as each cluster is reached during playback.
+ *
+ * The hook implements TeachingHook so it can be composed with other hooks
+ * via composeTeachingHooks.
+ *
+ * @param sink - Voice sink to emit speech directives.
+ * @param midi - Parsed MIDI file data.
+ * @param options - Configuration.
+ * @returns Teaching hook with `.directives` for inspection.
+ */
+export declare function createSingOnMidiHook(sink: VoiceSink, midi: ParsedMidi, options?: SingOnMidiOptions): TeachingHook & {
+    directives: VoiceDirective[];
+    clusters: MidiNoteEvent[][];
+};
+//# sourceMappingURL=sing-on-midi.d.ts.map

package/dist/teaching/sing-on-midi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sing-on-midi.d.ts","sourceRoot":"","sources":["../../src/teaching/sing-on-midi.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAWvD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAW5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,aAAa,GAClB,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,IAAI,EAAE,SAAS,aAAa,EAAE,GAC7B,MAAM,CAOR;AAID;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,aAAa,GAAG,SAAS,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,MAAM,EAAE,eAAe,GACtB,aAAa,EAAE,CAmBjB;AAID,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,aAAa,CAAC;IAErB,qEAAqE;IACrE,WAAW,CAAC,EAAE,eAAe,CAAC;IAE9B,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,iBAAsB,GAC9B,YAAY,GAAG;IAAE,UAAU,EAAE,cAAc,EAAE,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAA;CAAE,CA2F9E"}