@jeffy-g/live-midi-types 0.7.2 → 0.7.4

package/dist/ableton-colors.d.ts

@@ -14,8 +14,8 @@
  */
 export declare const abletonColorPalette: string[];
 /**
- * Get color code from Ableton color index.
- * @param {number} colorIndex Index of Ableton color palette.
+ * Get color code from Ableton Live color index.
+ * @param {number} colorIndex Index of Ableton Live color palette.
  * @returns {string} Hex color code.
  */
 export declare function getColorFromIndex(colorIndex: number): string;

package/dist/ableton-colors.js

@@ -23,8 +23,8 @@ export const abletonColorPalette = "#ff94a6:#ffa529:#cc9927:#f7f47c:#bffb00:#1af
 #af3333:#a95131:#724f41:#dbc300:#85961f:#539f31:#0a9c8e:\
 #236384:#1a2f96:#2f52a2:#624bad:#a34bad:#cc2e6e:#3c3c3c".split(":");
 /**
- * Get color code from Ableton color index.
- * @param {number} colorIndex Index of Ableton color palette.
+ * Get color code from Ableton Live color index.
+ * @param {number} colorIndex Index of Ableton Live color palette.
  * @returns {string} Hex color code.
  */
 export function getColorFromIndex(colorIndex) {

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.2";
+export declare const version = "v0.7.4";

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.2";
+export const version = "v0.7.4";

package/dist/project.d.ts

@@ -9,69 +9,165 @@
  * @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>> = {
   /**
-   * ```js
-   * // e.g
+   * Original `MidiClip` ID from the ALS document.
+   *
+   * + Stored as a numeric string.
+   *
+   * ```
    * "/Ableton/LiveSet/Tracks/MidiTrack[4]/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip[3]/@Id"
    * ```
    * @date 2026/07/02
    */
   originId: string;
   /**
-   * ID assigned for use in UI etc.
+   * Application-specific ID assigned for use by the UI and other consumers.
    *
    * ```
-   * "clip-" + crypto.randomUUID()
+   * `clip-${crypto.randomUUID()}`
    * ```
    */
   id: string;
+  /**
+   * Index into the Ableton Live color palette.
+   * + This value is always the index of the color palette.
+   * ```
+   * // e.g. xpath
+   * "/Ableton/LiveSet/Tracks/MidiTrack/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip/Color/@Value"
+   *
+   * // how to actual color
+   * // "0" or "12" to "#ff94a6" / "#e553a0"
+   * const hexColor = getColorFromIndex(+clip.color);
+   * ```
+   *
+   * @see {@link getColorFromIndex}
+   */
   color: string;
   /**
-   * Disabled property for the clip.
+   * Whether the clip is disabled.
    */
   disabled: boolean;
+  /**
+   * Original name of the `MidiClip`.
+   *
+   * ```
+   * // e.g
+   * "/Ableton/LiveSet/Tracks/MidiTrack/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip/Name/@Value"
+   * ```
+   */
   clipName: string;
+  /**
+   * Name of the parent track.
+   */
   trackName: string;
-  annotations?: string;
+  /**
+   * 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"
+   * ```
+   */
+  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"
    * ```
    * @date 2026/07/02
    */
   originId: string;
+  /**
+   * Application-specific ID assigned for use by the UI and other consumers.
+   *
+   * ```
+   * // e.g.
+   * "clip-" + crypto.randomUUID()
+   * ```
+   */
   id: string;
+  /**
+   * Original name of the track.
+   *
+   * ```
+   * // e.g MidiTrack
+   * "/Ableton/LiveSet/Tracks/MidiTrack/Name/EffectiveName/@Value"
+   * ```
+   */
   name: string;
+  /**
+   * 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"
+   *
+   * // Convert the index to a CSS color:
+   * // "0" or "12" to "#ff94a6" / "#e553a0"
+   * const hexColor = getColorFromIndex(+clip.color);
+   * ```
+   * @see {@link getColorFromIndex}
+   */
   color: string;
-  annotations?: string;
   /**
+   * Annotation attached to this track in Ableton Live. (MidiTrack etc).
+   *
+   * + Any text value appears to be accepted.
    * ```
-   * Record<"clipName", TMidiClipSummary>
+   * // e.g (MidiTrack)
+   * "/Ableton/LiveSet/Tracks/MidiTrack/Name/Annotation/@Value"
    * ```
    */
+  annotation: string;
+  /**
+   * 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)
+   * 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.
+   * 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"
+   * ```
    */
   tempoAutomation: TempoEvent[];
 };

package/package.json

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