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

package/ESMFEventType.d.ts

@@ -0,0 +1,119 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2026 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file live-midi-types/ESMFEventType.d.ts
+ */
+
+declare const enum ESMFEventType {
+  // Miscellaneous meta events
+  /**
+   * ```
+   * 0x00
+   * ```
+   */
+  sequenceNumber = 0,
+
+  // Text meta events
+  text,             // 1
+  copyrightNotice,  // 2
+  trackName,        // 3
+  instrumentName,   // 4
+  lyrics,           // 5
+  marker,           // 6
+  cuePoint,         // 7
+
+  // Channel voice events
+  noteOff = 0x08,   // 8
+  noteOn, // velocity === 0 ? 'noteOff' : 'noteOn'
+  noteAftertouch,   // 10
+  /**
+   * means control change event type.
+   * ```
+   * [0xb0 | event.channel][controllerType:0..127][value:0..127]
+   * ```
+   */
+  controller,       // 11
+  /**
+   * ```
+   * [0xc0 | event.channel][programNumber:0..127]
+   * ```
+   * @see {@linkcode https://midiprog.com/program-numbers/ Program Change Numbers}
+   */
+  programChange,    // 12
+  /**
+   * ```
+   * [0xd0 | event.channel][0..127]
+   * ```
+   */
+  channelAftertouch,// 13
+  /**
+   * ```
+   * [0xe0 | event.channel][LSB:0..127][MSB:0..127]
+   * ```
+   */
+  pitchBend,        // 14
+
+  // Tempo and channel prefix meta events
+  /**
+   * ```
+   * 0x20
+   * ```
+   */
+  channelPrefix = 0x20,   //
+  portPrefix,             // 33
+  /**
+   * ```
+   * 0x2F
+   * ```
+   */
+  endOfTrack = 0x2F,      // 47
+  /**
+   * ```
+   * 0x51
+   * ```
+   */
+  setTempo = 0x51,        // 81
+
+  // Meta utility events
+  /**
+   * ```
+   * 0x54
+   * ```
+   */
+  smpteOffset = 0x54,     // 84
+  /**
+   * ```
+   * 0x58
+   * ```
+   */
+  timeSignature = 0x58,   // 88
+  keySignature,           //
+
+  // System-exclusive events
+  /**
+   * ```
+   * 0x7F
+   * ```
+   */
+  sequencerSpecific = 0x7F,//127
+  /**
+   * ```
+   * 0xF0
+   * ```
+   */
+  sysEx = 0xF0, // 240 eventTypeByte
+  /**
+   * ```
+   * 0xF7
+   * ```
+   */
+  endSysEx = 0xF7,// 247 eventTypeByte
+
+  // Miscellaneous meta events
+  unknownMeta = -1,
+}

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.9.1";
+export declare const version = "v0.10.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.9.1";
+export const version = "v0.10.0";

package/dist/midi-clip.d.ts

@@ -9,7 +9,7 @@
  * @file src/midi-clip.ts
  * @summary Common MIDI clip data type for Ableton Live and related tools.
  */
-import type { NoteEvent, ControlChangeEvent } from "./midi-event.ts";
+import type { NoteEvent, MetaTextEvent, PitchBendEvent, ControlChangeEvent, ChannelPressureEvent } from "./midi-event.ts";
 /**
  * MIDI clip data extracted from Ableton Live's MidiClip object.
  *
@@ -68,6 +68,18 @@ export type TMidiClipData = {
    * @see {@link flattenCCEventMap}
    */
   cc?(): ControlChangeEvent[];
+  /**
+   * @since v0.10.0
+   */
+  pitchBends?: PitchBendEvent[];
+  /**
+   * @since v0.10.0
+   */
+  channelPressures?: ChannelPressureEvent[];
+  /**
+   * @since v0.10.0
+   */
+  meta?: MetaTextEvent[];
 };
 /**
  * @param {Record<string, ControlChangeEvent[]>} ccEventMap

package/dist/midi-event.d.ts

@@ -9,6 +9,7 @@
  * @file src/midi-event.ts
  * @summary Common MIDI event types for Ableton Live and related tools.
  */
