@mcptoolshop/ai_jam_session 0.1.0

package/dist/songs/midi/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/songs/midi/types.ts"],"names":[],"mappings":"AAOA,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/songs/midi/types.js

@@ -0,0 +1,8 @@
+// ─── MIDI Ingest Types ──────────────────────────────────────────────────────
+//
+// Tick-based types for the MIDI-to-SongEntry conversion pipeline.
+// These are separate from src/midi/types.ts which uses seconds-based timing
+// for real-time playback.
+// ─────────────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/songs/midi/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/songs/midi/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,kEAAkE;AAClE,4EAA4E;AAC5E,0BAA0B;AAC1B,gFAAgF"}

package/dist/songs/registry.d.ts

@@ -0,0 +1,37 @@
+import type { SongEntry, Genre, Difficulty, SearchOptions, RegistryStats } from "./types.js";
+/**
+ * Register a song in the global registry.
+ * Throws if the ID is already taken or validation fails.
+ */
+export declare function registerSong(song: SongEntry): void;
+/**
+ * Register multiple songs at once.
+ */
+export declare function registerSongs(entries: SongEntry[]): void;
+/**
+ * Validate a single song entry. Returns an array of error messages (empty = valid).
+ */
+export declare function validateSong(song: SongEntry): string[];
+/**
+ * Validate the entire registry. Throws on first invalid song.
+ */
+export declare function validateRegistry(): void;
+/** Get a song by its unique ID. */
+export declare function getSong(id: string): SongEntry | undefined;
+/** Get all registered songs. */
+export declare function getAllSongs(): SongEntry[];
+/** Get all songs in a specific genre. */
+export declare function getSongsByGenre(genre: Genre): SongEntry[];
+/** Get all songs at a specific difficulty level. */
+export declare function getSongsByDifficulty(difficulty: Difficulty): SongEntry[];
+/**
+ * Search songs with flexible filtering.
+ * The `query` field does a case-insensitive match against title, composer, tags,
+ * and musicalLanguage.description.
+ */
+export declare function searchSongs(options: SearchOptions): SongEntry[];
+/** Get summary statistics about the registry. */
+export declare function getStats(): RegistryStats;
+/** Clear all registered songs. Used when reloading or in tests. */
+export declare function clearRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/songs/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/songs/registry.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AASpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAWlD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAIxD;AAID;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAuFtD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAID,mCAAmC;AACnC,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEzD;AAED,gCAAgC;AAChC,wBAAgB,WAAW,IAAI,SAAS,EAAE,CAEzC;AAED,yCAAyC;AACzC,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAAE,CAEzD;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,CAExE;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,EAAE,CAsC/D;AAID,iDAAiD;AACjD,wBAAgB,QAAQ,IAAI,aAAa,CAsBxC;AAID,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/songs/registry.js

