@jeffy-g/live-midi-types 0.10.0 → 0.11.0

package/dist/midi10-smf-types.d.ts

@@ -10,7 +10,7 @@
 /**
  * @file src/midi10-smf-types.ts
  */
-/// <reference path="../ESMFEventType.d.ts" preserve="true" />
+import type { ESMFEventType } from "./ESMFEventType.ts";
 export interface MidiHeader {
   format: 0 | 1 | 2;
   numTracks: number;
@@ -20,22 +20,20 @@ export interface MidiHeader {
   ticksPerBeat?: number;
 }
 export type TextEventTypesUnion = ESMFEventType.text | ESMFEventType.copyrightNotice | ESMFEventType.trackName | ESMFEventType.instrumentName | ESMFEventType.lyrics | ESMFEventType.marker | ESMFEventType.cuePoint;
-export interface MidiBaseEvent<T> {
+export interface MidiBaseEvent<GEventType> {
   /**
    * serialize/deserialize by `writeVarInt/readVarInt`
    * + byte range are __`1 to 4`__ (unsigned integer)
    */
   deltaTime: number;
   /**
-   * MUST be `ESMFEventType`
+   * Numeric event discriminator shared by channel, system-exclusive, and meta events.
+   * SHOULD be `ESMFEventType`.
    * @see {@link ESMFEventType}
    */
-  type: T;
+  type: GEventType;
 }
-export interface MidiMetaEvent<T> extends MidiBaseEvent<T> {
-  meta?: true;
-}
-export type MidiEndOfTrackEvent = MidiMetaEvent<ESMFEventType.endOfTrack>;
+export type MidiEndOfTrackEvent = MidiBaseEvent<ESMFEventType.endOfTrack>;
 export type FrameRate = 24 | 25 | 29.97 | 30;
 export interface MidiSmpteOffsetMixins {
   frameRate: FrameRate;
@@ -45,7 +43,7 @@ export interface MidiSmpteOffsetMixins {
   frame: number;
   subFrame: number;
 }
-export type MidiSmpteOffsetEvent = MidiMetaEvent<ESMFEventType.smpteOffset> & MidiSmpteOffsetMixins;
+export type MidiSmpteOffsetEvent = MidiBaseEvent<ESMFEventType.smpteOffset> & MidiSmpteOffsetMixins;
 export interface MidiTimeSignatureMixins {
   numerator: number;
   denominator: number;
@@ -54,47 +52,47 @@ export interface MidiTimeSignatureMixins {
   /** @todo whats this? */
   thirtyseconds: number;
 }
-export type MidiTimeSignatureEvent = MidiMetaEvent<ESMFEventType.timeSignature> & MidiTimeSignatureMixins;
+export type MidiTimeSignatureEvent = MidiBaseEvent<ESMFEventType.timeSignature> & MidiTimeSignatureMixins;
 export interface MidiKeySignatureMixins {
   key: number;
   scale: number;
 }
-export type MidiKeySignatureEvent = MidiMetaEvent<ESMFEventType.keySignature> & MidiKeySignatureMixins;
+export type MidiKeySignatureEvent = MidiBaseEvent<ESMFEventType.keySignature> & MidiKeySignatureMixins;
 export interface MidiDataMixins {
   data: ArrayLike<number>;
 }
 export type MidiSysExEvent = MidiBaseEvent<ESMFEventType.sysEx> & MidiDataMixins;
 export type MidiEndSysExEvent = MidiBaseEvent<ESMFEventType.endSysEx> & MidiDataMixins;
-export type MidiSequencerSpecificEvent = MidiMetaEvent<ESMFEventType.sequencerSpecific> & MidiDataMixins;
+export type MidiSequencerSpecificEvent = MidiBaseEvent<ESMFEventType.sequencerSpecific> & MidiDataMixins;
 export interface MidiUnknownMixins {
   data: ArrayLike<number>;
   metatypeByte: number;
 }
-export type MidiUnknownEvent = MidiMetaEvent<ESMFEventType.unknownMeta> & MidiUnknownMixins;
+export type MidiUnknownEvent = MidiBaseEvent<ESMFEventType.unknownMeta> & MidiUnknownMixins;
 export interface MidiNumberMixins {
   number: number;
 }
-export type MidiSequenceNumberEvent = MidiMetaEvent<ESMFEventType.sequenceNumber> & MidiNumberMixins;
+export type MidiSequenceNumberEvent = MidiBaseEvent<ESMFEventType.sequenceNumber> & MidiNumberMixins;
 export interface MidiTextMixins {
   text: string;
 }
-export type MidiTextEvent = MidiMetaEvent<ESMFEventType.text> & MidiTextMixins;
-export type MidiLyricsEvent = MidiMetaEvent<ESMFEventType.lyrics> & MidiTextMixins;
-export type MidiMarkerEvent = MidiMetaEvent<ESMFEventType.marker> & MidiTextMixins;
-export type MidiCuePointEvent = MidiMetaEvent<ESMFEventType.cuePoint> & MidiTextMixins;
-export type MidiTrackNameEvent = MidiMetaEvent<ESMFEventType.trackName> & MidiTextMixins;
-export type MidiInstrumentNameEvent = MidiMetaEvent<ESMFEventType.instrumentName> & MidiTextMixins;
-export type MidiCopyrightNoticeEvent = MidiMetaEvent<ESMFEventType.copyrightNotice> & MidiTextMixins;
-export type MidiSetTempoEvent = MidiMetaEvent<ESMFEventType.setTempo> & {
+export type MidiTextEvent = MidiBaseEvent<ESMFEventType.text> & MidiTextMixins;
+export type MidiLyricsEvent = MidiBaseEvent<ESMFEventType.lyrics> & MidiTextMixins;
+export type MidiMarkerEvent = MidiBaseEvent<ESMFEventType.marker> & MidiTextMixins;
+export type MidiCuePointEvent = MidiBaseEvent<ESMFEventType.cuePoint> & MidiTextMixins;
+export type MidiTrackNameEvent = MidiBaseEvent<ESMFEventType.trackName> & MidiTextMixins;
+export type MidiInstrumentNameEvent = MidiBaseEvent<ESMFEventType.instrumentName> & MidiTextMixins;
+export type MidiCopyrightNoticeEvent = MidiBaseEvent<ESMFEventType.copyrightNotice> & MidiTextMixins;
+export type MidiSetTempoEvent = MidiBaseEvent<ESMFEventType.setTempo> & {
   /**
    * __`unsigned 24-bit integer`__
    */
   microsecondsPerBeat: number;
 };
-export type MidiPortPrefixEvent = MidiMetaEvent<ESMFEventType.portPrefix> & {
+export type MidiPortPrefixEvent = MidiBaseEvent<ESMFEventType.portPrefix> & {
   port: number;
 };
-export type MidiChannelPrefixEvent = MidiMetaEvent<ESMFEventType.channelPrefix> & {
+export type MidiChannelPrefixEvent = MidiBaseEvent<ESMFEventType.channelPrefix> & {
   channel: number;
 };
 export interface MidiNoteMixins {
@@ -121,7 +119,7 @@ export interface MidiControllerMixins {
    */
   value: number;
 }
-export interface MidiChannelEvent<T> extends MidiBaseEvent<T> {
+export interface MidiChannelEvent<GEventType> extends MidiBaseEvent<GEventType> {
   running?: true;
   channel: number;
 }
@@ -168,6 +166,23 @@ export type MidiEvent =
   | MidiCopyrightNoticeEvent
   | MidiChannelAftertouchEvent
   | MidiSequencerSpecificEvent;
+/**
+ * Common Utilities
+ */
+export type WithAbsoluteTime = {
+  /**
+   * `absoluteTime` is same as `ticks`
+   */
+  absoluteTime: number;
+};
+/**
+ * MIDI Event Derivation
+ */
+export type MidiEventWithAbsTime<GEvent extends MidiEvent = MidiEvent> = GEvent & WithAbsoluteTime;
+/**
+ * MIDI Event Derivation
+ */
+export type TTrackEvents<GEvent extends MidiEvent = MidiEvent> = Array<MidiEventWithAbsTime<GEvent>>;
 export interface MidiData {
   header: MidiHeader;
   tracks: MidiEvent[][];

package/dist/midi10-smf-types.js

@@ -7,7 +7,6 @@
  * Copyright (c) 2025 jeffy-g
  * Released under the MIT license.
  */
-/// <reference path="../ESMFEventType.d.ts" preserve="true"/>
 /**
  * @file src/midi10-smf-types.ts
  */

package/dist/project.d.ts

@@ -136,7 +136,9 @@ export type TTrackInfo<T extends Record<string, any>> = {
   /**
    * MIDI clips indexed by {@linkcode TClipSummary.id TClipSummary.id}
    */
-  clips: Record<string, TClipSummary<T>>;
+  clips: {
+    [uuidLike: string]: TClipSummary<T>;
+  };
   /**
    * @since v0.10.0
    */
@@ -163,7 +165,7 @@ export type TParsedAbletonLiveSet<T extends Record<string, any>> = {
    *
    * + Currently contains only MIDI tracks.
    */
-  tracks: TTrackInfo<T>[];
+  tracks: Array<TTrackInfo<T>>;
   /**
    * Tempo automation events extracted from the master track.
    *

package/dist/smf-parser.d.ts

@@ -0,0 +1,22 @@
+/*!
+ * Original Source: midi-file (https://github.com/carter-thaxton/midi-file/blob/master/lib/midi-parser.js)
+ * Original License: MIT License
+ *
+ * This file is a numeric-event reimplementation optimized for Uint8Array input.
+ * Copyright (c) 2026 jeffy-g
+ * Released under the MIT license.
+ */
+/**
+ * @file src/smf-parser.ts
+ */
+import type { MidiData } from "./midi10-smf-types.ts";
+/**
+ * Parse a Standard MIDI File into numeric {@link ESMFEventType} events.
+ *
+ * The Uint8Array fast path parses all chunks through a shared cursor and does
+ * not copy complete track payloads. Other array-like inputs are normalized once.
+ *
+ * @param {ArrayLike<number> | ArrayBuffer} input
+ * @returns {MidiData}
+ */
+export declare const parseMidi: (input: ArrayLike<number> | ArrayBuffer) => MidiData;

package/dist/smf-parser.js

@@ -0,0 +1,287 @@
+/*!
+ * Original Source: midi-file (https://github.com/carter-thaxton/midi-file/blob/master/lib/midi-parser.js)
+ * Original License: MIT License
+ *
+ * This file is a numeric-event reimplementation optimized for Uint8Array input.
+ * Copyright (c) 2026 jeffy-g
+ * Released under the MIT license.
+ */
+/**
+ * @file src/smf-parser.ts
+ */
+/**
+ * @import {
+ *   FrameRate,
+ *   MidiData,
+ *   MidiEvent,
+ *   MidiHeader,
+ * } from "./midi10-smf-types";
+ */
+/**
+ * ```
+ * // "MThd"
+ * String.fromCharCode(0x4d, 0x54, 0x68, 0x64) === "MThd"
+ * ```
+ */
+const MTHD = 0x4d546864;
+/**
+ * ```
+ * // "MTrk"
+ * String.fromCharCode(0x4d, 0x54, 0x72, 0x6b) === "MTrk"
+ * ```
+ */
+const MTRK = 0x4d54726b;
+/** @type {FrameRate[]} */
+const FRAME_RATES = [24, 25, 29.97, 30];
+const decorder = new TextDecoder();
+class SmfReader {
+  /**
+   * @param {Uint8Array} data
+   */
+  constructor(data) {
+    this.pos = 0;
+    this.data = data;
+  }
+  readUInt8() {
+    return this.data[this.pos++];
+  }
+  readInt8() {
+    const value = this.data[this.pos++];
+    return value & 0x80 ? value - 0x100 : value;
+  }
+  readUInt16() {
+    const data = this.data;
+    const pos = this.pos;
+    this.pos = pos + 2;
+    return (data[pos] << 8) | data[pos + 1];
+  }
+  readUInt24() {
+    const data = this.data;
+    const pos = this.pos;
+    this.pos = pos + 3;
+    return (data[pos] << 16) | (data[pos + 1] << 8) | data[pos + 2];
+  }
+  readUInt32() {
+    const data = this.data;
+    const pos = this.pos;
+    this.pos = pos + 4;
+    return (data[pos] * 0x1000000 + (data[pos + 1] << 16) + (data[pos + 2] << 8) + data[pos + 3]) >>> 0;
+  }
+  readVarInt() {
+    const data = this.data;
+    let position = this.pos;
+    let result = 0;
+    for (let count = 0; count++ < 4;) {
+      const byte = data[position++];
+      result = (result << 7) | (byte & 0x7f);
+      if ((byte & 0x80) === 0) {
+        this.pos = position;
+        return result;
+      }
+    }
+    throw new Error("MIDI variable-length integer exceeds four bytes");
+  }
+  /**
+   * @param {number} length
+   */
+  readBytes(length) {
+    const start = this.pos;
+    const end = start + length;
+    this.pos = end;
+    return this.data.slice(start, end);
+  }
+  /**
+   * @param {number} length
+   */
+  readString(length) {
+    const start = this.pos;
+    const end = start + length;
+    this.pos = end;
+    return decorder.decode(this.data.slice(start, end));
+  }
+}
+/** @type {(id: number) => string} */
+const chunkIdToString = (id) => String.fromCharCode(id >>> 24, (id >>> 16) & 0xff, (id >>> 8) & 0xff, id & 0xff);
+/** @type {(reader: SmfReader, magicNumber: number) => number} */
+const readChunkEnd = (reader, magicNumber /* , expectedName: string */) => {
+  const id = reader.readUInt32();
+  const length = reader.readUInt32();
+  if (id !== magicNumber) throw new Error(`Expected MIDI "${chunkIdToString(magicNumber)}" chunk, got "${chunkIdToString(id)}"`);
+  const end = reader.pos + length;
+  if (end > reader.data.length) throw new Error(`MIDI "${chunkIdToString(magicNumber)}" chunk exceeds the input length`);
+  return end;
+};
+/** @type {(reader: SmfReader) => MidiHeader} */
+const parseHeader = (reader /* , end: number */) => {
+  const format = reader.readUInt16();
+  if (format > 2) throw new Error(`Unsupported MIDI format: ${format}`);
+  const numTracks = reader.readUInt16();
+  const timeDivision = reader.readUInt16();
+  const header = /** @type {MidiHeader} */ ({
+    format: format,
+    numTracks,
+  });
+  if (timeDivision & 0x8000) {
+    header.framesPerSecond = 0x100 - (timeDivision >> 8);
+    header.ticksPerFrame = timeDivision & 0xff;
+  } else {
+    header.ticksPerBeat = timeDivision;
+  }
+  return header;
+};
+/** @type {(reader: SmfReader, trackEnd: number, deltaTime: number, eventTypeByte: number) => MidiEvent} */
+const readSystemEvent = (reader, trackEnd, deltaTime, eventTypeByte) => {
+  if (eventTypeByte === 0xff) {
+    /** read `ESMFEventType` */
+    const type = reader.readUInt8();
+    const length = reader.readVarInt();
+    if (reader.pos + length > trackEnd) throw new Error("MIDI meta event exceeds its track chunk");
+    switch (type) {
+      case 0 /* ESMFEventType.sequenceNumber */:
+        return { deltaTime, type, number: reader.readUInt16() };
+      case 1 /* ESMFEventType.text */:
+      case 2 /* ESMFEventType.copyrightNotice */:
+      case 3 /* ESMFEventType.trackName */:
+      case 4 /* ESMFEventType.instrumentName */:
+      case 5 /* ESMFEventType.lyrics */:
+      case 6 /* ESMFEventType.marker */:
+      case 7 /* ESMFEventType.cuePoint */:
+        return { deltaTime, type, text: reader.readString(length) };
+      case 32 /* ESMFEventType.channelPrefix */:
+        return { deltaTime, type, channel: reader.readUInt8() };
+      case 33 /* ESMFEventType.portPrefix */:
+        return { deltaTime, type, port: reader.readUInt8() };
+      case 47 /* ESMFEventType.endOfTrack */:
+        return { deltaTime, type };
+      case 81 /* ESMFEventType.setTempo */:
+        return { deltaTime, type, microsecondsPerBeat: reader.readUInt24() };
+      case 84 /* ESMFEventType.smpteOffset */: {
+        const hourByte = reader.readUInt8();
+        return {
+          deltaTime,
+          type,
+          frameRate: FRAME_RATES[(hourByte >> 5) & 0x03],
+          hour: hourByte & 0x1f,
+          min: reader.readUInt8(),
+          sec: reader.readUInt8(),
+          frame: reader.readUInt8(),
+          subFrame: reader.readUInt8(),
+        };
+      }
+      case 88 /* ESMFEventType.timeSignature */: {
+        return {
+          deltaTime,
+          type,
+          numerator: reader.readUInt8(),
+          denominator: 1 << reader.readUInt8(),
+          metronome: length === 4 ? reader.readUInt8() : 0x24,
+          thirtyseconds: length === 4 ? reader.readUInt8() : 0x08,
+        };
+      }
+      case 89 /* ESMFEventType.keySignature */:
+        return { deltaTime, type, key: reader.readInt8(), scale: reader.readUInt8() };
+      case 127 /* ESMFEventType.sequencerSpecific */:
+        return { deltaTime, type, data: reader.readBytes(length) };
+      default:
+        return { deltaTime, type: -1 /* ESMFEventType.unknownMeta */, metatypeByte: type, data: reader.readBytes(length) };
+    }
+  }
+  if (eventTypeByte === 240 /* ESMFEventType.sysEx */ || eventTypeByte === 247 /* ESMFEventType.endSysEx */) {
+    const length = reader.readVarInt();
+    return {
+      deltaTime,
+      type: eventTypeByte,
+      data: reader.readBytes(length),
+    };
+  }
+  throw new Error(`Unrecognized MIDI event type byte: ${eventTypeByte}`);
+};
+/** @type {(reader: SmfReader, trackEnd: number) => MidiEvent[]} */
+const parseTrack = (reader, trackEnd) => {
+  /** @type {MidiEvent[]} */
+  const events = [];
+  const data = reader.data;
+  let lastEventTypeByte = null;
+  while (reader.pos < trackEnd) {
+    const deltaTime = reader.readVarInt();
+    let eventTypeByte = data[reader.pos++];
+    if ((eventTypeByte & 0xf0) === 0xf0) {
+      events.push(readSystemEvent(reader, trackEnd, deltaTime, eventTypeByte));
+      continue;
+    }
+    /** @type {number} */
+    let eventValue;
+    /** @type {number} */
+    let running;
+    if ((eventTypeByte & 0x80) === 0) {
+      if (lastEventTypeByte === null) throw new Error("Running status encountered before a channel status byte");
+      eventValue = eventTypeByte;
+      eventTypeByte = lastEventTypeByte;
+      running = 1;
+    } else {
+      eventValue = data[reader.pos++];
+      lastEventTypeByte = eventTypeByte;
+      running = 0;
+    }
+    const type = eventTypeByte >> 4;
+    const channel = eventTypeByte & 0x0f;
+    /** @type {MidiEvent} */
+    let event;
+    switch (type) {
+      case 8 /* ESMFEventType.noteOff */:
+        event = { deltaTime, type, channel, noteNumber: eventValue, velocity: data[reader.pos++] };
+        break;
+      case 9 /* ESMFEventType.noteOn */: {
+        const velocity = data[reader.pos++];
+        if (velocity === 0) event = { deltaTime, type: 8 /* ESMFEventType.noteOff */, channel, noteNumber: eventValue, velocity, byte9: true };
+        else event = { deltaTime, type, channel, noteNumber: eventValue, velocity };
+        break;
+      }
+      case 10 /* ESMFEventType.noteAftertouch */:
+        event = { deltaTime, type, channel, noteNumber: eventValue, amount: data[reader.pos++] };
+        break;
+      case 11 /* ESMFEventType.controller */:
+        event = { deltaTime, type, channel, controllerType: eventValue, value: data[reader.pos++] };
+        break;
+      case 12 /* ESMFEventType.programChange */:
+        event = { deltaTime, type, channel, programNumber: eventValue };
+        break;
+      case 13 /* ESMFEventType.channelAftertouch */:
+        event = { deltaTime, type, channel, amount: eventValue };
+        break;
+      case 14 /* ESMFEventType.pitchBend */:
+        event = { deltaTime, type, channel, value: eventValue + (data[reader.pos++] << 7) - 0x2000 };
+        break;
+      default:
+        throw new Error(`Unrecognized MIDI channel event type: ${type}`);
+    }
+    if (reader.pos > trackEnd) throw new Error("MIDI channel event exceeds its track chunk");
+    if (running) event.running = true;
+    events.push(event);
+  }
+  return events;
+};
+/**
+ * Parse a Standard MIDI File into numeric {@link ESMFEventType} events.
+ *
+ * The Uint8Array fast path parses all chunks through a shared cursor and does
+ * not copy complete track payloads. Other array-like inputs are normalized once.
+ *
+ * @param {ArrayLike<number> | ArrayBuffer} input
+ * @returns {MidiData}
+ */
+export const parseMidi = (input) => {
+  const data = input instanceof Uint8Array ? input : input instanceof ArrayBuffer ? new Uint8Array(input) : Uint8Array.from(input);
+  const reader = new SmfReader(data);
+  const headerEnd = readChunkEnd(reader, MTHD /* , "MThd" */);
+  const header = parseHeader(reader /* , headerEnd */);
+  reader.pos = headerEnd;
+  /** @type {MidiEvent[][]} */
+  const tracks = [];
+  for (let i = 0, L = header.numTracks; i++ < L;) {
+    const trackEnd = readChunkEnd(reader, MTRK /* , "MTrk" */);
+    tracks.push(parseTrack(reader, trackEnd));
+    reader.pos = trackEnd;
+  }
+  return { header, tracks };
+};

package/dist/smf-writer.d.ts

@@ -0,0 +1,53 @@
+/*!
+ * Original Source: midi-file (https://github.com/carter-thaxton/midi-file/blob/master/lib/midi-writer.js)
+ * Original License: MIT License
+ *
+ * This file is a reimplementation of the original midi-writer.js with performance optimizations.
+ * The core logic is preserved, but the Writer class is replaced with a more efficient
+ * implementation that pre-calculates the buffer size and writes directly to a Uint8Array.
+ *
+ * Copyright (c) 2025 jeffy-g
+ * Released under the MIT license.
+ */
+/**
+ * @file src/smf-writer.ts
+ */
+import type { MidiData, MidiWriteOption } from "./midi10-smf-types.ts";
+/**
+ * Returns the number of bytes required to encode a non-negative integer
+ * as a MIDI 1.0 Variable-Length Quantity (VLQ).
+ *
+ * VLQ encoding uses 7 bits of payload per byte; the MSB of each byte
+ * is a continuation flag (1 = more bytes follow, 0 = final byte).
+ * The MIDI 1.0 spec caps values at 4 bytes → max encodable value is
+ * `0x0FFF_FFFF` (268,435,455 / 28 bits).
+ *
+ * ```
+ * value range                 encoded bytes
+ * ─────────────────────────── ─────────────
+ * 0x0000_0000 – 0x0000_007F       1
+ * 0x0000_0080 – 0x0000_3FFF       2
+ * 0x0000_4000 – 0x001F_FFFF       3
+ * 0x0020_0000 – 0x0FFF_FFFF       4
+ * ```
+ *
+ * @see MIDI 1.0 Detailed Specification §2 — "Variable-Length Quantities"
+ *
+ * @param {number} value - A non-negative integer to encode as VLQ.
+ * @returns Byte count needed to hold the VLQ-encoded value (1–4).
+ * @throws {RangeError} If `value` is negative or exceeds `0x0FFF_FFFF`.
+ *
+ * @example
+ * getVarIntSize(0x0000_0000);  // → 1  (MIDI delta-time of 0)
+ * getVarIntSize(0x0000_007F);  // → 1
+ * getVarIntSize(0x0000_0080);  // → 2
+ * getVarIntSize(0x0FFF_FFFF);  // → 4  (spec maximum)
+ */
+export declare function getVarIntSize(value: number): number;
+/**
+ * Writes MIDI data to a Uint8Array.
+ * @param {MidiData} data The MIDI data to write.
+ * @param {MidiWriteOption=} opts Options for writing the MIDI file.
+ * @returns A Uint8Array containing the MIDI file data.
+ */
+export declare function writeMidi(data: MidiData, opts?: MidiWriteOption): Uint8Array;