+import type { TextEventTypesUnion } from "./midi10-smf-types.ts";
 export type BaseEvent = {
   /**
    * Time relative to the start of the clip.
@@ -100,6 +101,69 @@ export type TempoEvent = BaseEvent & {
    */
   bpm: number;
 };
+/**
+ * Shared processing shape for Control Change, Channel Pressure, and Pitch Bend
+ * envelope events extracted from an Ableton Live MIDI clip.
+ *
+ * + This is an intermediate event type, not an SMF wire event.
+ * + It retains beat-based time, fractional Live values, and optional interpolation diagnostics until the target-specific MIDI encoding step.
+ * + A Control Change carries `controller`, Pitch Bend and Channel Pressure do not.
+ *
+ * @see {@linkcode ControlChangeEvent}
+ * @see {@linkcode ChannelPressureEvent}
+ * @see {@linkcode PitchBendEvent}
+ *
+ * @since v0.10.0
+ */
+export type TEnvelopeEvent = BaseEvent & {
+  /**
+   * Floating-point envelope value in the target's native Live range.
+   *
+   * - Control Change / Channel Pressure: `0..127`
+   * - Pitch Bend: signed `-8192..8191` with center `0`
+   *
+   * Preserve fractional values while processing the envelope. At the SMF encode
+   * boundary, values are quantized with `Math.floor()`; Pitch Bend remains signed
+   * until the MIDI writer applies the single `+0x2000` conversion.
+   */
+  value: number;
+  /**
+   * MIDI controller number (`0..127`) for a Control Change event.
+   *
+   * Omitted for Pitch Bend and Channel Pressure. Their internal target numbers
+   * (`-2` and `-1`) identify envelope-map buckets and must not be stored here.
+   */
+  controller?: number;
+};
+/**
+ * @since v0.10.0
+ */
+export type MetaTextEvent = {
+  /** Time in quarter-note beats. */
+  time: number;
+  text: string;
+  type: TextEventTypesUnion;
+};
+/**
+ * @since v0.10.0
+ */
+export type TimeSignatureEvent = {
+  /** Time in quarter-note beats. */
+  time: number;
+  numerator: number;
+  denominator: number;
+  metronome?: number;
+  thirtyseconds?: number;
+};
+/**
+ * @since v0.10.0
+ */
+export type KeySignatureEvent = {
+  /** Time in quarter-note beats. */
+  time: number;
+  key: string;
+  scale: "major" | "minor";
+};
 /**
  * Type alias for MIDI event types.
  *

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

@@ -0,0 +1,184 @@
+/*!
+ * Original Source: midi-file (https://github.com/carter-thaxton/midi-file/blob/master/index.d.ts)
+ * Original License: MIT License
+ *
+ * + Adapted the original string-based `type` discriminants to use numeric SMF event type codes.
+ *
+ * Copyright (c) 2025 jeffy-g
+ * Released under the MIT license.
+ */
+/**
+ * @file src/midi10-smf-types.ts
+ */
+/// <reference path="../ESMFEventType.d.ts" preserve="true" />
+export interface MidiHeader {
+  format: 0 | 1 | 2;
+  numTracks: number;
+  timeDivision?: number;
+  framesPerSecond?: number;
+  ticksPerFrame?: number;
+  ticksPerBeat?: number;
+}
+export type TextEventTypesUnion = ESMFEventType.text | ESMFEventType.copyrightNotice | ESMFEventType.trackName | ESMFEventType.instrumentName | ESMFEventType.lyrics | ESMFEventType.marker | ESMFEventType.cuePoint;
+export interface MidiBaseEvent<T> {
+  /**
+   * serialize/deserialize by `writeVarInt/readVarInt`
+   * + byte range are __`1 to 4`__ (unsigned integer)
+   */
+  deltaTime: number;
+  /**
+   * MUST be `ESMFEventType`
+   * @see {@link ESMFEventType}
+   */
+  type: T;
+}
+export interface MidiMetaEvent<T> extends MidiBaseEvent<T> {
+  meta?: true;
+}
+export type MidiEndOfTrackEvent = MidiMetaEvent<ESMFEventType.endOfTrack>;
+export type FrameRate = 24 | 25 | 29.97 | 30;
+export interface MidiSmpteOffsetMixins {
+  frameRate: FrameRate;
+  hour: number;
+  min: number;
+  sec: number;
+  frame: number;
+  subFrame: number;
+}
+export type MidiSmpteOffsetEvent = MidiMetaEvent<ESMFEventType.smpteOffset> & MidiSmpteOffsetMixins;
+export interface MidiTimeSignatureMixins {
+  numerator: number;
+  denominator: number;
+  /** @todo whats this? */
+  metronome: number;
+  /** @todo whats this? */
+  thirtyseconds: number;
+}
+export type MidiTimeSignatureEvent = MidiMetaEvent<ESMFEventType.timeSignature> & MidiTimeSignatureMixins;
+export interface MidiKeySignatureMixins {
+  key: number;
+  scale: number;
+}
+export type MidiKeySignatureEvent = MidiMetaEvent<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 interface MidiUnknownMixins {
+  data: ArrayLike<number>;
+  metatypeByte: number;
+}
+export type MidiUnknownEvent = MidiMetaEvent<ESMFEventType.unknownMeta> & MidiUnknownMixins;
+export interface MidiNumberMixins {
+  number: number;
+}
+export type MidiSequenceNumberEvent = MidiMetaEvent<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> & {
+  /**
+   * __`unsigned 24-bit integer`__
+   */
+  microsecondsPerBeat: number;
+};
+export type MidiPortPrefixEvent = MidiMetaEvent<ESMFEventType.portPrefix> & {
+  port: number;
+};
+export type MidiChannelPrefixEvent = MidiMetaEvent<ESMFEventType.channelPrefix> & {
+  channel: number;
+};
+export interface MidiNoteMixins {
+  noteNumber: number;
+  /**
+   * __`unsigned 7-bit integer`__
+   * + `0 to 127(0x7f)`
+   */
+  velocity: number;
+  byte9?: true;
+}
+export type MidiNoteOnEvent = MidiChannelEvent<ESMFEventType.noteOn> & MidiNoteMixins;
+export type MidiNoteOffEvent = MidiChannelEvent<ESMFEventType.noteOff> & MidiNoteMixins;
+export interface MidiNoteAftertouchMixins {
+  noteNumber: number;
+  amount: number;
+}
+export type MidiNoteAftertouchEvent = MidiChannelEvent<ESMFEventType.noteAftertouch> & MidiNoteAftertouchMixins;
+export interface MidiControllerMixins {
+  controllerType: number;
+  /**
+   * __`unsigned 7-bit integer`__
+   * + `0 to 127(0x7f)`
+   */
+  value: number;
+}
+export interface MidiChannelEvent<T> extends MidiBaseEvent<T> {
+  running?: true;
+  channel: number;
+}
+export type MidiPitchBendEvent = MidiChannelEvent<ESMFEventType.pitchBend> & {
+  /**
+   * __`SPEC`__: 14bit `-8192 to 8191` (integer)
+   */
+  value: number;
+};
+/**
+ * @see {@link https://anotherproducer.com/online-tools-for-musicians/midi-cc-list/ MIDI CC List for Continuous Controllers}
+ */
+export type MidiControllerEvent = MidiChannelEvent<ESMFEventType.controller> & MidiControllerMixins;
+export type MidiProgramChangeEvent = MidiChannelEvent<ESMFEventType.programChange> & {
+  programNumber: number;
+};
+export type MidiChannelAftertouchEvent = MidiChannelEvent<ESMFEventType.channelAftertouch> & {
+  amount: number;
+};
+export type MidiEvent =
+  | MidiTextEvent
+  | MidiSysExEvent
+  | MidiLyricsEvent
+  | MidiMarkerEvent
+  | MidiNoteOnEvent
+  | MidiNoteOffEvent
+  | MidiUnknownEvent
+  | MidiCuePointEvent
+  | MidiEndSysExEvent
+  | MidiSetTempoEvent
+  | MidiPitchBendEvent
+  | MidiTrackNameEvent
+  | MidiControllerEvent
+  | MidiEndOfTrackEvent
+  | MidiPortPrefixEvent
+  | MidiSmpteOffsetEvent
+  | MidiKeySignatureEvent
+  | MidiChannelPrefixEvent
+  | MidiProgramChangeEvent
+  | MidiTimeSignatureEvent
+  | MidiInstrumentNameEvent
+  | MidiNoteAftertouchEvent
+  | MidiSequenceNumberEvent
+  | MidiCopyrightNoticeEvent
+  | MidiChannelAftertouchEvent
+  | MidiSequencerSpecificEvent;
+export interface MidiData {
+  header: MidiHeader;
+  tracks: MidiEvent[][];
+}
+export interface MidiWriteOption {
+  /**
+   * reuse previous eventTypeByte when possible, to compress file
+   */
+  running?: boolean;
+  /**
+   * use 0x09 for noteOff when velocity is zero
+   */
+  useByte9ForNoteOff?: boolean;
+}

