@datamoc/mw_games 0.22.0 → 0.23.0

package/dist/audio/humanize/GrooveConverter.js

@@ -0,0 +1,344 @@
+import { assertGrooveTemplate, subdivisionCount, subdivisionTicks, } from './Groove.js';
+/** every text field in a groove MIDI starts with this, so a stray song cannot impersonate one */
+const GROOVE_PREFIX = 'mwg-groove:';
+/** General MIDI's bass drum, chosen as the first slot's pitch so slots run up from it */
+const FIRST_SLOT_PITCH = 36;
+/** how many velocity units one unit of velocityFactor buys; fixes the whole valid range */
+const VELOCITY_SCALE = 64;
+const GRIDS = ['8n', '16n', '32n'];
+const encoder = new TextEncoder();
+function notShipped(format) {
+    throw new Error(`the ${format} format is not shipped: it is an undocumented proprietary container, and a guessed reader could load a different groove than the file holds`);
+}
+function ascii(text) {
+    return [...text].map((character) => character.charCodeAt(0) & 0x7f);
+}
+/** MIDI variable-length quantity: seven bits per byte, high bit set while more follow */
+function vlq(value) {
+    const bytes = [value & 0x7f];
+    let rest = value >>> 7;
+    while (rest > 0) {
+        bytes.unshift((rest & 0x7f) | 0x80);
+        rest >>>= 7;
+    }
+    return bytes;
+}
+function metaEvent(type, body) {
+    return [0xff, type, ...vlq(body.length), ...body];
+}
+function writeGrooveMidi(template) {
+    assertGrooveTemplate(template);
+    const { name, timeSignature, ppq, subdivision, offsets } = template;
+    const slots = subdivisionCount(timeSignature, subdivision);
+    const slotTicks = subdivisionTicks(ppq, subdivision);
+    if (ppq > 0x7fff)
+        throw new Error(`groove template "${name}": ppq ${ppq} does not fit MIDI's 15-bit division`);
+    if (FIRST_SLOT_PITCH + slots - 1 > 127)
+        throw new Error(`groove template "${name}": ${slots} slots need pitches up to ${FIRST_SLOT_PITCH + slots - 1}, past MIDI's top note of 127`);
+    const microseconds = Math.round(60_000_000 / template.tempoBpm);
+    if (microseconds < 1 || microseconds > 0xffffff)
+        throw new Error(`groove template "${name}": tempoBpm ${template.tempoBpm} does not fit MIDI's three-byte tempo (${microseconds} microseconds)`);
+    offsets.forEach((offset, index) => {
+        if (Math.abs(offset.timeOffsetTicks) >= slotTicks)
+            throw new Error(`groove template "${name}": slot ${index} is offset by ${offset.timeOffsetTicks} ticks, outside the +/-${slotTicks} the MIDI encoding's one-slot anchor can tell from a slot shift`);
+        const velocity = Math.round(VELOCITY_SCALE * offset.velocityFactor);
+        if (velocity < 1 || velocity > 127)
+            throw new Error(`groove template "${name}": slot ${index} has velocityFactor ${offset.velocityFactor}, outside the ${1 / VELOCITY_SCALE} to ${127 / VELOCITY_SCALE} the MIDI encoding can store at ${1 / VELOCITY_SCALE} per velocity unit`);
+    });
+    const wires = [
+        {
+            tick: 0,
+            bytes: metaEvent(0x51, [(microseconds >> 16) & 0xff, (microseconds >> 8) & 0xff, microseconds & 0xff]),
+        },
+        { tick: 0, bytes: metaEvent(0x58, [timeSignature[0], Math.log2(timeSignature[1]), 24, 8]) },
+        { tick: 0, bytes: metaEvent(0x01, [...encoder.encode(GROOVE_PREFIX + name)]) },
+    ];
+    offsets.forEach((offset, index) => {
+        //the anchor occupies the first subdivision, so slot i's grid position is one slot
+        //later than the anchor plus i more; the offset is measured from that position
+        const on = slotTicks * (index + 1) + offset.timeOffsetTicks;
+        const off = on + Math.max(1, Math.floor(slotTicks / 4));
+        wires.push({
+            tick: on,
+            bytes: [0x90, FIRST_SLOT_PITCH + index, Math.round(VELOCITY_SCALE * offset.velocityFactor)],
+        });
+        wires.push({ tick: off, bytes: [0x80, FIRST_SLOT_PITCH + index, 0] });
+    });
+    wires.sort((a, b) => a.tick - b.tick);
+    const track = [];
+    let previous = 0;
+    for (const wire of wires) {
+        track.push(...vlq(wire.tick - previous), ...wire.bytes);
+        previous = wire.tick;
+    }
+    track.push(0, 0xff, 0x2f, 0x00);
+    return new Uint8Array([
+        ...ascii('MThd'),
+        0,
+        0,
+        0,
+        6,
+        0,
+        0,
+        0,
+        1,
+        (ppq >> 8) & 0xff,
+        ppq & 0xff,
+        ...ascii('MTrk'),
+        (track.length >>> 24) & 0xff,
+        (track.length >>> 16) & 0xff,
+        (track.length >>> 8) & 0xff,
+        track.length & 0xff,
+        ...track,
+    ]);
+}
+/** which grid gives a bar of this signature exactly this many slots */
+function subdivisionFor(timeSignature, slots) {
+    for (const candidate of GRIDS) {
+        try {
+            if (subdivisionCount(timeSignature, candidate) === slots)
+                return candidate;
+        }
+        catch {
+            //a grid that does not tile this bar cannot be the answer
+        }
+    }
+    throw new Error(`a ${slots}-slot groove in ${timeSignature[0]}/${timeSignature[1]} is not one of the 8n, 16n or 32n grids`);
+}
+/**
+ * Reads a groove back out of Standard MIDI File bytes.
+ *
+ * This is a dedicated reader rather than `parseMidi` over the same bytes: a round trip
+ * needs the tempo, time-signature and name metas, which `parseMidi` deliberately drops
+ * when it flattens a file into gameplay events.
+ */
+function readGrooveMidi(data) {
+    const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let cursor = 0;
+    const need = (count, what) => {
+        if (cursor + count > bytes.length)
+            throw new Error(`truncated MIDI file while reading ${what}`);
+    };
+    const readAscii = (length, what) => {
+        need(length, what);
+        let text = '';
+        for (let i = 0; i < length; i++)
+            text += String.fromCharCode(bytes[cursor + i]);
+        cursor += length;
+        return text;
+    };
+    const readU8 = (what) => {
+        need(1, what);
+        return bytes[cursor++];
+    };
+    const readU16 = (what) => {
+        need(2, what);
+        const value = view.getUint16(cursor);
+        cursor += 2;
+        return value;
+    };
+    const readU32 = (what) => {
+        need(4, what);
+        const value = view.getUint32(cursor);
+        cursor += 4;
+        return value;
+    };
+    const readVlq = (what) => {
+        let value = 0;
+        for (let i = 0; i < 4; i++) {
+            const byte = readU8(what);
+            value = (value << 7) | (byte & 0x7f);
+            if ((byte & 0x80) === 0)
+                return value;
+        }
+        throw new Error(`a variable-length quantity in ${what} runs past four bytes`);
+    };
+    if (readAscii(4, 'the file header') !== 'MThd')
+        throw new Error('not a Standard MIDI File: the MThd header is missing');
+    const headerLength = readU32('the header length');
+    if (headerLength < 6)
+        throw new Error(`MThd is ${headerLength} bytes, expected at least 6`);
+    const format = readU16('the format');
+    const trackCount = readU16('the track count');
+    const division = readU16('the division');
+    cursor += headerLength - 6;
+    if (format > 1)
+        throw new Error(`MIDI format ${format} is not a file this reader understands`);
+    if ((division & 0x8000) !== 0)
+        throw new Error('SMPTE time in the division carries no tick grid to read a groove from');
+    if (trackCount !== 1)
+        throw new Error(`an mwg groove file holds one track, this one has ${trackCount}`);
+    if (readAscii(4, 'the track header') !== 'MTrk')
+        throw new Error('the MTrk track header is missing');
+    const trackLength = readU32('the track length');
+    const trackEnd = cursor + trackLength;
+    if (trackEnd > bytes.length)
+        throw new Error('truncated MIDI file: the track runs past the end of the data');
+    let tick = 0;
+    let running = 0;
+    let microseconds = null;
+    let timeSignature = null;
+    let grooveName = null;
+    let sawEnd = false;
+    const onsets = new Map();
+    while (cursor < trackEnd) {
+        tick += readVlq('a delta time');
+        let status = bytes[cursor];
+        if (status < 0x80) {
+            if (running === 0)
+                throw new Error(`data at tick ${tick} follows a delta time with no running status to read it under`);
+            //the byte is data, not a status: the channel message still stands from before
+            status = running;
+        }
+        else {
+            cursor++;
+            if (status < 0xf0)
+                running = status;
+        }
+        if (status === 0xff) {
+            const type = readU8('a meta type');
+            const length = readVlq('a meta length');
+            need(length, 'a meta event');
+            const body = cursor;
+            if (type === 0x51 && length === 3)
+                microseconds = (bytes[body] << 16) | (bytes[body + 1] << 8) | bytes[body + 2];
+            else if (type === 0x58 && length >= 2)
+                timeSignature = [bytes[body], 2 ** bytes[body + 1]];
+            else if ((type === 0x01 || type === 0x03) && length > 0) {
+                let text = '';
+                for (let i = 0; i < length; i++)
+                    text += String.fromCharCode(bytes[body + i]);
+                if (text.startsWith(GROOVE_PREFIX))
+                    grooveName = text.slice(GROOVE_PREFIX.length);
+            }
+            cursor += length;
+            if (type === 0x2f)
+                sawEnd = true;
+            running = 0;
+            continue;
+        }
+        if (status === 0xf0 || status === 0xf7) {
+            cursor += readVlq('a sysex length');
+            running = 0;
+            continue;
+        }
+        const kind = status & 0xf0;
+        if (kind === 0x90 || kind === 0x80) {
+            const note = readU8('a note number');
+            const velocity = readU8('a note velocity');
+            if (kind === 0x90 && velocity > 0) {
+                if (onsets.has(note))
+                    throw new Error(`pitch ${note} carries more than one note-on, which no groove encodes`);
+                onsets.set(note, { tick, velocity });
+            }
+        }
+        else if (kind === 0xb0 || kind === 0xe0) {
+            need(2, 'a controller or bend event');
+            cursor += 2;
+        }
+        else if (kind === 0xc0 || kind === 0xd0) {
+            need(1, 'a program or channel-aftertouch event');
+            cursor += 1;
+        }
+        else
+            throw new Error(`unexpected status byte 0x${status.toString(16)} at tick ${tick}`);
+    }
+    if (!sawEnd)
+        throw new Error('the track has no end-of-track meta, so the file is incomplete');
+    if (grooveName === null)
+        throw new Error(`no ${GROOVE_PREFIX} text meta: this file was not written as a groove`);
+    if (timeSignature === null)
+        throw new Error('no time-signature meta: an mwg groove file always carries one');
+    const ppq = division;
+    const slots = onsets.size;
+    const subdivision = subdivisionFor(timeSignature, slots);
+    const slotTicks = subdivisionTicks(ppq, subdivision);
+    const offsets = [];
+    for (let index = 0; index < slots; index++) {
+        const onset = onsets.get(FIRST_SLOT_PITCH + index);
+        if (!onset)
+            throw new Error(`slot ${index} is missing: expected a note on pitch ${FIRST_SLOT_PITCH + index}`);
+        offsets.push({
+            subdivisionIndex: index,
+            //slot i's grid position is the anchor plus i subdivisions: the anchor itself
+            //is what makes an offset a whole slot long unreadable, hence the writer's bound
+            timeOffsetTicks: onset.tick - slotTicks * (index + 1),
+            velocityFactor: onset.velocity / VELOCITY_SCALE,
+        });
+    }
+    const template = {
+        name: grooveName,
+        timeSignature,
+        ppq,
+        tempoBpm: microseconds === null ? 120 : Math.round((60_000_000 / microseconds) * 100) / 100,
+        subdivision,
+        offsets,
+    };
+    assertGrooveTemplate(template);
+    return template;
+}
+function readGrooveJson(data) {
+    const text = typeof data === 'string' ? data : new TextDecoder().decode(data);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error('a groove JSON export must be an object');
+    assertGrooveTemplate(parsed);
+    return parsed;
+}
+/**
+ * Writes a template out and reads one back, through JSON (exact) or MIDI (encoded, with
+ * the bounds above enforced on the way in). Asking for `.agr` or `.reaper-groove` throws
+ * naming what is missing rather than returning something that merely resembles them.
+ *
+ * @example
+ * ```ts
+ * import { GrooveConverter, type GrooveTemplate } from '@datamoc/mw_games/audio';
+ *
+ * declare const template: GrooveTemplate;
+ *
+ * const converter = new GrooveConverter();
+ * const text = await converter.exportFormat(template, 'json');
+ * const copy = await converter.importFormat(text, 'json'); // same offsets, same name
+ *
+ * const bytes = await converter.exportFormat(template, 'midi');
+ * const fromMidi = await converter.importFormat(bytes, 'midi');
+ * console.log(fromMidi.tempoBpm === template.tempoBpm); // true: tempo travels as microseconds
+ * ```
+ */
+export class GrooveConverter {
+    async exportFormat(template, format) {
+        switch (format) {
+            case 'json':
+                assertGrooveTemplate(template);
+                return JSON.stringify(template, null, 2);
+            case 'midi':
+                return writeGrooveMidi(template);
+            case 'ableton-agr':
+            case 'reaper-groove':
+                return notShipped(format);
+            default:
+                throw new Error(`unknown groove format: ${String(format)}`);
+        }
+    }
+    async importFormat(data, format) {
+        switch (format) {
+            case 'json':
+                return readGrooveJson(data);
+            case 'midi':
+                return readGrooveMidi(data);
+            case 'ableton-agr':
+            case 'reaper-groove':
+                return notShipped(format);
+            default:
+                throw new Error(`unknown groove format: ${String(format)}`);
+        }
+    }
+}
+//# sourceMappingURL=GrooveConverter.js.map

