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

package/README.md

@@ -1,164 +1,266 @@
-# **@jeffy-g/live-midi-types** — TypeScript type definitions for Ableton Live MIDI data projects.
+# @jeffy-g/live-midi-types
 
 [![npm version](https://img.shields.io/npm/v/@jeffy-g/live-midi-types.svg)](https://www.npmjs.com/package/@jeffy-g/live-midi-types)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Common TypeScript type definitions for working with Ableton Live MIDI data.
+Shared TypeScript types and small runtime helpers for Ableton Live MIDI clip data, project summaries, and Standard MIDI Files.
 
-> ## Description
+## Scope
 
-This package provides a centralized collection of TypeScript type definitions for working with data extracted from Ableton Live Set (`.als`) files.
+The package provides three related contracts:
 
-It is designed to ensure type safety and data consistency across projects that handle Ableton Live's MIDI data, such as the `live-midi-export` tool.
+- beat-based MIDI events and clip data extracted from Ableton Live Sets;
+- application-facing clip, track, and project summaries;
+- numeric MIDI 1.0 SMF event types for parsers and writers.
 
-By providing a single source of truth for data structures, this library simplifies development and reduces errors when passing MIDI and project data between different modules.
+The Ableton data shapes were reverse engineered from observed Live 11 and Live 12 `.als` documents. Ableton does not publish an official `.als` specification, so consumers should expect the model to grow as more real projects are inspected.
 
-> ## Type Origin and Gaps
-
-These definitions were **reverse engineered** from Ableton Live 11 `.als` files.  
-Ableton publishes no official specification, so some fields may be missing or misinterpreted.  
-If you encounter inaccuracies, please open an issue or pull request.
-
-> ## Directory Structure
-
-```
-src/
-├─ midi-event.ts      # basic note, control change, and tempo events
-├─ midi-clip.ts       # builds on midi-event to describe clips
-├─ project.ts         # aggregates clips into a project
-├─ ableton-colors.ts  # color utilities
-└─ index.ts           # public exports
-```
-
-Dependencies flow upward: `midi-event` → `midi-clip` → `project`, while `ableton-colors` stands alone.
-
-> ## Installation
-
-You can install the package using npm or yarn:
+## Installation
 
 ```sh
 npm install @jeffy-g/live-midi-types
 ```
 
-or
+## Entry points
 
-```sh
-yarn add @jeffy-g/live-midi-types
-```
+| Entry point | Contents |
+|---|---|
+| `@jeffy-g/live-midi-types` | Ableton MIDI events, clip data, project summaries, color helpers, and runtime utilities |
+| `@jeffy-g/live-midi-types/midi10-smf-types` | MIDI 1.0 SMF header, event, file, and writer option types |
+| `@jeffy-g/live-midi-types/midi10-smf-io` | MIDI 1.0 SMF parser, writer, and VLQ size helper |
+| `@jeffy-g/live-midi-types/ESMFEventType` | Runtime numeric SMF event type constants |
 
-> ## Usage
+## Ableton MIDI clip data
 
-Import the types you need directly into your TypeScript files.
+`TMidiClipData` stores beat-based source data. MIDI CC events are grouped by controller in `ccMap`; `knownCCEvents` determines which controller buckets are present and their traversal order.
 
 ```ts
-import type { TMidiClipData, NoteEvent, ControlChangeEvent, TempoEvent } from "@jeffy-g/live-midi-types";
-
-/** @type {NoteEvent} */
-const note = {
-  time: 0.0,
-  duration: 1.0,
+import {
+  flattenCCEventMap,
+  type ControlChangeEvent,
+  type NoteEvent,
+  type TMidiClipData,
+} from "@jeffy-g/live-midi-types";
+
+const note: NoteEvent = {
+  time: 0,
+  duration: 1,
   pitch: 60,
-  velocity: 100
+  velocity: 100,
 };
 
-/** @type {ControlChangeEvent} */
-const cc = {
+const sustain: ControlChangeEvent = {
   time: 0.5,
   controller: 64,
   value: 127,
-  source: "single"
-};
-
-/** @type {TempoEvent} */
-const tempo = {
-  time: 0.0,
-  bpm: 120
+  source: "linear",
 };
 
-/** @type {TMidiClipData} */
-const clip = {
-  clipStartInBeats: 0,
-  clipLength: 16,
+const clip: TMidiClipData = {
+  clipStartInBeats: 8,
+  clipLength: 4,
   adjustTimeOftempee: 0,
-  knownCCEvents: [64, 1],
+  knownCCEvents: [64],
   notes: [note],
-  cc: [cc]
+  ccMap: {
+    "64": [sustain],
+  },
+  pitchBends: [
+    { time: 1, value: -4096 },
+    { time: 2, value: 4096, source: "bezier" },
+  ],
+  channelPressures: [
+    { time: 1.5, value: 96 },
+  ],
 };
+
+const controlChanges = flattenCCEventMap(
+  clip.ccMap,
+  clip.knownCCEvents,
+);
 ```
 
-Ableton Live color palette and utility functions:
+### Event value contracts
+
+All event `time` values are floating point quarter-note beats relative to the start of the clip.
+
+| Type | Value contract |
+|---|---|
+| `NoteEvent` | `duration` and `velocity` may be fractional; `pitch` is an integer from `0` to `127` |
+| `ControlChangeEvent` | `controller` is an integer from `0` to `127`; `value` may remain fractional in the `0..127` range |
+| `ChannelPressureEvent` | `value` may remain fractional in the `0..127` range |
+| `PitchBendEvent` | signed, possibly fractional Live value from `-8192` to `8191` |
+| `TempoEvent` | floating point BPM |
+
+`BaseEvent.source` is optional interpolation metadata. It is either `"linear"` or `"bezier"` and is normally omitted for original or discrete events.
+
+`TEnvelopeEvent` is the shared processing shape for Control Change, Channel Pressure, and Pitch Bend envelopes. Its `controller` property is present only for Control Change. Pitch Bend and Channel Pressure remain in their dedicated arrays and do not use negative controller numbers in serialized event data.
+
+`TMidiClipData.cc?()` is an optional compatibility helper. New code should treat `ccMap` as the stored representation and call `flattenCCEventMap()` when it needs one time-sorted CC array.
+
+### Clip metadata
+
+The following optional event collections were added in version 0.10:
+
+- `pitchBends?: PitchBendEvent[]`
+- `channelPressures?: ChannelPressureEvent[]`
+- `meta?: MetaTextEvent[]`
+
+The root entry point also exports `TimeSignatureEvent` and `KeySignatureEvent` for project-level musical metadata.
+
+## Project summaries
+
+The project types add application IDs and display metadata to clip data. `TTrackInfo.clips` is a map keyed by each `TClipSummary.id`.
 
 ```ts
-import { abletonColorPalette, getColorFromIndex } from "@jeffy-g/live-midi-types";
+import type {
+  TMidiClipData,
+  TClipSummary,
+  TParsedAbletonLiveSet,
+  TTrackInfo,
+} from "@jeffy-g/live-midi-types";
+
+declare const clip: TMidiClipData;
+
+const clipSummary: TClipSummary<TMidiClipData> = {
+  originId: "0",
+  id: "clip-6e8c",
+  color: "0",
+  disabled: false,
+  clipName: "Piano",
+  trackName: "Track 1",
+  annotation: "",
+  ...clip,
+};
 
-const color: string = getColorFromIndex(5); // "#1aff2f"
+const track: TTrackInfo<TMidiClipData> = {
+  originId: "12",
+  id: "track-91d2",
+  name: "Track 1",
+  color: "0",
+  annotation: "",
+  clips: {
+    [clipSummary.id]: clipSummary,
+  },
+};
+
+const project: TParsedAbletonLiveSet<TMidiClipData> = {
+  alsName: "MyProject",
+  ticksPerQuarter: 480,
+  tracks: [track],
+  tempoAutomation: [{ time: 0, bpm: 120 }],
+};
 ```
 
-Project & UI types:
+`color` is the Ableton palette index stored as a string. Convert it to a CSS color with `getColorFromIndex()`.
+
+## MIDI 1.0 SMF types
+
+SMF types use numeric `ESMFEventType` discriminants. Meta events do not carry a separate marker property; their numeric `type` identifies them. Import the runtime constants and type declarations from their dedicated entry points.
 
 ```ts
-import type { TClipSummary, TTrackInfo, TParsedAbletonLiveSet } from "@jeffy-g/live-midi-types";
-
-/** @type {TClipSummary<{custom: string}>} */
-const clipSummary = {
-    id: "clip-XXXX",
-    color: "#ff94a6",
-    disabled: false,
-    clipName: "Piano",
-    trackName: "Track 1",
-    custom: "meta"
+import { ESMFEventType } from "@jeffy-g/live-midi-types/ESMFEventType";
+import type {
+  MidiData,
+  MidiEndOfTrackEvent,
+  MidiNoteOnEvent,
+} from "@jeffy-g/live-midi-types/midi10-smf-types";
+
+const noteOn: MidiNoteOnEvent = {
+  deltaTime: 0,
+  type: ESMFEventType.noteOn,
+  channel: 0,
+  noteNumber: 60,
+  velocity: 100,
 };
 
-/** @type {TTrackInfo<{custom: string}>} */
-const trackInfo = {
-    name: "Track 1",
-    color: "#ff94a6",
-    clips: {
-        "Piano": clipSummary
-    }
+const endOfTrack: MidiEndOfTrackEvent = {
+  deltaTime: 480,
+  type: ESMFEventType.endOfTrack,
 };
 
-/** @type {TParsedAbletonLiveSet<{custom: string}>} */
-const project = {
-    alsName: "MyProject",
-    ticksPerQuarter: 480,
-    tracks: [trackInfo]
+const midi: MidiData = {
+  header: {
+    format: 0,
+    numTracks: 1,
+    ticksPerBeat: 480,
+  },
+  tracks: [[noteOn, endOfTrack]],
 };
 ```
 
-> ## Core Type Definitions (Reference)
+### SMF parser and writer
+
+The codec entry point parses MIDI bytes into `MidiData` and writes the same numeric event contract back to a `Uint8Array`.
+
+```ts
+import {
+  parseMidi,
+  writeMidi,
+} from "@jeffy-g/live-midi-types/midi10-smf-io";
+
+declare const source: Uint8Array;
+
+const parsed = parseMidi(source);
+const encoded = writeMidi(parsed, {
+  running: true,
+});
+```
+
+`getVarIntSize()` is also exported from this entry point for code that needs to calculate the encoded byte size of an SMF variable-length quantity.
 
-### MIDI Event Types
+The SMF contract includes:
 
-- **`NoteEvent`**: `{ time: number; duration: number; pitch: number; velocity: number; }` — Represents a single MIDI note. All values are float except pitch (int).
-- **`ControlChangeEvent`**: `{ time: number; controller: number; value: number; source?: "curve" | "single"; }` — MIDI CC message, with optional source type.
-- **`TempoEvent`**: `{ time: number; bpm: number; }` — Tempo change event.
+- format 0, 1, and 2 headers;
+- channel voice events, including Note On/Off, CC, Program Change, Channel Aftertouch, and signed Pitch Bend;
+- tempo, time signature, key signature, text, and other meta events;
+- SysEx, sequencer-specific, and unknown meta events;
+- running-status and velocity-zero Note On writer options.
 
-### MIDI Clip Types
+SMF event values are wire-boundary values. In particular, `MidiPitchBendEvent.value` remains signed from `-8192` to `8191`; a writer performs the 14-bit unsigned conversion when encoding the two data bytes.
 
-- **`TMidiClipData`**: Represents all essential data for a single MIDI clip.
-  - `clipStartInBeats`: Start time in beats.
-  - `clipLength`: Duration in beats.
-  - `adjustTimeOftempee`: Time adjustment for tempo mapping.
-  - `knownCCEvents`: Array of CC numbers present in the clip.
-  - `notes`: Array of `NoteEvent`.
-  - `cc`: Array of `ControlChangeEvent`.
+## Runtime helpers
 
-### Project & UI Types
+The root entry point includes a small set of runtime exports:
 
-- **`TClipSummary<T>`**: Generic summary type for a clip, with `id`, `color`, `clipName`, `trackName`, and custom fields.
-- **`TTrackInfo<T>`**: Track info type, with `name`, `color`, and a collection of `TClipSummary` objects.
-- **`TParsedAbletonLiveSet<T>`**: Parsed project type, with `alsName`, `ticksPerQuarter`, and array of tracks.
+```ts
+import {
+  abletonColorPalette,
+  eventsIs,
+  flattenCCEventMap,
+  getColorFromIndex,
+  version,
+} from "@jeffy-g/live-midi-types";
+
+const color = getColorFromIndex(5); // "#1aff2f"
+```
+
+- `flattenCCEventMap()` flattens the listed controller buckets and sorts the result by event time.
+- `eventsIs()` identifies note, CC, or tempo event arrays from their first event.
+- `getColorFromIndex()` returns the Ableton palette color or `"#888"` for an unknown index.
+- `version` exposes the package source version string.
 
-### Ableton Color Utilities
+## Source layout
 
-- **`abletonColorPalette`**: Array of 70+ Ableton Live color hex codes.
-- **`getColorFromIndex(index: number): string`**: Returns color code for given index, fallback is gray ("#888").
+```text
+src/
+├─ midi-event.ts          # beat-based Ableton event contracts
+├─ midi-clip.ts           # clip data and CC map flattening
+├─ project.ts             # clip, track, and project summaries
+├─ midi10-smf-types.ts    # MIDI 1.0 SMF type declarations
+├─ midi10-smf-io.ts       # SMF codec entry point
+├─ smf-parser.ts          # numeric SMF parser
+├─ smf-writer.ts          # numeric SMF writer
+├─ ESMFEventType.ts       # numeric SMF enum declarations
+├─ smf-event-type.ts      # runtime numeric SMF constants
+├─ ableton-colors.ts      # Live palette and color lookup
+└─ index.ts               # root package exports
+```
 
-> ## License
+## Related project
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+- [live-midi-export](https://github.com/jeffy-g/live-midi-export) extracts MIDI clips and project metadata from Ableton Live Sets.
 
-> ## Related Projects
+## License
 
-- [live-midi-export](https://github.com/jeffy-g/live-midi-export) — CLI tool for extracting MIDI clips from Ableton Live sets.
+MIT

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export declare const version = "v0.10.1";
+export declare const version = "v0.11.0";

package/dist/index.js

@@ -12,4 +12,4 @@ export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export const version = "v0.10.1";
+export const version = "v0.11.0";

package/dist/midi-clip.d.ts

@@ -31,8 +31,8 @@ export type TMidiClipData = {
    *
    * ```
    * // e.g. obtain `midiClip` object
-   * // xpath: "/Ableton/LiveSet/Tracks/MidiTrack[0]/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip[0]"
-   * const midiClip = Ableton.LiveSet.Tracks.MidiTrack[0].DeviceChain.MainSequencer.ClipTimeable.ArrangerAutomation.Events.MidiClip[0];
+   * // xpath: "/Ableton/LiveSet/Tracks/MidiTrack[1]/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip[1]"
+   * const midiClip = Ableton.LiveSet.Tracks.MidiTrack[1].DeviceChain.MainSequencer.ClipTimeable.ArrangerAutomation.Events.MidiClip[1];
    * // clip start position in Live arrangement view
    * const clipStart = midiClip.CurrentStart.Value;
    * // clip end position in Live arrangement view
@@ -57,10 +57,12 @@ export type TMidiClipData = {
    */
   notes: NoteEvent[];
   /**
-   * Control change event map. (key: cc number)
+   * Control change event map. (key: cc number, `0..127`)
    * @version 0.8.0
    */
-  ccMap: Record<string, ControlChangeEvent[]>;
+  ccMap: {
+    [ccNumber: `${number}`]: ControlChangeEvent[];
+  };
   /**
    * Array of extracted control change events. (flatten {@link TMidiClipData.ccMap __`ccMap`__}, sort by time)
    * + use `flattenCCEventMap` (recommended)

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

@@ -0,0 +1,12 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2026 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file live-midi-types/src/midi10-smf-io.ts
+ */
+export * from "./smf-parser.js";
+export * from "./smf-writer.js";

package/dist/midi10-smf-io.js

@@ -0,0 +1,12 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2026 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file live-midi-types/src/midi10-smf-io.ts
+ */
+export * from "./smf-parser.js";
+export * from "./smf-writer.js";

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

@@ -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/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
    */

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;