package/dist/midi10-smf-types.js

@@ -0,0 +1,14 @@
+/*!
+ * Original Source: midi-file (https://github.com/carter-thaxton/midi-file/blob/master/index.d.ts)
+ * Original License: MIT License
+ *
+ * + Adapted the original string-based `type` discriminants to use numeric SMF event type codes.
+ *
+ * Copyright (c) 2025 jeffy-g
+ * Released under the MIT license.
+ */
+/// <reference path="../ESMFEventType.d.ts" preserve="true"/>
+/**
+ * @file src/midi10-smf-types.ts
+ */
+export {};

package/dist/project.d.ts

@@ -8,7 +8,7 @@
 /**
  * @file src/project.ts
  */
-import type { TempoEvent } from "./midi-event.ts";
+import type { TempoEvent, MetaTextEvent, TimeSignatureEvent, KeySignatureEvent } from "./midi-event.ts";
 /**
  * Summary information for an Ableton Live MIDI clip.
  */
@@ -137,6 +137,10 @@ export type TTrackInfo<T extends Record<string, any>> = {
    * MIDI clips indexed by {@linkcode TClipSummary.id TClipSummary.id}
    */
   clips: Record<string, TClipSummary<T>>;
+  /**
+   * @since v0.10.0
+   */
+  meta?: MetaTextEvent[];
 };
 /**
  * Parsed data required by the Ableton Live project UI.
@@ -170,4 +174,12 @@ export type TParsedAbletonLiveSet<T extends Record<string, any>> = {
    * ```
    */
   tempoAutomation: TempoEvent[];
