@utilix-tech/sdk 0.70.0 → 0.71.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.71.0
+- Add `readMidiInfo` (midi-file-info): parse a Standard MIDI File's header and every track chunk to report format, tick division, initial tempo, time signature, and per-track event/note-on counts, plus total duration in seconds accounting for tempo changes.
+
 ## 0.70.0
 - Add `generateHotp`, `generateTotp` (totp-hotp-generator): generate an HOTP code (RFC 4226) for a counter value, or the current TOTP code (RFC 6238) plus seconds until rotation, from a base32-encoded shared secret, supporting SHA-1/SHA-256/SHA-512 and 6-8 digit codes.
 - Add `calculateTaxEquivalentYield` (tax-equivalent-yield-calculator): convert between a tax-free municipal bond yield and its taxable equivalent given a marginal federal (plus optional state) tax rate, in both directions.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**691 developer utility functions for Node.js: runs locally, no API key required.**
+**692 developer utility functions for Node.js: runs locally, no API key required.**
 
 [![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
@@ -876,10 +876,10 @@ analyzeString("café");          // { length: 4, codePoints: [...], ... }
 
 ---
 
-### `/media`: Image Header Parsing, EXIF, PDF Metadata & Page Dimensions, WAV, ID3, ICO, FLAC, Video & GIF Metadata
+### `/media`: Image Header Parsing, EXIF, PDF Metadata & Page Dimensions, WAV, ID3, ICO, FLAC, Video, GIF & MIDI Metadata
 
 ```ts
-import { readImageInfo, readExifData, readPdfMetadata, readPdfPageDimensions, readWavInfo, readId3Tags, readIcoInfo, readFlacInfo, readVideoInfo, inspectGifFrames } from "@utilix-tech/sdk/media";
+import { readImageInfo, readExifData, readPdfMetadata, readPdfPageDimensions, readWavInfo, readId3Tags, readIcoInfo, readFlacInfo, readVideoInfo, inspectGifFrames, readMidiInfo } from "@utilix-tech/sdk/media";
 
 // Reads format, dimensions, bit depth, and alpha channel straight from
 // file bytes: no decoding, no canvas, no image library.
@@ -945,9 +945,17 @@ readVideoInfo(new Uint8Array(videoBytes));
 const gifBytes = await fs.promises.readFile("animation.gif");
 inspectGifFrames(new Uint8Array(gifBytes));
 // { version: "89a", width: 480, height: 270, frameCount: 24, animated: true, loopCount: 0, totalDurationMs: 2400, ... }
+
+// Parses a Standard MIDI File's header and every track chunk to report
+// format, tick division, initial tempo, time signature, and per-track
+// event/note-on counts, plus total duration in seconds: no MIDI playback
+// or synthesis.
+const midiBytes = await fs.promises.readFile("song.mid");
+readMidiInfo(new Uint8Array(midiBytes));
+// { format: 1, trackCount: 2, initialTempoBpm: 120, timeSignature: { numerator: 4, denominator: 4 }, durationSeconds: 4, tracks: [...] }
 ```
 
-`readImageInfo` supports PNG, JPEG, GIF, WebP, and BMP. `readExifData` supports JPEG only. `readWavInfo` supports the canonical RIFF/WAVE container only. `readId3Tags` decodes ID3v2.3/2.4 and ID3v1/1.1 only (ID3v2.2 is detected but not decoded). `readIcoInfo` reads .ico icon files only and rejects .cur cursor files. `readFlacInfo` reads the native FLAC container only, not FLAC-in-Ogg. `readVideoInfo` supports MP4 (ISO BMFF) and WebM (EBML/Matroska) containers only. `inspectGifFrames` reads the GIF87a/89a block structure only; it never decodes pixel data.
+`readImageInfo` supports PNG, JPEG, GIF, WebP, and BMP. `readExifData` supports JPEG only. `readWavInfo` supports the canonical RIFF/WAVE container only. `readId3Tags` decodes ID3v2.3/2.4 and ID3v1/1.1 only (ID3v2.2 is detected but not decoded). `readIcoInfo` reads .ico icon files only and rejects .cur cursor files. `readFlacInfo` reads the native FLAC container only, not FLAC-in-Ogg. `readVideoInfo` supports MP4 (ISO BMFF) and WebM (EBML/Matroska) containers only. `inspectGifFrames` reads the GIF87a/89a block structure only; it never decodes pixel data. `readMidiInfo` reads Standard MIDI Files (format 0/1/2) only.
 
 ---
 

package/dist/{chunk-226EH3ZI.js → chunk-PT4N4UBL.js}

@@ -9,6 +9,7 @@ __export(media_exports, {
   readIcoInfo: () => readIcoInfo,
   readId3Tags: () => readId3Tags,
   readImageInfo: () => readImageInfo,
+  readMidiInfo: () => readMidiInfo,
   readPdfMetadata: () => readPdfMetadata,
   readPdfPageDimensions: () => readPdfPageDimensions,
   readVideoInfo: () => readVideoInfo,
@@ -1306,5 +1307,135 @@ function inspectGifFrames(bytes) {
     hasTransparency
   };
 }
+function readU16BE(bytes, offset) {
+  return bytes[offset] << 8 | bytes[offset + 1];
+}
+function readMidiVarLen(bytes, pos) {
+  let value = 0;
+  let i = pos;
+  for (let n = 0; n < 4; n++) {
+    if (i >= bytes.length) return null;
+    const b = bytes[i];
+    value = value << 7 | b & 127;
+    i++;
+    if ((b & 128) === 0) return { value, next: i };
+  }
+  return null;
+}
+function readMidiInfo(bytes) {
+  if (bytes.length < 14) return { error: "File is too small to be a valid MIDI file" };
+  if (Buffer.from(bytes.subarray(0, 4)).toString("ascii") !== "MThd") {
+    return { error: 'Not a valid MIDI file (missing "MThd" header chunk)' };
+  }
+  const headerLength = readU32BE(bytes, 4);
+  if (headerLength < 6 || 8 + headerLength > bytes.length) return { error: "Truncated or invalid MThd header chunk" };
+  const format = readU16BE(bytes, 8);
+  if (format !== 0 && format !== 1 && format !== 2) return { error: `Unsupported MIDI format: ${format} (expected 0, 1, or 2)` };
+  const trackCount = readU16BE(bytes, 10);
+  if (trackCount < 1) return { error: "MIDI file declares zero tracks" };
+  const divisionRaw = readU16BE(bytes, 12);
+  const division = (divisionRaw & 32768) !== 0 ? { type: "smpte", framesPerSecond: -(divisionRaw >> 8 << 24 >> 24), ticksPerFrame: divisionRaw & 255 } : { type: "ppq", ticksPerQuarterNote: divisionRaw & 32767 };
+  const tracks = [];
+  const tempoChanges = [];
+  let timeSignature = null;
+  let maxEndTick = 0;
+  let offset = 8 + headerLength;
+  let tracksParsed = 0;
+  while (tracksParsed < trackCount && offset + 8 <= bytes.length) {
+    const chunkId = Buffer.from(bytes.subarray(offset, offset + 4)).toString("ascii");
+    const chunkLength = readU32BE(bytes, offset + 4);
+    const dataStart = offset + 8;
+    const dataEnd = Math.min(dataStart + chunkLength, bytes.length);
+    if (chunkId !== "MTrk") {
+      offset = dataEnd;
+      continue;
+    }
+    let pos = dataStart;
+    let runningStatus = 0;
+    let absoluteTick = 0;
+    let eventCount = 0;
+    let noteOnCount = 0;
+    let name = null;
+    while (pos < dataEnd) {
+      const delta = readMidiVarLen(bytes, pos);
+      if (!delta) break;
+      pos = delta.next;
+      absoluteTick += delta.value;
+      if (pos >= dataEnd) break;
+      let statusByte = bytes[pos];
+      if (statusByte & 128) {
+        runningStatus = statusByte;
+        pos++;
+      }
+      statusByte = runningStatus;
+      eventCount++;
+      if (statusByte === 255) {
+        const metaType = bytes[pos];
+        pos++;
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next;
+        const data = bytes.subarray(pos, Math.min(pos + len.value, dataEnd));
+        pos += len.value;
+        if (metaType === 81 && data.length >= 3) {
+          tempoChanges.push({ tick: absoluteTick, usPerQuarter: data[0] << 16 | data[1] << 8 | data[2] });
+        } else if (metaType === 88 && data.length >= 2) {
+          if (!timeSignature) timeSignature = { numerator: data[0], denominator: 2 ** data[1] };
+        } else if (metaType === 3 && name === null) {
+          name = Buffer.from(data).toString("utf8").trim() || null;
+        } else if (metaType === 47) {
+          break;
+        }
+      } else if (statusByte === 240 || statusByte === 247) {
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next + len.value;
+      } else if (statusByte >= 128) {
+        const type = statusByte & 240;
+        if (type === 192 || type === 208) {
+          pos += 1;
+        } else {
+          if (type === 144 && (bytes[pos + 1] ?? 0) > 0) noteOnCount++;
+          pos += 2;
+        }
+      } else {
+        break;
+      }
+    }
+    tracks.push({ index: tracksParsed, name, eventCount, noteOnCount });
+    maxEndTick = Math.max(maxEndTick, absoluteTick);
+    offset = dataEnd;
+    tracksParsed++;
+  }
+  if (tracks.length === 0) return { error: "No MTrk track chunks found in this MIDI file" };
+  const DEFAULT_US_PER_QUARTER = 5e5;
+  const initialTempoBpm = Math.round(6e7 / (tempoChanges[0]?.usPerQuarter ?? DEFAULT_US_PER_QUARTER) * 100) / 100;
+  let durationSeconds = null;
+  if (division.type === "smpte") {
+    const ticksPerSecond = division.framesPerSecond * division.ticksPerFrame;
+    durationSeconds = ticksPerSecond > 0 ? Math.round(maxEndTick / ticksPerSecond * 1e3) / 1e3 : null;
+  } else {
+    const sorted = [...tempoChanges].sort((a, b) => a.tick - b.tick);
+    let seconds = 0;
+    let prevTick = 0;
+    let currentUsPerQuarter = DEFAULT_US_PER_QUARTER;
+    for (const change of sorted) {
+      seconds += (change.tick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+      prevTick = change.tick;
+      currentUsPerQuarter = change.usPerQuarter;
+    }
+    seconds += (maxEndTick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+    durationSeconds = Math.round(seconds * 1e3) / 1e3;
+  }
+  return {
+    format,
+    trackCount: tracks.length,
+    division,
+    initialTempoBpm,
+    timeSignature,
+    durationSeconds,
+    tracks
+  };
+}
 
-export { inspectGifFrames, media_exports, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readPdfMetadata, readPdfPageDimensions, readVideoInfo, readWavInfo };
+export { inspectGifFrames, media_exports, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readMidiInfo, readPdfMetadata, readPdfPageDimensions, readVideoInfo, readWavInfo };

package/dist/index.cjs

@@ -24357,6 +24357,7 @@ __export(media_exports, {
   readIcoInfo: () => readIcoInfo,
   readId3Tags: () => readId3Tags,
   readImageInfo: () => readImageInfo,
+  readMidiInfo: () => readMidiInfo,
   readPdfMetadata: () => readPdfMetadata,
   readPdfPageDimensions: () => readPdfPageDimensions,
   readVideoInfo: () => readVideoInfo,
@@ -25654,6 +25655,136 @@ function inspectGifFrames(bytes) {
     hasTransparency
   };
 }
+function readU16BE(bytes, offset) {
+  return bytes[offset] << 8 | bytes[offset + 1];
+}
+function readMidiVarLen(bytes, pos) {
+  let value = 0;
+  let i = pos;
+  for (let n = 0; n < 4; n++) {
+    if (i >= bytes.length) return null;
+    const b = bytes[i];
+    value = value << 7 | b & 127;
+    i++;
+    if ((b & 128) === 0) return { value, next: i };
+  }
+  return null;
+}
+function readMidiInfo(bytes) {
+  if (bytes.length < 14) return { error: "File is too small to be a valid MIDI file" };
+  if (Buffer.from(bytes.subarray(0, 4)).toString("ascii") !== "MThd") {
+    return { error: 'Not a valid MIDI file (missing "MThd" header chunk)' };
+  }
+  const headerLength = readU32BE(bytes, 4);
+  if (headerLength < 6 || 8 + headerLength > bytes.length) return { error: "Truncated or invalid MThd header chunk" };
+  const format = readU16BE(bytes, 8);
+  if (format !== 0 && format !== 1 && format !== 2) return { error: `Unsupported MIDI format: ${format} (expected 0, 1, or 2)` };
+  const trackCount = readU16BE(bytes, 10);
+  if (trackCount < 1) return { error: "MIDI file declares zero tracks" };
+  const divisionRaw = readU16BE(bytes, 12);
+  const division = (divisionRaw & 32768) !== 0 ? { type: "smpte", framesPerSecond: -(divisionRaw >> 8 << 24 >> 24), ticksPerFrame: divisionRaw & 255 } : { type: "ppq", ticksPerQuarterNote: divisionRaw & 32767 };
+  const tracks = [];
+  const tempoChanges = [];
+  let timeSignature = null;
+  let maxEndTick = 0;
+  let offset = 8 + headerLength;
+  let tracksParsed = 0;
+  while (tracksParsed < trackCount && offset + 8 <= bytes.length) {
+    const chunkId = Buffer.from(bytes.subarray(offset, offset + 4)).toString("ascii");
+    const chunkLength = readU32BE(bytes, offset + 4);
+    const dataStart = offset + 8;
+    const dataEnd = Math.min(dataStart + chunkLength, bytes.length);
+    if (chunkId !== "MTrk") {
+      offset = dataEnd;
+      continue;
+    }
+    let pos = dataStart;
+    let runningStatus = 0;
+    let absoluteTick = 0;
+    let eventCount = 0;
+    let noteOnCount = 0;
+    let name = null;
+    while (pos < dataEnd) {
+      const delta = readMidiVarLen(bytes, pos);
+      if (!delta) break;
+      pos = delta.next;
+      absoluteTick += delta.value;
+      if (pos >= dataEnd) break;
+      let statusByte = bytes[pos];
+      if (statusByte & 128) {
+        runningStatus = statusByte;
+        pos++;
+      }
+      statusByte = runningStatus;
+      eventCount++;
+      if (statusByte === 255) {
+        const metaType = bytes[pos];
+        pos++;
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next;
+        const data = bytes.subarray(pos, Math.min(pos + len.value, dataEnd));
+        pos += len.value;
+        if (metaType === 81 && data.length >= 3) {
+          tempoChanges.push({ tick: absoluteTick, usPerQuarter: data[0] << 16 | data[1] << 8 | data[2] });
+        } else if (metaType === 88 && data.length >= 2) {
+          if (!timeSignature) timeSignature = { numerator: data[0], denominator: 2 ** data[1] };
+        } else if (metaType === 3 && name === null) {
+          name = Buffer.from(data).toString("utf8").trim() || null;
+        } else if (metaType === 47) {
+          break;
+        }
+      } else if (statusByte === 240 || statusByte === 247) {
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next + len.value;
+      } else if (statusByte >= 128) {
+        const type = statusByte & 240;
+        if (type === 192 || type === 208) {
+          pos += 1;
+        } else {
+          if (type === 144 && (bytes[pos + 1] ?? 0) > 0) noteOnCount++;
+          pos += 2;
+        }
+      } else {
+        break;
+      }
+    }
+    tracks.push({ index: tracksParsed, name, eventCount, noteOnCount });
+    maxEndTick = Math.max(maxEndTick, absoluteTick);
+    offset = dataEnd;
+    tracksParsed++;
+  }
+  if (tracks.length === 0) return { error: "No MTrk track chunks found in this MIDI file" };
+  const DEFAULT_US_PER_QUARTER = 5e5;
+  const initialTempoBpm = Math.round(6e7 / (tempoChanges[0]?.usPerQuarter ?? DEFAULT_US_PER_QUARTER) * 100) / 100;
+  let durationSeconds = null;
+  if (division.type === "smpte") {
+    const ticksPerSecond = division.framesPerSecond * division.ticksPerFrame;
+    durationSeconds = ticksPerSecond > 0 ? Math.round(maxEndTick / ticksPerSecond * 1e3) / 1e3 : null;
+  } else {
+    const sorted = [...tempoChanges].sort((a, b) => a.tick - b.tick);
+    let seconds = 0;
+    let prevTick = 0;
+    let currentUsPerQuarter = DEFAULT_US_PER_QUARTER;
+    for (const change of sorted) {
+      seconds += (change.tick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+      prevTick = change.tick;
+      currentUsPerQuarter = change.usPerQuarter;
+    }
+    seconds += (maxEndTick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+    durationSeconds = Math.round(seconds * 1e3) / 1e3;
+  }
+  return {
+    format,
+    trackCount: tracks.length,
+    division,
+    initialTempoBpm,
+    timeSignature,
+    durationSeconds,
+    tracks
+  };
+}
 
 // src/index.ts
 var version = "0.1.0";

package/dist/index.d.cts

@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.cjs';
 export { c as css } from './css-Cf7AMGM-.cjs';
 export { m as misc } from './misc-CA3N198T.cjs';
 export { a as ai_agent } from './ai_agent-CmrVjvYH.cjs';
-export { m as media } from './media-BUvwm4wU.cjs';
+export { m as media } from './media-56zrIBw4.cjs';
 
 declare const version = "0.1.0";
 

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.js';
 export { c as css } from './css-Cf7AMGM-.js';
 export { m as misc } from './misc-CA3N198T.js';
 export { a as ai_agent } from './ai_agent-CmrVjvYH.js';
-export { m as media } from './media-BUvwm4wU.js';
+export { m as media } from './media-56zrIBw4.js';
 
 declare const version = "0.1.0";
 

package/dist/index.js

@@ -1,4 +1,4 @@
-export { media_exports as media } from './chunk-226EH3ZI.js';
+export { media_exports as media } from './chunk-PT4N4UBL.js';
 export { units_exports as units } from './chunk-653HDWXW.js';
 export { network_exports as network } from './chunk-ACGCCOCK.js';
 export { api_exports as api } from './chunk-4S63T7Y4.js';

package/dist/{media-BUvwm4wU.d.cts → media-56zrIBw4.d.cts}

@@ -224,6 +224,45 @@ interface GifInfoError {
  * any LZW-compressed pixel data.
  */
 declare function inspectGifFrames(bytes: Uint8Array): GifInfo | GifInfoError;
+type MidiDivision = {
+    type: 'ppq';
+    ticksPerQuarterNote: number;
+} | {
+    type: 'smpte';
+    framesPerSecond: number;
+    ticksPerFrame: number;
+};
+interface MidiTrackInfo {
+    index: number;
+    name: string | null;
+    eventCount: number;
+    noteOnCount: number;
+}
+interface MidiTimeSignature {
+    numerator: number;
+    denominator: number;
+}
+interface MidiInfo {
+    format: number;
+    trackCount: number;
+    division: MidiDivision;
+    initialTempoBpm: number;
+    timeSignature: MidiTimeSignature | null;
+    durationSeconds: number | null;
+    tracks: MidiTrackInfo[];
+}
+interface MidiInfoError {
+    error: string;
+}
+/**
+ * Parse a Standard MIDI File (SMF) header and every track chunk to report
+ * format (0/1/2), the tick division, initial tempo, time signature, a
+ * per-track event/note-on count, and total duration in seconds. Duration
+ * accounts for tempo-change meta events across the whole file when the
+ * division is ticks-per-quarter-note; the rarer SMPTE division uses a fixed
+ * frames-per-second/ticks-per-frame rate instead.
+ */
+declare function readMidiInfo(bytes: Uint8Array): MidiInfo | MidiInfoError;
 
 type media_ExifData = ExifData;
 type media_ExifError = ExifError;
@@ -239,6 +278,11 @@ type media_Id3TagsError = Id3TagsError;
 type media_ImageFormat = ImageFormat;
 type media_ImageInfo = ImageInfo;
 type media_ImageInfoError = ImageInfoError;
+type media_MidiDivision = MidiDivision;
+type media_MidiInfo = MidiInfo;
+type media_MidiInfoError = MidiInfoError;
+type media_MidiTimeSignature = MidiTimeSignature;
+type media_MidiTrackInfo = MidiTrackInfo;
 type media_PdfMetadata = PdfMetadata;
 type media_PdfMetadataError = PdfMetadataError;
 type media_PdfPageDimension = PdfPageDimension;
@@ -254,12 +298,13 @@ declare const media_readFlacInfo: typeof readFlacInfo;
 declare const media_readIcoInfo: typeof readIcoInfo;
 declare const media_readId3Tags: typeof readId3Tags;
 declare const media_readImageInfo: typeof readImageInfo;
+declare const media_readMidiInfo: typeof readMidiInfo;
 declare const media_readPdfMetadata: typeof readPdfMetadata;
 declare const media_readPdfPageDimensions: typeof readPdfPageDimensions;
 declare const media_readVideoInfo: typeof readVideoInfo;
 declare const media_readWavInfo: typeof readWavInfo;
 declare namespace media {
-  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfPageDimensions as readPdfPageDimensions, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
+  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_MidiDivision as MidiDivision, type media_MidiInfo as MidiInfo, type media_MidiInfoError as MidiInfoError, type media_MidiTimeSignature as MidiTimeSignature, type media_MidiTrackInfo as MidiTrackInfo, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readMidiInfo as readMidiInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfPageDimensions as readPdfPageDimensions, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
 }
 
-export { readWavInfo as A, type ExifData as E, type FlacInfo as F, type GifInfo as G, type IcoImageEntry as I, type PdfMetadata as P, type VideoInfo as V, type WavInfo as W, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type PdfMetadataError as k, type PdfPageDimension as l, media as m, type PdfPageDimensionsResult as n, type PdfPageOrientation as o, type VideoInfoError as p, type WavInfoError as q, inspectGifFrames as r, readExifData as s, readFlacInfo as t, readIcoInfo as u, readId3Tags as v, readImageInfo as w, readPdfMetadata as x, readPdfPageDimensions as y, readVideoInfo as z };
+export { readImageInfo as A, readMidiInfo as B, readPdfMetadata as C, readPdfPageDimensions as D, type ExifData as E, type FlacInfo as F, type GifInfo as G, readVideoInfo as H, type IcoImageEntry as I, readWavInfo as J, type MidiDivision as M, type PdfMetadata as P, type VideoInfo as V, type WavInfo as W, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type MidiInfo as k, type MidiInfoError as l, media as m, type MidiTimeSignature as n, type MidiTrackInfo as o, type PdfMetadataError as p, type PdfPageDimension as q, type PdfPageDimensionsResult as r, type PdfPageOrientation as s, type VideoInfoError as t, type WavInfoError as u, inspectGifFrames as v, readExifData as w, readFlacInfo as x, readIcoInfo as y, readId3Tags as z };

package/dist/{media-BUvwm4wU.d.ts → media-56zrIBw4.d.ts}

@@ -224,6 +224,45 @@ interface GifInfoError {
  * any LZW-compressed pixel data.
  */
 declare function inspectGifFrames(bytes: Uint8Array): GifInfo | GifInfoError;
+type MidiDivision = {
+    type: 'ppq';
+    ticksPerQuarterNote: number;
+} | {
+    type: 'smpte';
+    framesPerSecond: number;
+    ticksPerFrame: number;
+};
+interface MidiTrackInfo {
+    index: number;
+    name: string | null;
+    eventCount: number;
+    noteOnCount: number;
+}
+interface MidiTimeSignature {
+    numerator: number;
+    denominator: number;
+}
+interface MidiInfo {
+    format: number;
+    trackCount: number;
+    division: MidiDivision;
+    initialTempoBpm: number;
+    timeSignature: MidiTimeSignature | null;
+    durationSeconds: number | null;
+    tracks: MidiTrackInfo[];
+}
+interface MidiInfoError {
+    error: string;
+}
+/**
+ * Parse a Standard MIDI File (SMF) header and every track chunk to report
+ * format (0/1/2), the tick division, initial tempo, time signature, a
+ * per-track event/note-on count, and total duration in seconds. Duration
+ * accounts for tempo-change meta events across the whole file when the
+ * division is ticks-per-quarter-note; the rarer SMPTE division uses a fixed
+ * frames-per-second/ticks-per-frame rate instead.
+ */
+declare function readMidiInfo(bytes: Uint8Array): MidiInfo | MidiInfoError;
 
 type media_ExifData = ExifData;
 type media_ExifError = ExifError;
@@ -239,6 +278,11 @@ type media_Id3TagsError = Id3TagsError;
 type media_ImageFormat = ImageFormat;
 type media_ImageInfo = ImageInfo;
 type media_ImageInfoError = ImageInfoError;
+type media_MidiDivision = MidiDivision;
+type media_MidiInfo = MidiInfo;
+type media_MidiInfoError = MidiInfoError;
+type media_MidiTimeSignature = MidiTimeSignature;
+type media_MidiTrackInfo = MidiTrackInfo;
 type media_PdfMetadata = PdfMetadata;
 type media_PdfMetadataError = PdfMetadataError;
 type media_PdfPageDimension = PdfPageDimension;
@@ -254,12 +298,13 @@ declare const media_readFlacInfo: typeof readFlacInfo;
 declare const media_readIcoInfo: typeof readIcoInfo;
 declare const media_readId3Tags: typeof readId3Tags;
 declare const media_readImageInfo: typeof readImageInfo;
+declare const media_readMidiInfo: typeof readMidiInfo;
 declare const media_readPdfMetadata: typeof readPdfMetadata;
 declare const media_readPdfPageDimensions: typeof readPdfPageDimensions;
 declare const media_readVideoInfo: typeof readVideoInfo;
 declare const media_readWavInfo: typeof readWavInfo;
 declare namespace media {
-  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfPageDimensions as readPdfPageDimensions, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
+  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_MidiDivision as MidiDivision, type media_MidiInfo as MidiInfo, type media_MidiInfoError as MidiInfoError, type media_MidiTimeSignature as MidiTimeSignature, type media_MidiTrackInfo as MidiTrackInfo, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readMidiInfo as readMidiInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfPageDimensions as readPdfPageDimensions, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
 }
 
-export { readWavInfo as A, type ExifData as E, type FlacInfo as F, type GifInfo as G, type IcoImageEntry as I, type PdfMetadata as P, type VideoInfo as V, type WavInfo as W, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type PdfMetadataError as k, type PdfPageDimension as l, media as m, type PdfPageDimensionsResult as n, type PdfPageOrientation as o, type VideoInfoError as p, type WavInfoError as q, inspectGifFrames as r, readExifData as s, readFlacInfo as t, readIcoInfo as u, readId3Tags as v, readImageInfo as w, readPdfMetadata as x, readPdfPageDimensions as y, readVideoInfo as z };
+export { readImageInfo as A, readMidiInfo as B, readPdfMetadata as C, readPdfPageDimensions as D, type ExifData as E, type FlacInfo as F, type GifInfo as G, readVideoInfo as H, type IcoImageEntry as I, readWavInfo as J, type MidiDivision as M, type PdfMetadata as P, type VideoInfo as V, type WavInfo as W, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type MidiInfo as k, type MidiInfoError as l, media as m, type MidiTimeSignature as n, type MidiTrackInfo as o, type PdfMetadataError as p, type PdfPageDimension as q, type PdfPageDimensionsResult as r, type PdfPageOrientation as s, type VideoInfoError as t, type WavInfoError as u, inspectGifFrames as v, readExifData as w, readFlacInfo as x, readIcoInfo as y, readId3Tags as z };

package/dist/tools/media.cjs

@@ -1293,6 +1293,136 @@ function inspectGifFrames(bytes) {
     hasTransparency
   };
 }
+function readU16BE(bytes, offset) {
+  return bytes[offset] << 8 | bytes[offset + 1];
+}
+function readMidiVarLen(bytes, pos) {
+  let value = 0;
+  let i = pos;
+  for (let n = 0; n < 4; n++) {
+    if (i >= bytes.length) return null;
+    const b = bytes[i];
+    value = value << 7 | b & 127;
+    i++;
+    if ((b & 128) === 0) return { value, next: i };
+  }
+  return null;
+}
+function readMidiInfo(bytes) {
+  if (bytes.length < 14) return { error: "File is too small to be a valid MIDI file" };
+  if (Buffer.from(bytes.subarray(0, 4)).toString("ascii") !== "MThd") {
+    return { error: 'Not a valid MIDI file (missing "MThd" header chunk)' };
+  }
+  const headerLength = readU32BE(bytes, 4);
+  if (headerLength < 6 || 8 + headerLength > bytes.length) return { error: "Truncated or invalid MThd header chunk" };
+  const format = readU16BE(bytes, 8);
+  if (format !== 0 && format !== 1 && format !== 2) return { error: `Unsupported MIDI format: ${format} (expected 0, 1, or 2)` };
+  const trackCount = readU16BE(bytes, 10);
+  if (trackCount < 1) return { error: "MIDI file declares zero tracks" };
+  const divisionRaw = readU16BE(bytes, 12);
+  const division = (divisionRaw & 32768) !== 0 ? { type: "smpte", framesPerSecond: -(divisionRaw >> 8 << 24 >> 24), ticksPerFrame: divisionRaw & 255 } : { type: "ppq", ticksPerQuarterNote: divisionRaw & 32767 };
+  const tracks = [];
+  const tempoChanges = [];
+  let timeSignature = null;
+  let maxEndTick = 0;
+  let offset = 8 + headerLength;
+  let tracksParsed = 0;
+  while (tracksParsed < trackCount && offset + 8 <= bytes.length) {
+    const chunkId = Buffer.from(bytes.subarray(offset, offset + 4)).toString("ascii");
+    const chunkLength = readU32BE(bytes, offset + 4);
+    const dataStart = offset + 8;
+    const dataEnd = Math.min(dataStart + chunkLength, bytes.length);
+    if (chunkId !== "MTrk") {
+      offset = dataEnd;
+      continue;
+    }
+    let pos = dataStart;
+    let runningStatus = 0;
+    let absoluteTick = 0;
+    let eventCount = 0;
+    let noteOnCount = 0;
+    let name = null;
+    while (pos < dataEnd) {
+      const delta = readMidiVarLen(bytes, pos);
+      if (!delta) break;
+      pos = delta.next;
+      absoluteTick += delta.value;
+      if (pos >= dataEnd) break;
+      let statusByte = bytes[pos];
+      if (statusByte & 128) {
+        runningStatus = statusByte;
+        pos++;
+      }
+      statusByte = runningStatus;
+      eventCount++;
+      if (statusByte === 255) {
+        const metaType = bytes[pos];
+        pos++;
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next;
+        const data = bytes.subarray(pos, Math.min(pos + len.value, dataEnd));
+        pos += len.value;
+        if (metaType === 81 && data.length >= 3) {
+          tempoChanges.push({ tick: absoluteTick, usPerQuarter: data[0] << 16 | data[1] << 8 | data[2] });
+        } else if (metaType === 88 && data.length >= 2) {
+          if (!timeSignature) timeSignature = { numerator: data[0], denominator: 2 ** data[1] };
+        } else if (metaType === 3 && name === null) {
+          name = Buffer.from(data).toString("utf8").trim() || null;
+        } else if (metaType === 47) {
+          break;
+        }
+      } else if (statusByte === 240 || statusByte === 247) {
+        const len = readMidiVarLen(bytes, pos);
+        if (!len) break;
+        pos = len.next + len.value;
+      } else if (statusByte >= 128) {
+        const type = statusByte & 240;
+        if (type === 192 || type === 208) {
+          pos += 1;
+        } else {
+          if (type === 144 && (bytes[pos + 1] ?? 0) > 0) noteOnCount++;
+          pos += 2;
+        }
+      } else {
+        break;
+      }
+    }
+    tracks.push({ index: tracksParsed, name, eventCount, noteOnCount });
+    maxEndTick = Math.max(maxEndTick, absoluteTick);
+    offset = dataEnd;
+    tracksParsed++;
+  }
+  if (tracks.length === 0) return { error: "No MTrk track chunks found in this MIDI file" };
+  const DEFAULT_US_PER_QUARTER = 5e5;
+  const initialTempoBpm = Math.round(6e7 / (tempoChanges[0]?.usPerQuarter ?? DEFAULT_US_PER_QUARTER) * 100) / 100;
+  let durationSeconds = null;
+  if (division.type === "smpte") {
+    const ticksPerSecond = division.framesPerSecond * division.ticksPerFrame;
+    durationSeconds = ticksPerSecond > 0 ? Math.round(maxEndTick / ticksPerSecond * 1e3) / 1e3 : null;
+  } else {
+    const sorted = [...tempoChanges].sort((a, b) => a.tick - b.tick);
+    let seconds = 0;
+    let prevTick = 0;
+    let currentUsPerQuarter = DEFAULT_US_PER_QUARTER;
+    for (const change of sorted) {
+      seconds += (change.tick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+      prevTick = change.tick;
+      currentUsPerQuarter = change.usPerQuarter;
+    }
+    seconds += (maxEndTick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+    durationSeconds = Math.round(seconds * 1e3) / 1e3;
+  }
+  return {
+    format,
+    trackCount: tracks.length,
+    division,
+    initialTempoBpm,
+    timeSignature,
+    durationSeconds,
+    tracks
+  };
+}
 
 exports.inspectGifFrames = inspectGifFrames;
 exports.readExifData = readExifData;
@@ -1300,6 +1430,7 @@ exports.readFlacInfo = readFlacInfo;
 exports.readIcoInfo = readIcoInfo;
 exports.readId3Tags = readId3Tags;
 exports.readImageInfo = readImageInfo;
+exports.readMidiInfo = readMidiInfo;
 exports.readPdfMetadata = readPdfMetadata;
 exports.readPdfPageDimensions = readPdfPageDimensions;
 exports.readVideoInfo = readVideoInfo;

package/dist/tools/media.d.cts

@@ -1 +1 @@
-export { E as ExifData, a as ExifError, F as FlacInfo, b as FlacInfoError, G as GifInfo, c as GifInfoError, I as IcoImageEntry, d as IcoInfo, e as IcoInfoError, f as Id3Tags, g as Id3TagsError, h as ImageFormat, i as ImageInfo, j as ImageInfoError, P as PdfMetadata, k as PdfMetadataError, l as PdfPageDimension, n as PdfPageDimensionsResult, o as PdfPageOrientation, V as VideoInfo, p as VideoInfoError, W as WavInfo, q as WavInfoError, r as inspectGifFrames, s as readExifData, t as readFlacInfo, u as readIcoInfo, v as readId3Tags, w as readImageInfo, x as readPdfMetadata, y as readPdfPageDimensions, z as readVideoInfo, A as readWavInfo } from '../media-BUvwm4wU.cjs';
+export { E as ExifData, a as ExifError, F as FlacInfo, b as FlacInfoError, G as GifInfo, c as GifInfoError, I as IcoImageEntry, d as IcoInfo, e as IcoInfoError, f as Id3Tags, g as Id3TagsError, h as ImageFormat, i as ImageInfo, j as ImageInfoError, M as MidiDivision, k as MidiInfo, l as MidiInfoError, n as MidiTimeSignature, o as MidiTrackInfo, P as PdfMetadata, p as PdfMetadataError, q as PdfPageDimension, r as PdfPageDimensionsResult, s as PdfPageOrientation, V as VideoInfo, t as VideoInfoError, W as WavInfo, u as WavInfoError, v as inspectGifFrames, w as readExifData, x as readFlacInfo, y as readIcoInfo, z as readId3Tags, A as readImageInfo, B as readMidiInfo, C as readPdfMetadata, D as readPdfPageDimensions, H as readVideoInfo, J as readWavInfo } from '../media-56zrIBw4.cjs';

package/dist/tools/media.d.ts

@@ -1 +1 @@
-export { E as ExifData, a as ExifError, F as FlacInfo, b as FlacInfoError, G as GifInfo, c as GifInfoError, I as IcoImageEntry, d as IcoInfo, e as IcoInfoError, f as Id3Tags, g as Id3TagsError, h as ImageFormat, i as ImageInfo, j as ImageInfoError, P as PdfMetadata, k as PdfMetadataError, l as PdfPageDimension, n as PdfPageDimensionsResult, o as PdfPageOrientation, V as VideoInfo, p as VideoInfoError, W as WavInfo, q as WavInfoError, r as inspectGifFrames, s as readExifData, t as readFlacInfo, u as readIcoInfo, v as readId3Tags, w as readImageInfo, x as readPdfMetadata, y as readPdfPageDimensions, z as readVideoInfo, A as readWavInfo } from '../media-BUvwm4wU.js';
+export { E as ExifData, a as ExifError, F as FlacInfo, b as FlacInfoError, G as GifInfo, c as GifInfoError, I as IcoImageEntry, d as IcoInfo, e as IcoInfoError, f as Id3Tags, g as Id3TagsError, h as ImageFormat, i as ImageInfo, j as ImageInfoError, M as MidiDivision, k as MidiInfo, l as MidiInfoError, n as MidiTimeSignature, o as MidiTrackInfo, P as PdfMetadata, p as PdfMetadataError, q as PdfPageDimension, r as PdfPageDimensionsResult, s as PdfPageOrientation, V as VideoInfo, t as VideoInfoError, W as WavInfo, u as WavInfoError, v as inspectGifFrames, w as readExifData, x as readFlacInfo, y as readIcoInfo, z as readId3Tags, A as readImageInfo, B as readMidiInfo, C as readPdfMetadata, D as readPdfPageDimensions, H as readVideoInfo, J as readWavInfo } from '../media-56zrIBw4.js';

package/dist/tools/media.js

@@ -1,2 +1,2 @@
-export { inspectGifFrames, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readPdfMetadata, readPdfPageDimensions, readVideoInfo, readWavInfo } from '../chunk-226EH3ZI.js';
+export { inspectGifFrames, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readMidiInfo, readPdfMetadata, readPdfPageDimensions, readVideoInfo, readWavInfo } from '../chunk-PT4N4UBL.js';
 import '../chunk-MLKGABMK.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilix-tech/sdk",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "154+ developer utility tools for Node.js: JSON, encoding, hashing, color, CSS, network and more. Runs locally, no API key required.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",