@jeffy-g/live-midi-types 0.10.0 → 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/{ESMFEventType.d.ts → dist/ESMFEventType.d.ts}

@@ -6,114 +6,100 @@
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /**
- * @file live-midi-types/ESMFEventType.d.ts
+ * @file live-midi-types/src/ESMFEventType.ts
  */
-
-declare const enum ESMFEventType {
-  // Miscellaneous meta events
+export declare const enum ESMFEventType {
   /**
    * ```
    * 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
+  text = 1, // 1
+  copyrightNotice = 2, // 2
+  trackName = 3, // 3
+  instrumentName = 4, // 4
+  lyrics = 5, // 5
+  marker = 6, // 6
+  cuePoint = 7, // 7
+  noteOff = 8, // 8
+  noteOn = 9, // velocity === 0 ? 'noteOff' : 'noteOn'
+  noteAftertouch = 10, // 10
   /**
    * means control change event type.
    * ```
    * [0xb0 | event.channel][controllerType:0..127][value:0..127]
    * ```
    */
-  controller,       // 11
+  controller = 11, // 11
   /**
    * ```
    * [0xc0 | event.channel][programNumber:0..127]
    * ```
    * @see {@linkcode https://midiprog.com/program-numbers/ Program Change Numbers}
    */
-  programChange,    // 12
+  programChange = 12, // 12
   /**
    * ```
    * [0xd0 | event.channel][0..127]
    * ```
    */
-  channelAftertouch,// 13
+  channelAftertouch = 13, // 13
   /**
    * ```
    * [0xe0 | event.channel][LSB:0..127][MSB:0..127]
    * ```
    */
-  pitchBend,        // 14
-
-  // Tempo and channel prefix meta events
+  pitchBend = 14, // 14
   /**
    * ```
    * 0x20
    * ```
    */
-  channelPrefix = 0x20,   //
-  portPrefix,             // 33
+  channelPrefix = 32, //
+  portPrefix = 33, // 33
   /**
    * ```
    * 0x2F
    * ```
    */
-  endOfTrack = 0x2F,      // 47
+  endOfTrack = 47, // 47
   /**
    * ```
    * 0x51
    * ```
    */
-  setTempo = 0x51,        // 81
-
-  // Meta utility events
+  setTempo = 81, // 81
   /**
    * ```
    * 0x54
    * ```
    */
-  smpteOffset = 0x54,     // 84
+  smpteOffset = 84, // 84
   /**
    * ```
    * 0x58
    * ```
    */
-  timeSignature = 0x58,   // 88
-  keySignature,           //
-
-  // System-exclusive events
+  timeSignature = 88, // 88
+  keySignature = 89, //
   /**
    * ```
    * 0x7F
    * ```
    */
-  sequencerSpecific = 0x7F,//127
+  sequencerSpecific = 127, //127
   /**
    * ```
    * 0xF0
    * ```
    */
-  sysEx = 0xF0, // 240 eventTypeByte
+  sysEx = 240, // 240 eventTypeByte
   /**
    * ```
    * 0xF7
    * ```
    */
-  endSysEx = 0xF7,// 247 eventTypeByte
-
-  // Miscellaneous meta events
+  endSysEx = 247, // 247 eventTypeByte
   unknownMeta = -1,
 }

package/dist/ESMFEventType.js

@@ -0,0 +1,11 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  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/ESMFEventType.ts
+ */
+export {};

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.0";
+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.0";
+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";