+  /**
+   * @since v0.10.0
+   */
+  timeSignatures?: TimeSignatureEvent[];
+  /**
+   * @since v0.10.0
+   */
+  keySignatures?: KeySignatureEvent[];
 };

package/dist/smf-event-type.d.ts

@@ -0,0 +1,105 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file live-midi-types/src/smf-event-type.ts
+ */
+export declare const ESMFEventType: {
+  /**
+   * ```
+   * 0x00
+   * ```
+   */
+  readonly sequenceNumber: 0;
+  readonly text: 1;
+  readonly copyrightNotice: 2;
+  readonly trackName: 3;
+  readonly instrumentName: 4;
+  readonly lyrics: 5;
+  readonly marker: 6;
+  readonly cuePoint: 7;
+  readonly noteOff: 8;
+  readonly noteOn: 9;
+  readonly noteAftertouch: 10;
+  /**
+   * means control change event type.
+   * ```
+   * [0xb0 | event.channel][controllerType:0..127][value:0..127]
+   * ```
+   */
+  readonly controller: 11;
+  /**
+   * ```
+   * [0xc0 | event.channel][programNumber:0..127]
+   * ```
+   * @see {@linkcode https://midiprog.com/program-numbers/ Program Change Numbers}
+   */
+  readonly programChange: 12;
+  /**
+   * ```
+   * [0xd0 | event.channel][0..127]
+   * ```
+   */
+  readonly channelAftertouch: 13;
+  /**
+   * ```
+   * [0xe0 | event.channel][LSB:0..127][MSB:0..127]
+   * ```
+   */
+  readonly pitchBend: 14;
+  /**
+   * ```
+   * 0x20
+   * ```
+   */
+  readonly channelPrefix: 32;
+  readonly portPrefix: 33;
+  /**
+   * ```
+   * 0x2F
+   * ```
+   */
+  readonly endOfTrack: 47;
+  /**
+   * ```
+   * 0x51
+   * ```
+   */
+  readonly setTempo: 81;
+  /**
+   * ```
+   * 0x54
+   * ```
+   */
+  readonly smpteOffset: 84;
+  /**
+   * ```
+   * 0x58
+   * ```
+   */
+  readonly timeSignature: 88;
+  readonly keySignature: 89;
+  /**
+   * ```
+   * 0x7F
+   * ```
+   */
+  readonly sequencerSpecific: 127;
+  /**
+   * ```
+   * 0xF0
+   * ```
+   */
+  readonly sysEx: 240;
+  /**
+   * ```
+   * 0xF7
+   * ```
+   */
+  readonly endSysEx: 247;
+  readonly unknownMeta: -1;
+};