package/dist/audio/humanize/GrooveConverter.js.map

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

package/dist/audio/humanize/GrooveExtractor.d.ts

@@ -0,0 +1,49 @@
+import type { MidiFile } from '../Midi.ts';
+import { type GridSubdivision, type GrooveTemplate } from './Groove.ts';
+export interface GrooveExtractorEngine {
+    /**
+     * Mode A: align two performances of the same material - one played straight, one
+     * played - and keep how far each played note sat from its quantized counterpart.
+     */
+    extractFromMidiPair(quantizedMidi: MidiFile, recordedMidi: MidiFile, gridSubdivision?: GridSubdivision): Promise<GrooveTemplate>;
+    /**
+     * Mode B: one performance and no reference. The notes themselves are projected onto
+     * the nearest grid slot, so what comes back is the residual of a played file against
+     * its own implied grid - the deviations a straight quantization would remove.
+     */
+    extractFromSingleMidi(recordedMidi: MidiFile, gridSubdivision?: GridSubdivision): Promise<GrooveTemplate>;
+    /**
+     * Mode C: a recording instead of a file. The tempo is an argument rather than
+     * something read off the signal, because timing is meaningless without it.
+     */
+    extractFromAudioBuffer(audioBuffer: AudioBuffer, gridSubdivision?: '8n' | '16n', tempoBpm?: number): Promise<GrooveTemplate>;
+}
+/**
+ * Extracts a groove template from a pair of performances of the same material.
+ *
+ * Every note-on in `recordedMidi` is matched to the closest still-unused note-on of the
+ * same channel and pitch in `quantizedMidi`. A match is only taken when it falls inside
+ * half a slot, so a recorded part with notes the quantized one never plays is ignored
+ * instead of being forced onto a neighbour, and a slot the pair never reaches keeps the
+ * neutral offset rather than a value invented from no evidence at all.
+ *
+ * @example
+ * ```ts
+ * import { parseMidi, GrooveExtractor, type GrooveTemplate } from '@datamoc/mw_games/audio';
+ *
+ * declare const straightBytes: ArrayBuffer;
+ * declare const playedBytes: ArrayBuffer;
+ *
+ * const straight = parseMidi(straightBytes);
+ * const played = parseMidi(playedBytes);
+ *
+ * const template = await new GrooveExtractor().extractFromMidiPair(straight, played, '16n');
+ * console.log(template.offsets[0].timeOffsetTicks, template.name); // 0 'extracted'
+ * ```
+ */
+export declare class GrooveExtractor implements GrooveExtractorEngine {
+    extractFromMidiPair(quantizedMidi: MidiFile, recordedMidi: MidiFile, gridSubdivision?: GridSubdivision): Promise<GrooveTemplate>;
+    extractFromSingleMidi(recordedMidi: MidiFile, gridSubdivision?: GridSubdivision): Promise<GrooveTemplate>;
+    extractFromAudioBuffer(audioBuffer: AudioBuffer, gridSubdivision?: '8n' | '16n', tempoBpm?: number): Promise<GrooveTemplate>;
+}
+//# sourceMappingURL=GrooveExtractor.d.ts.map

