@jeffy-g/live-midi-types 0.7.3 → 0.8.0

package/dist/index.d.ts

@@ -2,4 +2,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.7.3";
+export declare const version = "v0.8.0";

package/dist/index.js

@@ -2,4 +2,4 @@ export * from "./midi-event.js";
 export * from "./midi-clip.js";
 export * from "./project.js";
 export * from "./ableton-colors.js";
-export const version = "v0.7.3";
+export const version = "v0.8.0";

package/dist/midi-clip.d.ts

@@ -42,8 +42,14 @@ export type TMidiClipData = {
    * Array of extracted note events.
    */
   notes: NoteEvent[];
+  /**
+   * Control change event map.
+   * @version 0.8.0
+   */
+  ccMap: Record<string, ControlChangeEvent[]>;
   /**
    * Array of extracted control change events.
+   * @version 0.8.0
    */
-  cc: ControlChangeEvent[];
+  cc(): ControlChangeEvent[];
 };

package/dist/midi-event.d.ts

@@ -50,7 +50,7 @@ export type ControlChangeEvent = {
   /**
    * `0` to `127`
    *
-   * Value of the controller (0-127, may be float).
+   * Value of the controller (0-127, floating number).
    */
   value: number;
   /**

package/dist/project.d.ts

@@ -9,29 +9,31 @@
  * @file src/project.ts
  */
 import type { TempoEvent } from "./midi-event.ts";
+/**
+ * Summary information for an Ableton Live MIDI clip.
+ */
 export type TClipSummary<T extends Record<string, any>> = {
   /**
-   * Original MidiClip Id
-   * + This is always a simple number.
+   * Original `MidiClip` ID from the ALS document.
    *
-   * ```js
-   * // e.g
+   * + Stored as a numeric string.
+   *
+   * ```
    * "/Ableton/LiveSet/Tracks/MidiTrack[4]/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip[3]/@Id"
    * ```
    * @date 2026/07/02
    */
   originId: string;
   /**
-   * An ID to be assigned for use in UI and other applications.
+   * Application-specific ID assigned for use by the UI and other consumers.
    *
    * ```
-   * // e.g.
-   * "clip-" + crypto.randomUUID()
+   * `clip-${crypto.randomUUID()}`
    * ```
    */
   id: string;
   /**
-   * Live color palette index
+   * Index into the Ableton Live color palette.
    * + This value is always the index of the color palette.
    * ```
    * // e.g. xpath
@@ -46,35 +48,42 @@ export type TClipSummary<T extends Record<string, any>> = {
    */
   color: string;
   /**
-   * Disabled property for the clip.
+   * Whether the clip is disabled.
    */
   disabled: boolean;
   /**
-   * Original MidiClip name
+   * Original name of the `MidiClip`.
    *
-   * ```js
+   * ```
    * // e.g
    * "/Ableton/LiveSet/Tracks/MidiTrack/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip/Name/@Value"
    * ```
    */
   clipName: string;
   /**
-   * Parent track name
+   * Name of the parent track.
    */
   trackName: string;
   /**
-   * Annotation of this MidiClip.
-   * + It seems that any value can be stored if it's a text value.
-   * ```js
+   * Annotation attached to this `MidiClip` in Ableton Live.
+   *
+   * + Any text value appears to be accepted.
+   *
+   * ```
    * // e.g
    * "/Ableton/LiveSet/Tracks/MidiTrack/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip/Annotation/@Value"
    * ```
    */
-  annotations?: string;
+  annotation: string;
 } & T;
+/**
+ * Summary information for an Ableton Live track.
+ */
 export type TTrackInfo<T extends Record<string, any>> = {
   /**
-   * ```js
+   * Original track ID from the ALS document.
+   *
+   * ```
    * // e.g
    * "/Ableton/LiveSet/Tracks/MidiTrack[4]/@Id"
    * ```
@@ -82,7 +91,7 @@ export type TTrackInfo<T extends Record<string, any>> = {
    */
   originId: string;
   /**
-   * An ID to be assigned for use in UI and other applications.
+   * Application-specific ID assigned for use by the UI and other consumers.
    *
    * ```
    * // e.g.
@@ -91,64 +100,70 @@ export type TTrackInfo<T extends Record<string, any>> = {
    */
   id: string;
   /**
-   * Original Track name
+   * Original name of the track.
    *
-   * ```js
+   * ```
    * // e.g MidiTrack
    * "/Ableton/LiveSet/Tracks/MidiTrack/Name/EffectiveName/@Value"
    * ```
    */
   name: string;
   /**
-   * Live color palette index
+   * Index into the Ableton Live color palette.
    * + This value is always the index of the color palette.
+   *
    * ```
    * // e.g. xpath (MidiTrack)
    * "/Ableton/LiveSet/Tracks/MidiTrack/Color/@Value"
    *
-   * // how to actual color
+   * // Convert the index to a CSS color:
    * // "0" or "12" to "#ff94a6" / "#e553a0"
    * const hexColor = getColorFromIndex(+clip.color);
    * ```
-   *
    * @see {@link getColorFromIndex}
    */
   color: string;
   /**
-   * Annotation of this MidiClip.
-   * + It seems that any value can be stored if it's a text value.
-   * ```js
+   * Annotation attached to this track in Ableton Live. (MidiTrack etc).
+   *
+   * + Any text value appears to be accepted.
+   * ```
    * // e.g (MidiTrack)
    * "/Ableton/LiveSet/Tracks/MidiTrack/Name/Annotation/@Value"
    * ```
    */
-  annotations?: string;
+  annotation: string;
   /**
-   * ```
-   * Record<"clipName", TMidiClipSummary>
-   * ```
+   * MIDI clips indexed by clip name.
    */
   clips: Record<string, TClipSummary<T>>;
 };
+/**
+ * Parsed data required by the Ableton Live project UI.
+ */
 export type TParsedAbletonLiveSet<T extends Record<string, any>> = {
   /**
-   * Ableton Live project name
-   * Usually the als file name without the extension.
+   * Ableton Live project name.
+   *
+   * + Usually the `.als` filename without its extension.
    */
   alsName: string;
   /**
-   * ppq (ticks per quarter note)
-   * + This value is not available in `ALS`, but it is set on the application side.
+   * Pulses per quarter note (PPQ).
+   *
+   * + This value is not stored in the ALS document; it is supplied by the application.
    */
   ticksPerQuarter: number;
   /**
    * Tracks in the project.
-   * NOTE: currently, this is a Midi tracks only.
+   *
+   * + Currently contains only MIDI tracks.
    */
   tracks: TTrackInfo<T>[];
   /**
-   * Tempo automation events.
-   * + Retrieving tempo event data is a bit complicated.
+   * Tempo automation events extracted from the master track.
+   *
+   * + Retrieving tempo event data requires a version-dependent XPath.
    * ```
    * // Specific XPath examples (live 12.x)
    * "/Ableton/LiveSet/MasterTrack/AutomationEnvelopes/Envelopes/AutomationEnvelope[2]/Automation/Events"

package/package.json

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