package/dist/smf-event-type.js

@@ -0,0 +1,105 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file live-midi-types/src/smf-event-type.ts
+ */
+export const ESMFEventType = {
+  /**
+   * ```
+   * 0x00
+   * ```
+   */
+  sequenceNumber: 0,
+  text: 1,
+  copyrightNotice: 2,
+  trackName: 3,
+  instrumentName: 4,
+  lyrics: 5,
+  marker: 6,
+  cuePoint: 7,
+  noteOff: 8,
+  noteOn: 9,
+  noteAftertouch: 10,
+  /**
+   * means control change event type.
+   * ```
+   * [0xb0 | event.channel][controllerType:0..127][value:0..127]
+   * ```
+   */
+  controller: 11,
+  /**
+   * ```
+   * [0xc0 | event.channel][programNumber:0..127]
+   * ```
+   * @see {@linkcode https://midiprog.com/program-numbers/ Program Change Numbers}
+   */
+  programChange: 12,
+  /**
+   * ```
+   * [0xd0 | event.channel][0..127]
+   * ```
+   */
+  channelAftertouch: 13,
+  /**
+   * ```
+   * [0xe0 | event.channel][LSB:0..127][MSB:0..127]
+   * ```
+   */
+  pitchBend: 14,
+  /**
+   * ```
+   * 0x20
+   * ```
+   */
+  channelPrefix: 0x20,
+  portPrefix: 0x21,
+  /**
+   * ```
+   * 0x2F
+   * ```
+   */
+  endOfTrack: 0x2f,
+  /**
+   * ```
+   * 0x51
+   * ```
+   */
+  setTempo: 0x51,
+  /**
+   * ```
+   * 0x54
+   * ```
+   */
+  smpteOffset: 0x54,
+  /**
+   * ```
+   * 0x58
+   * ```
+   */
+  timeSignature: 0x58,
+  keySignature: 0x59,
+  /**
+   * ```
+   * 0x7F
+   * ```
+   */
+  sequencerSpecific: 0x7f,
+  /**
+   * ```
+   * 0xF0
+   * ```
+   */
+  sysEx: 0xf0,
+  /**
+   * ```
+   * 0xF7
+   * ```
+   */
+  endSysEx: 0xf7,
+  unknownMeta: -1,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffy-g/live-midi-types",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Common TypeScript types for Ableton Live MIDI clip and event data.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,10 +10,24 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./midi10-smf-types": {
+      "import": "./dist/midi10-smf-types.js",
+      "require": "./dist/midi10-smf-types.js",
+      "types": "./dist/midi10-smf-types.d.ts"
+    },
+    "./smf-event-type": {
+      "import": "./dist/smf-event-type.js",
+      "require": "./dist/smf-event-type.js",
+      "types": "./dist/smf-event-type.d.ts"
+    },
+    "./ESMFEventType": {
+      "types": "./ESMFEventType.d.ts"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "ESMFEventType.d.ts"
   ],
   "author": "jeffy-g <hirotom1107@gmail.com>",
   "license": "MIT",