package/dist/audio/humanize/GrooveExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrooveExtractor.d.ts","sourceRoot":"","sources":["../../../src/audio/humanize/GrooveExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAsC,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AA8B5G,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,mBAAmB,CAClB,aAAa,EAAE,QAAQ,EACvB,YAAY,EAAE,QAAQ,EACtB,eAAe,CAAC,EAAE,eAAe,GAC/B,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B;;;;OAIG;IACH,qBAAqB,CAAC,YAAY,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1G;;;OAGG;IACH,sBAAsB,CACrB,WAAW,EAAE,WAAW,EACxB,eAAe,CAAC,EAAE,IAAI,GAAG,KAAK,EAC9B,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3B;AAyDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;IACtD,mBAAmB,CACxB,aAAa,EAAE,QAAQ,EACvB,YAAY,EAAE,QAAQ,EACtB,eAAe,GAAE,eAAuB,GACtC,OAAO,CAAC,cAAc,CAAC,CAiDzB;IAEK,qBAAqB,CAC1B,YAAY,EAAE,QAAQ,EACtB,eAAe,GAAE,eAAuB,GACtC,OAAO,CAAC,cAAc,CAAC,CAmBzB;IAEK,sBAAsB,CAC3B,WAAW,EAAE,WAAW,EACxB,eAAe,GAAE,IAAI,GAAG,KAAa,EACrC,QAAQ,GAAE,MAA0B,GAClC,OAAO,CAAC,cAAc,CAAC,CAgCzB;CACD"}

