@mcptoolshop/ai_jam_session 0.1.0

package/dist/songs/loader.js

@@ -0,0 +1,90 @@
+// ─── Song Loader ────────────────────────────────────────────────────────────
+//
+// Loads SongEntry objects from JSON files at runtime.
+// Two directories: builtin (ships with package) + user (~/.pianoai/songs/).
+// No compilation needed to add songs — just drop a .json file.
+// ─────────────────────────────────────────────────────────────────────────────
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { validateSong, registerSong, clearRegistry } from "./registry.js";
+/**
+ * Load all .json song files from a directory.
+ * Validates each file and returns valid SongEntry objects.
+ * Skips (with warning) any files that fail validation.
+ */
+export function loadSongsFromDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter(f => f.endsWith(".json"));
+    const songs = [];
+    for (const file of files) {
+        try {
+            const song = loadSongFile(join(dir, file));
+            songs.push(song);
+        }
+        catch (err) {
+            console.error(`  SKIP ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return songs;
+}
+/**
+ * Load a single song from a JSON file.
+ * Validates the parsed object and returns a typed SongEntry.
+ */
+export function loadSongFile(filePath) {
+    const raw = JSON.parse(readFileSync(filePath, "utf8"));
+    const errors = validateSong(raw);
+    if (errors.length > 0) {
+        throw new Error(`Invalid song in ${basename(filePath)}:\n  - ${errors.join("\n  - ")}`);
+    }
+    return raw;
+}
+/**
+ * Save a SongEntry as a JSON file in the given directory.
+ * Creates the directory if it doesn't exist.
+ * Returns the full path to the saved file.
+ */
+export function saveSong(song, dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const filePath = join(dir, `${song.id}.json`);
+    writeFileSync(filePath, JSON.stringify(song, null, 2) + "\n", "utf8");
+    return filePath;
+}
+/**
+ * Initialize the song registry from builtin and optional user directories.
+ * Clears any existing registry entries first.
+ *
+ * @param builtinDir - Path to the builtin songs directory (ships with package)
+ * @param userDir - Optional path to user songs directory (default: ~/.pianoai/songs/)
+ */
+export function initializeRegistry(builtinDir, userDir) {
+    clearRegistry();
+    // Load builtin songs
+    const builtinSongs = loadSongsFromDir(builtinDir);
+    for (const song of builtinSongs) {
+        try {
+            registerSong(song);
+        }
+        catch (err) {
+            console.error(`  SKIP builtin ${song.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Load user songs (if directory exists)
+    if (userDir) {
+        const userSongs = loadSongsFromDir(userDir);
+        for (const song of userSongs) {
+            try {
+                registerSong(song);
+            }
+            catch (err) {
+                console.error(`  SKIP user ${song.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    const total = builtinSongs.length + (userDir ? loadSongsFromDir(userDir).length : 0);
+    console.error(`Song registry initialized: ${builtinSongs.length} builtin songs loaded`);
+}
+//# sourceMappingURL=loader.js.map

package/dist/songs/loader.js.map

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

package/dist/songs/midi/hands.d.ts

@@ -0,0 +1,46 @@
+import type { ResolvedNote } from "./types.js";
+export declare const DEFAULT_SPLIT_POINT = 60;
+export declare const DEFAULT_CHORD_TOLERANCE = 10;
+/** Result of splitting notes into two hands. */
+export interface HandSplit {
+    rightHand: ResolvedNote[];
+    leftHand: ResolvedNote[];
+}
+/**
+ * Separate notes into right hand and left hand based on split point.
+ */
+export declare function separateHands(notes: ResolvedNote[], splitPoint?: number): HandSplit;
+/**
+ * Group simultaneous notes (within a tick tolerance window) into chords.
+ */
+export declare function groupIntoChords(notes: ResolvedNote[], tolerance?: number): ResolvedNote[][];
+/**
+ * Detect if a group of notes forms a chord (2+ simultaneous notes).
+ */
+export declare function isChord(group: ResolvedNote[]): boolean;
+/**
+ * Convert a MIDI note number to scientific pitch notation.
+ * 60 → "C4", 69 → "A4", 48 → "C3"
+ */
+export declare function midiNoteToScientific(noteNumber: number): string;
+/**
+ * Convert ticks duration to a note duration suffix.
+ */
+export declare function ticksToDuration(ticks: number, ticksPerBeat: number): string;
+/**
+ * Format a single note as scientific notation with duration suffix.
+ */
+export declare function formatNote(note: ResolvedNote, ticksPerBeat: number): string;
+/**
+ * Format a chord group to the string representation.
+ * Single note: "C4:q"
+ * Chord: "C4 E4 G4:q" (sorted low to high, duration from longest note)
+ */
+export declare function chordToString(chord: ResolvedNote[], ticksPerBeat: number): string;
+/**
+ * Format a hand's notes into a single notation string.
+ * Groups into chords, formats each, joins with spaces.
+ * Returns "R:w" (whole rest) if the hand has no notes.
+ */
+export declare function formatHand(notes: ResolvedNote[], ticksPerBeat: number, chordTolerance?: number): string;
+//# sourceMappingURL=hands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hands.d.ts","sourceRoot":"","sources":["../../../src/songs/midi/hands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAM1C,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EAAE,EACrB,UAAU,GAAE,MAA4B,GACvC,SAAS,CAaX;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EAAE,EACrB,SAAS,GAAE,MAAgC,GAC1C,YAAY,EAAE,EAAE,CAgBlB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAEtD;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAoB3E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUjF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,MAAgC,GAC/C,MAAM,CAIR"}

package/dist/songs/midi/hands.js

@@ -0,0 +1,134 @@
+// ─── Hand Separation & Chord Detection ───────────────────────────────────────
+//
+// Splits notes into right hand / left hand by a configurable split point,
+// groups simultaneous notes into chords, and formats them as notation strings.
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── Constants ───────────────────────────────────────────────────────────────
+export const DEFAULT_SPLIT_POINT = 60; // Middle C (C4)
+export const DEFAULT_CHORD_TOLERANCE = 10; // ticks
+const NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+/**
+ * Separate notes into right hand and left hand based on split point.
+ */
+export function separateHands(notes, splitPoint = DEFAULT_SPLIT_POINT) {
+    const rightHand = [];
+    const leftHand = [];
+    for (const note of notes) {
+        if (note.noteNumber >= splitPoint) {
+            rightHand.push(note);
+        }
+        else {
+            leftHand.push(note);
+        }
+    }
+    return { rightHand, leftHand };
+}
+/**
+ * Group simultaneous notes (within a tick tolerance window) into chords.
+ */
+export function groupIntoChords(notes, tolerance = DEFAULT_CHORD_TOLERANCE) {
+    if (notes.length === 0)
+        return [];
+    const groups = [];
+    let current = [notes[0]];
+    for (let i = 1; i < notes.length; i++) {
+        if (notes[i].startTick - current[0].startTick <= tolerance) {
+            current.push(notes[i]);
+        }
+        else {
+            groups.push(current);
+            current = [notes[i]];
+        }
+    }
+    groups.push(current);
+    return groups;
+}
+/**
+ * Detect if a group of notes forms a chord (2+ simultaneous notes).
+ */
+export function isChord(group) {
+    return group.length > 1;
+}
+// ─── Note Formatting ─────────────────────────────────────────────────────────
+/**
+ * Convert a MIDI note number to scientific pitch notation.
+ * 60 → "C4", 69 → "A4", 48 → "C3"
+ */
+export function midiNoteToScientific(noteNumber) {
+    const octave = Math.floor(noteNumber / 12) - 1;
+    const name = NOTE_NAMES[noteNumber % 12];
+    return `${name}${octave}`;
+}
+/**
+ * Convert ticks duration to a note duration suffix.
+ */
+export function ticksToDuration(ticks, ticksPerBeat) {
+    const ratio = ticks / ticksPerBeat;
+    if (Math.abs(ratio - 4) < 0.15)
+        return "w";
+    if (Math.abs(ratio - 3) < 0.15)
+        return "h.";
+    if (Math.abs(ratio - 2) < 0.15)
+        return "h";
+    if (Math.abs(ratio - 1.5) < 0.15)
+        return "q.";
+    if (Math.abs(ratio - 4 / 3) < 0.1)
+        return "ht";
+    if (Math.abs(ratio - 1) < 0.15)
+        return "q";
+    if (Math.abs(ratio - 0.75) < 0.05)
+        return "e.";
+    if (Math.abs(ratio - 2 / 3) < 0.08)
+        return "qt";
+    if (Math.abs(ratio - 0.5) < 0.1)
+        return "e";
+    if (Math.abs(ratio - 1 / 3) < 0.06)
+        return "et";
+    if (Math.abs(ratio - 0.25) < 0.06)
+        return "s";
+    if (ratio >= 3)
+        return "w";
+    if (ratio >= 1.5)
+        return "h";
+    if (ratio >= 0.75)
+        return "q";
+    if (ratio >= 0.375)
+        return "e";
+    return "s";
+}
+/**
+ * Format a single note as scientific notation with duration suffix.
+ */
+export function formatNote(note, ticksPerBeat) {
+    const name = midiNoteToScientific(note.noteNumber);
+    const dur = ticksToDuration(note.durationTicks, ticksPerBeat);
+    return `${name}:${dur}`;
+}
+/**
+ * Format a chord group to the string representation.
+ * Single note: "C4:q"
+ * Chord: "C4 E4 G4:q" (sorted low to high, duration from longest note)
+ */
+export function chordToString(chord, ticksPerBeat) {
+    if (chord.length === 1)
+        return formatNote(chord[0], ticksPerBeat);
+    const maxDur = Math.max(...chord.map(n => n.durationTicks));
+    const dur = ticksToDuration(maxDur, ticksPerBeat);
+    const noteNames = [...chord]
+        .sort((a, b) => a.noteNumber - b.noteNumber)
+        .map(n => midiNoteToScientific(n.noteNumber))
+        .join(" ");
+    return `${noteNames}:${dur}`;
+}
+/**
+ * Format a hand's notes into a single notation string.
+ * Groups into chords, formats each, joins with spaces.
+ * Returns "R:w" (whole rest) if the hand has no notes.
+ */
+export function formatHand(notes, ticksPerBeat, chordTolerance = DEFAULT_CHORD_TOLERANCE) {
+    if (notes.length === 0)
+        return "R:w";
+    const chords = groupIntoChords(notes, chordTolerance);
+    return chords.map(c => chordToString(c, ticksPerBeat)).join(" ");
+}
+//# sourceMappingURL=hands.js.map

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

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

package/dist/songs/midi/ingest.d.ts

@@ -0,0 +1,8 @@
+import type { SongEntry } from "../types.js";
+import type { SongConfig } from "../config/schema.js";
+/**
+ * Convert a MIDI buffer + human-authored config into a complete SongEntry.
+ */
+export declare function midiToSongEntry(midiBuffer: Uint8Array, config: SongConfig): SongEntry;
+export { midiNoteToScientific } from "./hands.js";
+//# sourceMappingURL=ingest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../../src/songs/midi/ingest.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAqBtD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU,GACjB,SAAS,CAkDX;AAGD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/songs/midi/ingest.js

@@ -0,0 +1,191 @@
+// ─── MIDI → SongEntry Converter ──────────────────────────────────────────────
+//
+// Parses a standard MIDI file and merges it with a human-authored SongConfig
+// to produce a complete SongEntry ready for the registry.
+//
+// The MIDI provides: notes, timing, duration, structure.
+// The config provides: metadata, musical language, teaching notes, fingering.
+// ─────────────────────────────────────────────────────────────────────────────
+import { parseMidi } from "midi-file";
+import { ticksPerMeasure, computeTotalMeasures, sliceIntoMeasures, resolveTimeSignature, } from "./measures.js";
+import { separateHands, formatHand, DEFAULT_SPLIT_POINT, } from "./hands.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_TEMPO = 120;
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Convert a MIDI buffer + human-authored config into a complete SongEntry.
+ */
+export function midiToSongEntry(midiBuffer, config) {
+    const midi = parseMidi(midiBuffer);
+    const tpb = midi.header.ticksPerBeat ?? 480;
+    const splitPoint = config.splitPoint ?? DEFAULT_SPLIT_POINT;
+    // 1. Collect tempo + time signature events across all tracks
+    const tempoEvents = extractTempoEvents(midi);
+    const timeSigEvents = extractTimeSigEvents(midi);
+    // 2. Resolve all notes to absolute ticks + durations
+    const notes = resolveNotes(midi);
+    // 3. Determine effective tempo and time signature
+    const effectiveTempo = config.tempo ?? tempoFromEvents(tempoEvents);
+    const effectiveTimeSig = resolveTimeSignature(timeSigEvents, config.timeSignature);
+    // 4. Compute ticks per measure
+    const tpm = ticksPerMeasure(tpb, effectiveTimeSig.numerator, effectiveTimeSig.denominator);
+    // 5. Determine total measures
+    const totalMeasures = computeTotalMeasures(notes, tpm);
+    // 6. Slice notes into measure buckets
+    const buckets = sliceIntoMeasures(notes, totalMeasures, tpm);
+    // 7. Build measure objects with hand separation + formatting
+    const measures = buildMeasures(buckets, tpb, splitPoint, config);
+    // 8. Compute duration in seconds
+    const lastNoteTick = notes.length > 0
+        ? Math.max(...notes.map(n => n.startTick + n.durationTicks))
+        : 0;
+    const durationSeconds = ticksToSeconds(lastNoteTick, tempoEvents, tpb);
+    return {
+        id: config.id,
+        title: config.title,
+        genre: config.genre,
+        composer: config.composer,
+        arranger: config.arranger,
+        difficulty: config.difficulty,
+        key: config.key,
+        tempo: effectiveTempo,
+        timeSignature: `${effectiveTimeSig.numerator}/${effectiveTimeSig.denominator}`,
+        durationSeconds: Math.round(durationSeconds),
+        musicalLanguage: config.musicalLanguage,
+        measures,
+        tags: config.tags,
+        source: config.source,
+    };
+}
+// Re-export for barrel convenience
+export { midiNoteToScientific } from "./hands.js";
+// ─── Internal: Extract Events ────────────────────────────────────────────────
+function extractTempoEvents(midi) {
+    const events = [];
+    for (const track of midi.tracks) {
+        let tick = 0;
+        for (const event of track) {
+            tick += event.deltaTime;
+            if (event.type === "setTempo") {
+                events.push({ tick, microsecondsPerBeat: event.microsecondsPerBeat });
+            }
+        }
+    }
+    events.sort((a, b) => a.tick - b.tick);
+    return events;
+}
+function extractTimeSigEvents(midi) {
+    const events = [];
+    for (const track of midi.tracks) {
+        let tick = 0;
+        for (const event of track) {
+            tick += event.deltaTime;
+            if (event.type === "timeSignature") {
+                events.push({
+                    tick,
+                    numerator: event.numerator,
+                    denominator: Math.pow(2, event.denominator),
+                });
+            }
+        }
+    }
+    events.sort((a, b) => a.tick - b.tick);
+    return events;
+}
+/** Get the initial tempo from MIDI events. */
+function tempoFromEvents(events) {
+    if (events.length === 0)
+        return DEFAULT_TEMPO;
+    return Math.round(60_000_000 / events[0].microsecondsPerBeat);
+}
+// ─── Internal: Resolve Notes ─────────────────────────────────────────────────
+/** Flatten all tracks into resolved notes with absolute tick positions. */
+function resolveNotes(midi) {
+    const notes = [];
+    for (const track of midi.tracks) {
+        let tick = 0;
+        const pending = new Map();
+        for (const event of track) {
+            tick += event.deltaTime;
+            if (event.type === "noteOn" && event.velocity > 0) {
+                const key = `${event.channel}:${event.noteNumber}`;
+                pending.set(key, {
+                    startTick: tick,
+                    velocity: event.velocity,
+                    channel: event.channel,
+                    noteNumber: event.noteNumber,
+                });
+            }
+            else if (event.type === "noteOff" ||
+                (event.type === "noteOn" && event.velocity === 0)) {
+                const key = `${event.channel}:${event.noteNumber}`;
+                const start = pending.get(key);
+                if (start) {
+                    notes.push({
+                        noteNumber: start.noteNumber,
+                        startTick: start.startTick,
+                        durationTicks: tick - start.startTick,
+                        velocity: start.velocity,
+                        channel: start.channel,
+                    });
+                    pending.delete(key);
+                }
+            }
+        }
+    }
+    notes.sort((a, b) => a.startTick - b.startTick || a.noteNumber - b.noteNumber);
+    return notes;
+}
+// ─── Internal: Build Measures ────────────────────────────────────────────────
+/** Build Measure objects from measure buckets. */
+function buildMeasures(buckets, ticksPerBeat, splitPoint, config) {
+    const overrides = new Map();
+    if (config.measureOverrides) {
+        for (const ov of config.measureOverrides) {
+            overrides.set(ov.measure, ov);
+        }
+    }
+    return buckets.map(bucket => {
+        const { rightHand, leftHand } = separateHands(bucket.notes, splitPoint);
+        const measure = {
+            number: bucket.number,
+            rightHand: formatHand(rightHand, ticksPerBeat),
+            leftHand: formatHand(leftHand, ticksPerBeat),
+        };
+        const ov = overrides.get(bucket.number);
+        if (ov?.fingering)
+            measure.fingering = ov.fingering;
+        if (ov?.teachingNote)
+            measure.teachingNote = ov.teachingNote;
+        if (ov?.dynamics)
+            measure.dynamics = ov.dynamics;
+        if (ov?.tempoOverride)
+            measure.tempoOverride = ov.tempoOverride;
+        return measure;
+    });
+}
+// ─── Internal: Tick-to-Time Conversion ───────────────────────────────────────
+/** Convert a tick position to seconds, respecting tempo changes. */
+function ticksToSeconds(targetTick, tempoEvents, ticksPerBeat) {
+    let seconds = 0;
+    let currentTick = 0;
+    let microsecondsPerBeat = tempoEvents.length > 0
+        ? tempoEvents[0].microsecondsPerBeat
+        : 500_000; // 120 BPM default
+    for (const event of tempoEvents) {
+        if (event.tick >= targetTick)
+            break;
+        if (event.tick > currentTick) {
+            const deltaTicks = event.tick - currentTick;
+            seconds += (deltaTicks / ticksPerBeat) * (microsecondsPerBeat / 1_000_000);
+            currentTick = event.tick;
+        }
+        microsecondsPerBeat = event.microsecondsPerBeat;
+    }
+    if (currentTick < targetTick) {
+        const deltaTicks = targetTick - currentTick;
+        seconds += (deltaTicks / ticksPerBeat) * (microsecondsPerBeat / 1_000_000);
+    }
+    return seconds;
+}
+//# sourceMappingURL=ingest.js.map

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

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

package/dist/songs/midi/measures.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedNote, TimeSigEvent } from "./types.js";
+/** A bucket of notes belonging to a single measure. */
+export interface MeasureBucket {
+    /** 1-based measure number. */
+    number: number;
+    /** Absolute tick where this measure starts. */
+    startTick: number;
+    /** Absolute tick where this measure ends. */
+    endTick: number;
+    /** Notes whose startTick falls within this measure. */
+    notes: ResolvedNote[];
+}
+/**
+ * Compute ticks per measure for a given time signature.
+ */
+export declare function ticksPerMeasure(ticksPerBeat: number, numerator: number, denominator: number): number;
+/**
+ * Determine total number of measures needed to contain all notes.
+ */
+export declare function computeTotalMeasures(notes: ResolvedNote[], tpm: number): number;
+/**
+ * Slice notes into measure buckets.
+ */
+export declare function sliceIntoMeasures(notes: ResolvedNote[], totalMeasures: number, tpm: number): MeasureBucket[];
+/**
+ * Parse a time signature string like "4/4" or "3/4".
+ * Returns { numerator, denominator } or defaults to 4/4 on invalid input.
+ */
+export declare function parseTimeSignature(timeSig?: string): {
+    numerator: number;
+    denominator: number;
+};
+/**
+ * Get effective time signature from MIDI events or config string.
+ * Config string takes priority over MIDI events.
+ */
+export declare function resolveTimeSignature(events: TimeSigEvent[], configTimeSig?: string): {
+    numerator: number;
+    denominator: number;
+};
+//# sourceMappingURL=measures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"measures.d.ts","sourceRoot":"","sources":["../../../src/songs/midi/measures.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI7D,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAID;;GAEG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EAAE,EACrB,GAAG,EAAE,MAAM,GACV,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EAAE,EACrB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,GACV,aAAa,EAAE,CAgBjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAO5C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EAAE,EACtB,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAM5C"}

package/dist/songs/midi/measures.js

@@ -0,0 +1,64 @@
+// ─── Measure Slicing ─────────────────────────────────────────────────────────
+//
+// Slices a flat array of resolved notes into measure buckets based on
+// time signature and ticks-per-beat.
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Compute ticks per measure for a given time signature.
+ */
+export function ticksPerMeasure(ticksPerBeat, numerator, denominator) {
+    return ticksPerBeat * numerator * (4 / denominator);
+}
+/**
+ * Determine total number of measures needed to contain all notes.
+ */
+export function computeTotalMeasures(notes, tpm) {
+    if (notes.length === 0)
+        return 1;
+    const lastNoteTick = Math.max(...notes.map(n => n.startTick + n.durationTicks));
+    return Math.max(1, Math.ceil(lastNoteTick / tpm));
+}
+/**
+ * Slice notes into measure buckets.
+ */
+export function sliceIntoMeasures(notes, totalMeasures, tpm) {
+    const buckets = [];
+    for (let m = 0; m < totalMeasures; m++) {
+        const startTick = m * tpm;
+        const endTick = (m + 1) * tpm;
+        buckets.push({
+            number: m + 1,
+            startTick,
+            endTick,
+            notes: notes.filter(n => n.startTick >= startTick && n.startTick < endTick),
+        });
+    }
+    return buckets;
+}
+/**
+ * Parse a time signature string like "4/4" or "3/4".
+ * Returns { numerator, denominator } or defaults to 4/4 on invalid input.
+ */
+export function parseTimeSignature(timeSig) {
+    if (!timeSig)
+        return { numerator: 4, denominator: 4 };
+    const parts = timeSig.split("/").map(Number);
+    if (parts.length === 2 && parts[0] > 0 && parts[1] > 0) {
+        return { numerator: parts[0], denominator: parts[1] };
+    }
+    return { numerator: 4, denominator: 4 };
+}
+/**
+ * Get effective time signature from MIDI events or config string.
+ * Config string takes priority over MIDI events.
+ */
+export function resolveTimeSignature(events, configTimeSig) {
+    if (configTimeSig)
+        return parseTimeSignature(configTimeSig);
+    if (events.length > 0) {
+        return { numerator: events[0].numerator, denominator: events[0].denominator };
+    }
+    return { numerator: 4, denominator: 4 };
+}
+//# sourceMappingURL=measures.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"measures.js","sourceRoot":"","sources":["../../../src/songs/midi/measures.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,sEAAsE;AACtE,qCAAqC;AACrC,gFAAgF;AAkBhF,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAoB,EACpB,SAAiB,EACjB,WAAmB;IAEnB,OAAO,YAAY,GAAG,SAAS,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAqB,EACrB,GAAW;IAEX,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAqB,EACrB,aAAqB,EACrB,GAAW;IAEX,MAAM,OAAO,GAAoB,EAAE,CAAC;IAEpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAE9B,OAAO,CAAC,IAAI,CAAC;YACX,MAAM,EAAE,CAAC,GAAG,CAAC;YACb,SAAS;YACT,OAAO;YACP,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,SAAS,IAAI,CAAC,CAAC,SAAS,GAAG,OAAO,CAAC;SAC5E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAgB;IAEhB,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,aAAsB;IAEtB,IAAI,aAAa;QAAE,OAAO,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,25 @@
+/** A resolved note with absolute timing from MIDI. */
+export interface ResolvedNote {
+    /** MIDI note number 0-127. */
+    noteNumber: number;
+    /** Start time in ticks from the beginning. */
+    startTick: number;
+    /** Duration in ticks. */
+    durationTicks: number;
+    /** Velocity 0-127. */
+    velocity: number;
+    /** MIDI channel. */
+    channel: number;
+}
+/** A tempo change event with absolute tick position. */
+export interface IngestTempoEvent {
+    tick: number;
+    microsecondsPerBeat: number;
+}
+/** A time signature event with absolute tick position. */
+export interface TimeSigEvent {
+    tick: number;
+    numerator: number;
+    denominator: number;
+}
+//# sourceMappingURL=types.d.ts.map