@jeffy-g/live-midi-types 0.8.1 → 0.8.3

package/dist/ableton-colors.js

@@ -28,5 +28,5 @@ export const abletonColorPalette = "#ff94a6:#ffa529:#cc9927:#f7f47c:#bffb00:#1af
  * @returns {string} Hex color code.
  */
 export function getColorFromIndex(colorIndex) {
-  return abletonColorPalette[colorIndex] ?? "#888"; // fallback gray
+  return abletonColorPalette[colorIndex] ?? "#888";
 }

package/dist/index.d.ts

@@ -1,5 +1,15 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  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/index.ts
+ */
 export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export declare const version = "v0.8.1";
+export declare const version = "v0.8.3";

package/dist/index.js

@@ -1,5 +1,15 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  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/index.ts
+ */
 export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export const version = "v0.8.1";
+export const version = "v0.8.3";

package/dist/midi-clip.d.ts

@@ -28,6 +28,18 @@ export type TMidiClipData = {
   clipStartInBeats: number;
   /**
    * Length of the clip (in beats). Usually `CurrentEnd.Value - CurrentStart.Value`.
+   *
+   * ```
+   * // 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];
+   * // clip start position in Live arrangement view
+   * const clipStart = midiClip.CurrentStart.Value;
+   * // clip end position in Live arrangement view
+   * const clipEnd = midiClip.CurrentEnd.Value;
+   * // calculate clip range
+   * const clipLength = +clipEnd - +clipStart;
+   * ```
    */
   clipLength: number;
   /**
@@ -35,7 +47,7 @@ export type TMidiClipData = {
    */
   adjustTimeOftempee: number;
   /**
-   * List of known CC events in this clip.
+   * CC numbers known to this clip, sorted in ascending order.
    *
    * {@link TMidiClipData.ccMap __`ccMap`__}
    */
@@ -52,6 +64,15 @@ export type TMidiClipData = {
   /**
    * Array of extracted control change events. (flatten {@link TMidiClipData.ccMap __`ccMap`__}, sort by time)
    * @version 0.8.0
+   * @see {@link flattenCCEventMap}
    */
-  cc(): ControlChangeEvent[];
+  cc?(): ControlChangeEvent[];
 };
+/**
+ * @param {Record<string, ControlChangeEvent[]>} ccEventMap
+ * @param {number[]} knownCCEvents
+ */
+export declare const flattenCCEventMap: (ccEventMap: Record<string, ControlChangeEvent[]>, knownCCEvents: number[]) => ControlChangeEvent[];
+/**
+ * @import { ControlChangeEvent } from "./midi-event.ts";
+ */

package/dist/midi-clip.js

@@ -1 +1,47 @@
-export {};
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/midi-clip.ts
+ * @summary Common MIDI clip data type for Ableton Live and related tools.
+ */
+/**
+ * @param {Record<string, ControlChangeEvent[]>} ccEventMap
+ * @param {number[]} knownCCEvents
+ */
+const getFlattenSize = (ccEventMap, knownCCEvents) => {
+  var total = 0;
+  for (var idx in knownCCEvents) {
+    total += ccEventMap[knownCCEvents[idx]].length;
+  }
+  return total;
+};
+const warn = console.warn;
+/**
+ * @param {Record<string, ControlChangeEvent[]>} ccEventMap
+ * @param {number[]} knownCCEvents
+ */
+export const flattenCCEventMap = (ccEventMap, knownCCEvents) => {
+  var afterFlattenSize = getFlattenSize(ccEventMap, knownCCEvents);
+  /** @type {ControlChangeEvent[]} */
+  var ccBuffer = Array(afterFlattenSize);
+  var bufferIndex = 0;
+  for (let idx = 0, ccEventsLen = knownCCEvents.length; idx < ccEventsLen;) {
+    let ccEvents = ccEventMap[knownCCEvents[idx++]];
+    for (let eventIndex = 0, ccEventsLen = ccEvents.length; eventIndex < ccEventsLen;) {
+      ccBuffer[bufferIndex++] = ccEvents[eventIndex++];
+    }
+  }
+  if (bufferIndex !== afterFlattenSize) {
+    ccBuffer.length = bufferIndex;
+    warn(`⚠️  flattenCCEventMap: afterFlattenSize=${afterFlattenSize} lastSize=${bufferIndex}`);
+  }
+  return ccBuffer.sort((a, b) => a.time - b.time);
+};
+/**
+ * @import { ControlChangeEvent } from "./midi-event.ts";
+ */

package/dist/midi-event.d.ts

@@ -24,10 +24,12 @@ export type NoteEvent = {
   time: number;
   /**
    * NOTE: floating number
+   * + quarter-note beats
    */
   duration: number;
   /**
-   * NOTE: Must be an integer. Floating-point values are not valid.
+   * NOTE: Must be an integer. Floating-point values are invalid.
+   * + `0..127` integer
    */
   pitch: number;
   /**
@@ -45,6 +47,9 @@ export type ControlChangeEvent = {
   time: number;
   /**
    * MIDI controller number.
+   *
+   * NOTE: Must be an integer. Floating-point values are invalid.
+   * + `0..127` integer
    */
   controller: number;
   /**
@@ -55,6 +60,7 @@ export type ControlChangeEvent = {
   value: number;
   /**
    * Source type: "curve" for interpolated, "single" for discrete.
+   * + In **LME**, the "curve" is assigned to Bezier events, while it is omitted in regular discrete events.
    */
   source?: "curve" | "single";
 };

package/dist/midi-event.js

@@ -33,7 +33,6 @@ export const eventsIs = (events, type) => {
       return typeof e.pitch === "number" && typeof e.velocity === "number";
     case "cc":
       return typeof e.controller === "number" && typeof e.value === "number";
-    // case "tempo":
     default:
       return typeof e.bpm === "number";
   }

package/dist/project.d.ts

@@ -40,7 +40,7 @@ export type TClipSummary<T extends Record<string, any>> = {
    * "/Ableton/LiveSet/Tracks/MidiTrack/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip/Color/@Value"
    *
    * // how to actual color
-   * // "0" or "12" to "#ff94a6" / "#e553a0"
+   * // e.g - "0" to "#ff94a6", "12" to "#e553a0"
    * const hexColor = getColorFromIndex(+clip.color);
    * ```
    *
@@ -95,7 +95,7 @@ export type TTrackInfo<T extends Record<string, any>> = {
    *
    * ```
    * // e.g.
-   * "clip-" + crypto.randomUUID()
+   * "track-" + crypto.randomUUID()
    * ```
    */
   id: string;
@@ -117,8 +117,8 @@ export type TTrackInfo<T extends Record<string, any>> = {
    * "/Ableton/LiveSet/Tracks/MidiTrack/Color/@Value"
    *
    * // Convert the index to a CSS color:
-   * // "0" or "12" to "#ff94a6" / "#e553a0"
-   * const hexColor = getColorFromIndex(+clip.color);
+   * // e.g - "0" to "#ff94a6", "12" to "#e553a0"
+   * const hexColor = getColorFromIndex(+track.color);
    * ```
    * @see {@link getColorFromIndex}
    */
@@ -134,7 +134,7 @@ export type TTrackInfo<T extends Record<string, any>> = {
    */
   annotation: string;
   /**
-   * MIDI clips indexed by clip name.
+   * MIDI clips indexed by {@linkcode TClipSummary.id TClipSummary.id}
    */
   clips: Record<string, TClipSummary<T>>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffy-g/live-midi-types",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Common TypeScript types for Ableton Live MIDI clip and event data.",
   "type": "module",
   "main": "dist/index.js",