package/dist/audio/humanize/GrooveExtractor.js

@@ -0,0 +1,179 @@
+import { subdivisionCount, subdivisionTicks } from './Groove.js';
+import { detectOnsets } from './Onsets.js';
+/**
+ * Builds `GrooveTemplate`s from three kinds of evidence, all reduced to the same shape by
+ * the same last step: collect a pile of per-slot deviations, take the median of each, and
+ * fill the slots nobody played with the neutral offsets (0, 1.0).
+ *
+ * The median is the whole reason a groove can be recovered from evidence this noisy. A
+ * single flubbed note drags a mean off the grid; with medians it is one sample among
+ * several and disappears. It also gives a slot with no evidence at all a defensible
+ * answer: nothing was measured, so the slot keeps the grid position and the default
+ * velocity, rather than inventing a deviation from an empty list.
+ */
+/** every extracted template carries the mode's name so a save can say where it came from */
+const EXTRACTED_NAME = 'extracted';
+/** extraction reads one bar of 4/4; a signature is written out and re-checked on import */
+const EXTRACTED_SIGNATURE = [4, 4];
+/** tempo assumed when the recorded file states none, which is the General MIDI default */
+const DEFAULT_BPM = 120;
+/** the tempo Mode C is measured against when the caller does not supply one */
+const AUDIO_DEFAULT_BPM = 120;
+/** ticks per quarter for audio-derived templates, chosen because nothing ties them to a file */
+const AUDIO_PPQ = 480;
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = sorted.length >> 1;
+    return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function roundedMedian(values) {
+    return Math.round(median(values));
+}
+/** the file's tempo in beats per minute: its first tempo event, or the General MIDI default */
+function tempoOf(midi) {
+    for (const event of midi.events) {
+        if (event.type === 'tempo')
+            return Math.round((60_000_000 / event.microsecondsPerQuarter) * 100) / 100;
+    }
+    return DEFAULT_BPM;
+}
+function noteOns(midi) {
+    return midi.events.filter((event) => event.type === 'noteOn');
+}
+/** the flat list of note velocities, which Mode B needs a typical value out of */
+function velocitiesOf(midi) {
+    return noteOns(midi).map((event) => event.velocity);
+}
+function finish(slots, subdivision, ppq, tempoBpm, velocityFrom) {
+    const offsets = slots.map((slot, subdivisionIndex) => ({
+        subdivisionIndex,
+        timeOffsetTicks: slot.time.length > 0 ? roundedMedian(slot.time) : 0,
+        velocityFactor: slot.velocity.length > 0 ? velocityFrom(slot) : 1,
+    }));
+    return {
+        name: EXTRACTED_NAME,
+        timeSignature: [...EXTRACTED_SIGNATURE],
+        ppq,
+        tempoBpm,
+        subdivision,
+        offsets,
+    };
+}
+/**
+ * Extracts a groove template from a pair of performances of the same material.
+ *
+ * Every note-on in `recordedMidi` is matched to the closest still-unused note-on of the
+ * same channel and pitch in `quantizedMidi`. A match is only taken when it falls inside
+ * half a slot, so a recorded part with notes the quantized one never plays is ignored
+ * instead of being forced onto a neighbour, and a slot the pair never reaches keeps the
+ * neutral offset rather than a value invented from no evidence at all.
+ *
+ * @example
+ * ```ts
+ * import { parseMidi, GrooveExtractor, type GrooveTemplate } from '@datamoc/mw_games/audio';
+ *
+ * declare const straightBytes: ArrayBuffer;
+ * declare const playedBytes: ArrayBuffer;
+ *
+ * const straight = parseMidi(straightBytes);
+ * const played = parseMidi(playedBytes);
+ *
+ * const template = await new GrooveExtractor().extractFromMidiPair(straight, played, '16n');
+ * console.log(template.offsets[0].timeOffsetTicks, template.name); // 0 'extracted'
+ * ```
+ */
+export class GrooveExtractor {
+    async extractFromMidiPair(quantizedMidi, recordedMidi, gridSubdivision = '16n') {
+        const ppq = recordedMidi.ticksPerQuarter;
+        const slotTicks = subdivisionTicks(ppq, gridSubdivision);
+        const slots = subdivisionCount(EXTRACTED_SIGNATURE, gridSubdivision);
+        //the reference may have been quantized against a different ppq: scale it into the
+        //recorded file's ticks before any of the comparisons below mean anything
+        const scale = ppq / quantizedMidi.ticksPerQuarter;
+        const reference = noteOns(quantizedMidi).map((event) => ({
+            channel: event.channel,
+            note: event.note,
+            tick: event.tick * scale,
+            velocity: event.velocity,
+        }));
+        const used = new Set();
+        //each played note claims its nearest untouched reference of the same channel and
+        //pitch; the ratio, not the difference, of the two velocities is what survives, so
+        //the template scales a performance instead of reproducing its own absolute levels
+        const matches = [];
+        for (const played of noteOns(recordedMidi)) {
+            let bestIndex = -1;
+            let bestDistance = Infinity;
+            for (let i = 0; i < reference.length; i++) {
+                const candidate = reference[i];
+                if (used.has(i) || candidate.channel !== played.channel || candidate.note !== played.note)
+                    continue;
+                const distance = Math.abs(candidate.tick - played.tick);
+                if (distance < bestDistance) {
+                    bestDistance = distance;
+                    bestIndex = i;
+                }
+            }
+            if (bestIndex < 0 || bestDistance > slotTicks / 2)
+                continue;
+            used.add(bestIndex);
+            matches.push({
+                slotTick: reference[bestIndex].tick,
+                delta: played.tick - reference[bestIndex].tick,
+                factor: reference[bestIndex].velocity > 0 ? played.velocity / reference[bestIndex].velocity : null,
+            });
+        }
+        const buckets = Array.from({ length: slots }, () => ({ time: [], velocity: [] }));
+        for (const match of matches) {
+            const index = ((Math.round(match.slotTick / slotTicks) % slots) + slots) % slots;
+            buckets[index].time.push(match.delta);
+            if (match.factor !== null)
+                buckets[index].velocity.push(match.factor);
+        }
+        return finish(buckets, gridSubdivision, ppq, tempoOf(recordedMidi), (slot) => median(slot.velocity));
+    }
+    async extractFromSingleMidi(recordedMidi, gridSubdivision = '16n') {
+        const ppq = recordedMidi.ticksPerQuarter;
+        const slotTicks = subdivisionTicks(ppq, gridSubdivision);
+        const slots = subdivisionCount(EXTRACTED_SIGNATURE, gridSubdivision);
+        const buckets = Array.from({ length: slots }, () => ({ time: [], velocity: [] }));
+        for (const event of noteOns(recordedMidi)) {
+            //project onto the nearest slot: the residual is how far the performance sat
+            //from its own implied grid, which is what a single file can actually show
+            const nearest = Math.round(event.tick / slotTicks) * slotTicks;
+            const index = ((Math.round(nearest / slotTicks) % slots) + slots) % slots;
+            buckets[index].time.push(event.tick - nearest);
+            buckets[index].velocity.push(event.velocity);
+        }
+        const typical = median(velocitiesOf(recordedMidi));
+        return finish(buckets, gridSubdivision, ppq, tempoOf(recordedMidi), (slot) => typical <= 0 ? 1 : median(slot.velocity) / typical);
+    }
+    async extractFromAudioBuffer(audioBuffer, gridSubdivision = '16n', tempoBpm = AUDIO_DEFAULT_BPM) {
+        if (!Number.isFinite(tempoBpm) || tempoBpm <= 0)
+            throw new Error(`tempoBpm must be greater than 0, got ${String(tempoBpm)}`);
+        const channelData = [];
+        for (let channel = 0; channel < audioBuffer.numberOfChannels; channel++)
+            channelData.push(audioBuffer.getChannelData(channel));
+        const mono = new Float32Array(audioBuffer.length);
+        for (const data of channelData)
+            for (let i = 0; i < data.length; i++)
+                mono[i] += data[i] / channelData.length;
+        const onsets = detectOnsets(mono, audioBuffer.sampleRate);
+        if (onsets.length === 0)
+            throw new Error('no onsets detected in the buffer - a groove needs audible attacks, and this audio has none');
+        const ppq = AUDIO_PPQ;
+        const slotTicks = subdivisionTicks(ppq, gridSubdivision);
+        const slots = subdivisionCount(EXTRACTED_SIGNATURE, gridSubdivision);
+        const ticksPerSecond = (tempoBpm * ppq) / 60;
+        const buckets = Array.from({ length: slots }, () => ({ time: [], velocity: [] }));
+        for (const seconds of onsets) {
+            const tick = seconds * ticksPerSecond;
+            const nearest = Math.round(tick / slotTicks) * slotTicks;
+            const index = ((Math.round(nearest / slotTicks) % slots) + slots) % slots;
+            buckets[index].time.push(tick - nearest);
+        }
+        //audio carries no velocity to recover, so every slot stays at the neutral factor
+        return finish(buckets, gridSubdivision, ppq, tempoBpm, () => 1);
+    }
+}
+//# sourceMappingURL=GrooveExtractor.js.map