@@ -0,0 +1,197 @@
+// ─── Song Registry ──────────────────────────────────────────────────────────
+//
+// Single source of truth for all songs loaded at runtime.
+// Songs are loaded from JSON files (builtin + user directories).
+// The registry provides validation, search, filtering, and stats.
+// ─────────────────────────────────────────────────────────────────────────────
+import { GENRES, DIFFICULTIES } from "./types.js";
+// ─── Internal state ─────────────────────────────────────────────────────────
+const songs = new Map();
+// ─── Registration ───────────────────────────────────────────────────────────
+/**
+ * Register a song in the global registry.
+ * Throws if the ID is already taken or validation fails.
+ */
+export function registerSong(song) {
+    const errors = validateSong(song);
+    if (errors.length > 0) {
+        throw new Error(`Invalid song "${song.id}":\n  - ${errors.join("\n  - ")}`);
+    }
+    if (songs.has(song.id)) {
+        throw new Error(`Duplicate song ID: "${song.id}"`);
+    }
+    songs.set(song.id, song);
+}
+/**
+ * Register multiple songs at once.
+ */
+export function registerSongs(entries) {
+    for (const song of entries) {
+        registerSong(song);
+    }
+}
+// ─── Validation ─────────────────────────────────────────────────────────────
+/**
+ * Validate a single song entry. Returns an array of error messages (empty = valid).
+ */
+export function validateSong(song) {
+    const errors = [];
+    if (!song.id || typeof song.id !== "string") {
+        errors.push("id is required and must be a non-empty string");
+    }
+    else if (!/^[a-z0-9-]+$/.test(song.id)) {
+        errors.push("id must be kebab-case (lowercase alphanumeric + hyphens)");
+    }
+    if (!song.title || typeof song.title !== "string") {
+        errors.push("title is required");
+    }
+    if (!GENRES.includes(song.genre)) {
+        errors.push(`genre must be one of: ${GENRES.join(", ")}`);
+    }
+    if (!DIFFICULTIES.includes(song.difficulty)) {
+        errors.push(`difficulty must be one of: ${DIFFICULTIES.join(", ")}`);
+    }
+    if (!song.key || typeof song.key !== "string") {
+        errors.push("key signature is required");
+    }
+    if (typeof song.tempo !== "number" || song.tempo < 20 || song.tempo > 300) {
+        errors.push("tempo must be a number between 20 and 300 BPM");
+    }
+    if (!song.timeSignature || !/^\d+\/\d+$/.test(song.timeSignature)) {
+        errors.push('timeSignature must be in "N/N" format');
+    }
+    if (typeof song.durationSeconds !== "number" ||
+        song.durationSeconds <= 0) {
+        errors.push("durationSeconds must be a positive number");
+    }
+    // Musical language layer
+    if (!song.musicalLanguage) {
+        errors.push("musicalLanguage is required");
+    }
+    else {
+        if (!song.musicalLanguage.description) {
+            errors.push("musicalLanguage.description is required");
+        }
+        if (!song.musicalLanguage.structure) {
+            errors.push("musicalLanguage.structure is required");
+        }
+        if (!Array.isArray(song.musicalLanguage.keyMoments) ||
+            song.musicalLanguage.keyMoments.length === 0) {
+            errors.push("musicalLanguage.keyMoments must have at least one entry");
+        }
+        if (!Array.isArray(song.musicalLanguage.teachingGoals) ||
+            song.musicalLanguage.teachingGoals.length === 0) {
+            errors.push("musicalLanguage.teachingGoals must have at least one entry");
+        }
+        if (!Array.isArray(song.musicalLanguage.styleTips)) {
+            errors.push("musicalLanguage.styleTips must be an array");
+        }
+    }
+    // Measures
+    if (!Array.isArray(song.measures) || song.measures.length === 0) {
+        errors.push("measures must be a non-empty array");
+    }
+    else {
+        for (let i = 0; i < song.measures.length; i++) {
+            const m = song.measures[i];
+            if (typeof m.number !== "number" || m.number !== i + 1) {
+                errors.push(`measure[${i}].number should be ${i + 1}, got ${m.number}`);
+            }
+            if (!m.rightHand && !m.leftHand) {
+                errors.push(`measure[${i}] must have at least rightHand or leftHand`);
+            }
+        }
+    }
+    if (!Array.isArray(song.tags)) {
+        errors.push("tags must be an array");
+    }
+    return errors;
+}
+/**
+ * Validate the entire registry. Throws on first invalid song.
+ */
+export function validateRegistry() {
+    const allSongs = getAllSongs();
+    if (allSongs.length === 0) {
+        throw new Error("Registry is empty — no songs registered");
+    }
+    console.error(`Registry valid: ${allSongs.length} songs across ${new Set(allSongs.map((s) => s.genre)).size} genres.`);
+}
+// ─── Lookup ─────────────────────────────────────────────────────────────────
+/** Get a song by its unique ID. */
+export function getSong(id) {
+    return songs.get(id);
+}
+/** Get all registered songs. */
+export function getAllSongs() {
+    return [...songs.values()];
+}
+/** Get all songs in a specific genre. */
+export function getSongsByGenre(genre) {
+    return getAllSongs().filter((s) => s.genre === genre);
+}
+/** Get all songs at a specific difficulty level. */
+export function getSongsByDifficulty(difficulty) {
+    return getAllSongs().filter((s) => s.difficulty === difficulty);
+}
+// ─── Search ─────────────────────────────────────────────────────────────────
+/**
+ * Search songs with flexible filtering.
+ * The `query` field does a case-insensitive match against title, composer, tags,
+ * and musicalLanguage.description.
+ */
+export function searchSongs(options) {
+    let results = getAllSongs();
+    if (options.genre) {
+        results = results.filter((s) => s.genre === options.genre);
+    }
+    if (options.difficulty) {
+        results = results.filter((s) => s.difficulty === options.difficulty);
+    }
+    if (options.tags && options.tags.length > 0) {
+        const wanted = new Set(options.tags.map((t) => t.toLowerCase()));
+        results = results.filter((s) => s.tags.some((t) => wanted.has(t.toLowerCase())));
+    }
+    if (options.maxDuration !== undefined) {
+        results = results.filter((s) => s.durationSeconds <= options.maxDuration);
+    }
+    if (options.minDuration !== undefined) {
+        results = results.filter((s) => s.durationSeconds >= options.minDuration);
+    }
+    if (options.query) {
+        const q = options.query.toLowerCase();
+        results = results.filter((s) => s.title.toLowerCase().includes(q) ||
+            s.composer?.toLowerCase().includes(q) ||
+            s.tags.some((t) => t.toLowerCase().includes(q)) ||
+            s.musicalLanguage.description.toLowerCase().includes(q));
+    }
+    return results;
+}
+// ─── Stats ──────────────────────────────────────────────────────────────────
+/** Get summary statistics about the registry. */
+export function getStats() {
+    const allSongs = getAllSongs();
+    const byGenre = {};
+    for (const g of GENRES)
+        byGenre[g] = 0;
+    for (const s of allSongs)
+        byGenre[s.genre]++;
+    const byDifficulty = {};
+    for (const d of DIFFICULTIES)
+        byDifficulty[d] = 0;
+    for (const s of allSongs)
+        byDifficulty[s.difficulty]++;
+    const totalMeasures = allSongs.reduce((sum, s) => sum + s.measures.length, 0);
+    return {
+        totalSongs: allSongs.length,
+        byGenre,
+        byDifficulty,
+        totalMeasures,
+    };
+}
+// ─── Reset ──────────────────────────────────────────────────────────────────
+/** Clear all registered songs. Used when reloading or in tests. */
+export function clearRegistry() {
+    songs.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/songs/registry.js.map

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

package/dist/songs/types.d.ts

@@ -0,0 +1,99 @@
+/** Genres supported by the library. */
+export declare const GENRES: readonly ["classical", "jazz", "pop", "blues", "rock", "rnb", "latin", "film", "ragtime", "new-age"];
+export type Genre = (typeof GENRES)[number];
+/** Difficulty levels for song entries. */
+export declare const DIFFICULTIES: readonly ["beginner", "intermediate", "advanced"];
+export type Difficulty = (typeof DIFFICULTIES)[number];
+/** How notes are expressed in the measures array. */
+export type NoteFormat = "scientific" | "midi-number" | "letter";
+/**
+ * Human-readable musical context — the part an LLM reads to *understand*
+ * the song before deciding how to teach or perform it.
+ */
+export interface MusicalLanguage {
+    /** 1–3 sentence overview of the piece (mood, era, why it matters). */
+    description: string;
+    /** Musical structure: "ABA", "Verse-Chorus-Verse", "Rondo ABACA", etc. */
+    structure: string;
+    /** Notable moments an LLM can reference when teaching. */
+    keyMoments: string[];
+    /** Pedagogical notes: what the student will learn from this piece. */
+    teachingGoals: string[];
+    /** Style/feel hints for performance: "legato", "swing eighths", etc. */
+    styleTips: string[];
+}
+/**
+ * A single measure of piano music, code-ready for MIDI playback or analysis.
+ *
+ * Notes use scientific pitch notation by default: "C4", "F#5", "Bb3".
+ * Chords are space-separated: "C4 E4 G4".
+ * Rests are written as "R".
+ * Duration is encoded inline: "C4:q" (quarter), "E4:h" (half), "G4:w" (whole),
+ * "A4:e" (eighth), "B4:s" (sixteenth). Default is quarter if omitted.
+ */
+export interface Measure {
+    /** 1-based measure number. */
+    number: number;
+    /** Right-hand notes (treble clef). */
+    rightHand: string;
+    /** Left-hand notes (bass clef). */
+    leftHand: string;
+    /** Suggested fingering, e.g. "1-2-3-5" or "RH: 1-3-5, LH: 5-3-1". */
+    fingering?: string;
+    /** Per-measure teaching note the LLM can read aloud or display. */
+    teachingNote?: string;
+    /**
+     * Optional dynamics/expression mark for this measure.
+     * Standard markings: "pp", "p", "mp", "mf", "f", "ff", "crescendo", "decrescendo".
+     */
+    dynamics?: string;
+    /** Tempo override for this measure (rubato, ritardando, etc.). */
+    tempoOverride?: number;
+}
+export interface SongEntry {
+    /** Unique slug: kebab-case, e.g. "moonlight-sonata-mvt1". */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Genre — must be one of the 10 canonical genres. */
+    genre: Genre;
+    /** Composer or artist (undefined for traditional/anonymous). */
+    composer?: string;
+    /** Arranger (if this is a simplified or adapted version). */
+    arranger?: string;
+    /** Difficulty level. */
+    difficulty: Difficulty;
+    /** Key signature, e.g. "C major", "A minor", "Bb major". */
+    key: string;
+    /** Tempo in BPM (the default/starting tempo). */
+    tempo: number;
+    /** Time signature, e.g. "4/4", "3/4", "6/8". */
+    timeSignature: string;
+    /** Approximate duration in seconds at the given tempo. */
+    durationSeconds: number;
+    /** The LLM-readable musical language layer. */
+    musicalLanguage: MusicalLanguage;
+    /** Code-ready measure data for playback and analysis. */
+    measures: Measure[];
+    /** Freeform tags for search/filtering. */
+    tags: string[];
+    /** Source/attribution for the arrangement. */
+    source?: string;
+}
+/** Summary stats returned by the registry. */
+export interface RegistryStats {
+    totalSongs: number;
+    byGenre: Record<Genre, number>;
+    byDifficulty: Record<Difficulty, number>;
+    totalMeasures: number;
+}
+/** Search options for filtering songs. */
+export interface SearchOptions {
+    genre?: Genre;
+    difficulty?: Difficulty;
+    query?: string;
+    tags?: string[];
+    maxDuration?: number;
+    minDuration?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/songs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/songs/types.ts"],"names":[],"mappings":"AAaA,uCAAuC;AACvC,eAAO,MAAM,MAAM,sGAWT,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C,0CAA0C;AAC1C,eAAO,MAAM,YAAY,mDAAoD,CAAC;AAC9E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,qDAAqD;AACrD,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,aAAa,GAAG,QAAQ,CAAC;AAIjE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IAEpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAElB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB,sEAAsE;IACtE,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAEjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IAEX,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,KAAK,EAAE,KAAK,CAAC;IAEb,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,wBAAwB;IACxB,UAAU,EAAE,UAAU,CAAC;IAEvB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IAEZ,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IAEd,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IAExB,+CAA+C;IAC/C,eAAe,EAAE,eAAe,CAAC;IAEjC,yDAAyD;IACzD,QAAQ,EAAE,OAAO,EAAE,CAAC;IAEpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/songs/types.js

@@ -0,0 +1,27 @@
+// ─── Song Types ─────────────────────────────────────────────────────────────
+//
+// The hybrid format has three layers:
+//   1. Metadata   — structured JSON (genre, key, tempo, difficulty, etc.)
+//   2. Musical Language — human-readable descriptions for LLM reasoning
+//   3. Code-ready — measure-by-measure note data the runtime can consume
+//
+// An LLM can read the "musicalLanguage" block to explain a song to a student,
+// then use the "measures" array to drive MIDI playback or generate exercises.
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── Enums ──────────────────────────────────────────────────────────────────
+/** Genres supported by the library. */
+export const GENRES = [
+    "classical",
+    "jazz",
+    "pop",
+    "blues",
+    "rock",
+    "rnb",
+    "latin",
+    "film",
+    "ragtime",
+    "new-age",
+];
+/** Difficulty levels for song entries. */
+export const DIFFICULTIES = ["beginner", "intermediate", "advanced"];
+//# sourceMappingURL=types.js.map

package/dist/songs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/songs/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,sCAAsC;AACtC,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAEhF,+EAA+E;AAE/E,uCAAuC;AACvC,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,WAAW;IACX,MAAM;IACN,KAAK;IACL,OAAO;IACP,MAAM;IACN,KAAK;IACL,OAAO;IACP,MAAM;IACN,SAAS;IACT,SAAS;CACD,CAAC;AAIX,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,CAAU,CAAC"}

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

@@ -0,0 +1,36 @@
+import type { ParsedMidi } from "../midi/types.js";
+import type { TeachingHook, VoiceDirective, VoiceSink, AsideDirective, AsideSink } from "../types.js";
+import { PositionTracker } from "../playback/position.js";
+export interface LiveMidiFeedbackOptions {
+    /** Emit voice encouragement every N measures (default: 8). */
+    voiceInterval?: number;
+    /** Warn about wide range passages (default: true). */
+    warnOnWideRange?: boolean;
+    /** Warn about velocity shifts (default: true). */
+    warnOnVelocityShift?: boolean;
+    /** Warn about dense passages (default: true). */
+    warnOnDensity?: boolean;
+    /** Detect section boundaries (default: true). */
+    detectSections?: boolean;
+    /** Announce milestone percentages (default: true). */
+    announceMilestones?: boolean;
+    /** Voice preset. */
+    voice?: string;
+    /** Speech speed. Default: 1.0. */
+    speechSpeed?: number;
+}
+/**
+ * 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 declare function createLiveMidiFeedbackHook(voiceSink: VoiceSink, asideSink: AsideSink, midi: ParsedMidi, options?: LiveMidiFeedbackOptions): TeachingHook & {
+    voiceDirectives: VoiceDirective[];
+    asideDirectives: AsideDirective[];
+    tracker: PositionTracker;
+};
+//# sourceMappingURL=live-midi-feedback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-midi-feedback.d.ts","sourceRoot":"","sources":["../../src/teaching/live-midi-feedback.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AA0E1D,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,uBAA4B,GACpC,YAAY,GAAG;IAChB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,OAAO,EAAE,eAAe,CAAC;CAC1B,CAoMA"}