package/dist/audio/humanize/GrooveExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrooveExtractor.js","sourceRoot":"","sources":["../../../src/audio/humanize/GrooveExtractor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAA6C,MAAM,aAAa,CAAC;AAC5G,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AAEH,4FAA4F;AAC5F,MAAM,cAAc,GAAG,WAAW,CAAC;AAEnC,2FAA2F;AAC3F,MAAM,mBAAmB,GAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAErD,0FAA0F;AAC1F,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,gGAAgG;AAChG,MAAM,SAAS,GAAG,GAAG,CAAC;AAkCtB,SAAS,MAAM,CAAC,MAAyB;IACxC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,aAAa,CAAC,MAAyB;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,+FAA+F;AAC/F,SAAS,OAAO,CAAC,IAAc;IAC9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,KAAK,CAAC,sBAAsB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IACxG,CAAC;IACD,OAAO,WAAW,CAAC;AACpB,CAAC;AAED,SAAS,OAAO,CAAC,IAAc;IAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAA0B,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;AACvF,CAAC;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,IAAc;IACnC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,MAAM,CACd,KAAyB,EACzB,WAA4B,EAC5B,GAAW,EACX,QAAgB,EAChB,YAAuC;IAEvC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;QACtD,gBAAgB;QAChB,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;KACjE,CAAC,CAAC,CAAC;IAEJ,OAAO;QACN,IAAI,EAAE,cAAc;QACpB,aAAa,EAAE,CAAC,GAAG,mBAAmB,CAAC;QACvC,GAAG;QACH,QAAQ;QACR,WAAW;QACX,OAAO;KACP,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,eAAe;IAC3B,KAAK,CAAC,mBAAmB,CACxB,aAAuB,EACvB,YAAsB,EACtB,eAAe,GAAoB,KAAK;QAExC,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,CAAC;QACzC,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,gBAAgB,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;QACrE,kFAAkF;QAClF,yEAAyE;QACzE,MAAM,KAAK,GAAG,GAAG,GAAG,aAAa,CAAC,eAAe,CAAC;QAElD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACxD,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI,GAAG,KAAK;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACxB,CAAC,CAAC,CAAC;QACJ,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAE/B,iFAAiF;QACjF,kFAAkF;QAClF,kFAAkF;QAClF,MAAM,OAAO,GAAiE,EAAE,CAAC;QACjF,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAC5C,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;YACnB,IAAI,YAAY,GAAG,QAAQ,CAAC;YAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;gBAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;oBAAE,SAAS;gBACpG,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;gBACxD,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;oBAC7B,YAAY,GAAG,QAAQ,CAAC;oBACxB,SAAS,GAAG,CAAC,CAAC;gBACf,CAAC;YACF,CAAC;YACD,IAAI,SAAS,GAAG,CAAC,IAAI,YAAY,GAAG,SAAS,GAAG,CAAC;gBAAE,SAAS;YAC5D,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI;gBACnC,KAAK,EAAE,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI;gBAC9C,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;aAClG,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAc,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAC7F,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;YACjF,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtG,CAAC;IAED,KAAK,CAAC,qBAAqB,CAC1B,YAAsB,EACtB,eAAe,GAAoB,KAAK;QAExC,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,CAAC;QACzC,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,gBAAgB,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;QACrE,MAAM,OAAO,GAAc,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAE7F,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAC3C,4EAA4E;YAC5E,0EAA0E;YAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;YAC/D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;YAC1E,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;YAC/C,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAC5E,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAClD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,sBAAsB,CAC3B,WAAwB,EACxB,eAAe,GAAiB,KAAK,EACrC,QAAQ,GAAW,iBAAiB;QAEpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,wCAAwC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAE7E,MAAM,WAAW,GAAmB,EAAE,CAAC;QACvC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC,gBAAgB,EAAE,OAAO,EAAE;YACtE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QAEvD,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,WAAW;YAAE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;gBAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC;QAE9G,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YACtB,MAAM,IAAI,KAAK,CACd,4FAA4F,CAC5F,CAAC;QAEH,MAAM,GAAG,GAAG,SAAS,CAAC;QACtB,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,gBAAgB,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;QACrE,MAAM,cAAc,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QAC7C,MAAM,OAAO,GAAc,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAE7F,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,OAAO,GAAG,cAAc,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;YACzD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;YAC1E,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,iFAAiF;QACjF,OAAO,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;CACD"}

package/dist/audio/humanize/GrooveHumanizer.d.ts

@@ -0,0 +1,34 @@
+import type { MidiFile } from '../Midi.ts';
+import { type HumanizationOptions, type MidiHumanizerEngine } from './Humanize.ts';
+/**
+ * Tier 2: the lite pass plus the groove grid and two musical rules the lite tier has no
+ * opinion about. The template supplies the per-slot deviations, rescaled from the tempo it
+ * was measured at to the tempo of the file being played, so a groove stays the same shape
+ * in time rather than the same number of ticks.
+ *
+ * The two rules are what keep a groove musical instead of merely uneven: kick and bass
+ * carry the pulse and stay inside 5 ms however loose the run, while a melody's local peaks
+ * are lifted a little so the line still speaks. Without a template the slot term is empty
+ * and the run is those rules over the same noise the lite tier uses - this tier is a
+ * superset of it, never a different pass.
+ *
+ * @example
+ * ```ts
+ * import { parseMidi, GrooveHumanizer, type GrooveTemplate } from '@datamoc/mw_games/audio';
+ *
+ * declare const midiBytes: ArrayBuffer;
+ * declare const template: GrooveTemplate;
+ *
+ * const file = parseMidi(midiBytes);
+ * const engine = new GrooveHumanizer();
+ * await engine.initialize(); // idempotent; the factory already does this for you
+ * const swung = await engine.process(file, { intensity: 0.8, grooveTemplate: template, seed: 7 });
+ * ```
+ */
+export declare class GrooveHumanizer implements MidiHumanizerEngine {
+    readonly tierName = "groove";
+    readonly approximateSizeMb = 0.5;
+    initialize(): Promise<void>;
+    process(midi: MidiFile, options: HumanizationOptions): Promise<MidiFile>;
+}
+//# sourceMappingURL=GrooveHumanizer.d.ts.map

package/dist/audio/humanize/GrooveHumanizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrooveHumanizer.d.ts","sourceRoot":"","sources":["../../../src/audio/humanize/GrooveHumanizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAqB,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IAC1D,QAAQ,CAAC,QAAQ,YAAY;IAC7B,QAAQ,CAAC,iBAAiB,OAAO;IAE3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAE9B,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE7E;CACD"}