@jeffy-g/live-midi-types 0.3.0 → 0.5.1

package/README.md

@@ -7,7 +7,9 @@ Common TypeScript type definitions for working with Ableton Live MIDI data.
 
 > ## Description
 
-This package provides a centralized collection of TypeScript type definitions for working with data extracted from Ableton Live Set (`.als`) files. 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.
+This package provides a centralized collection of TypeScript type definitions for working with data extracted from Ableton Live Set (`.als`) files.
+
+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.
 
 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.
 
@@ -29,61 +31,110 @@ yarn add @jeffy-g/live-midi-types
 
 Import the types you need directly into your TypeScript files.
 
-```typescript
-import type { TMidiClipData, NoteEvent } from "@jeffy-g/live-midi-types";
-
-// Example function that processes MIDI clip data
-function processMidiClip(clip: TMidiClipData) {
-  console.log(`Processing clip starting at ${clip.clipStartInBeats} beats.`);
-  console.log(`It contains ${clip.notes.length} notes.`);
+```ts
+import type { TMidiClipData, NoteEvent, ControlChangeEvent, TempoEvent } from "@jeffy-g/live-midi-types";
+
+/** @type {NoteEvent} */
+const note = {
+  time: 0.0,
+  duration: 1.0,
+  pitch: 60,
+  velocity: 100
+};
+
+/** @type {ControlChangeEvent} */
+const cc = {
+  time: 0.5,
+  controller: 64,
+  value: 127,
+  source: "single"
+};
+
+/** @type {TempoEvent} */
+const tempo = {
+  time: 0.0,
+  bpm: 120
+};
+
+/** @type {TMidiClipData} */
+const clip = {
+  clipStartInBeats: 0,
+  clipLength: 16,
+  adjustTimeOftempee: 0,
+  knownCCEvents: [64, 1],
+  notes: [note],
+  cc: [cc]
+};
+```
 
-  for (const note of clip.notes) {
-    logNoteInfo(note);
-  }
-}
+Ableton Live color palette and utility functions:
 
-function logNoteInfo(note: NoteEvent) {
-  console.log(
-    `  - Note Pitch: ${note.pitch}, Velocity: ${note.velocity}, Duration: ${note.duration}`
-  );
-}
+```ts
+import { abletonColorPalette, getColorFromIndex } from "@jeffy-g/live-midi-types";
 
+const color: string = getColorFromIndex(5); // "#1aff2f"
 ```
 
-> ## Core Types
+Project & UI types:
+
+```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"
+};
+
+/** @type {TTrackInfo<{custom: string}>} */
+const trackInfo = {
+    name: "Track 1",
+    color: "#ff94a6",
+    clips: {
+        "Piano": clipSummary
+    }
+};
+
+/** @type {TParsedAbletonLiveSet<{custom: string}>} */
+const project = {
+    alsName: "MyProject",
+    ticksPerQuarter: 480,
+    tracks: [trackInfo]
+};
+```
 
-This library exports several key types to model the data within an Ableton Live project.
+> ## Core Type Definitions (Reference)
 
 ### MIDI Event Types
 
-- **`NoteEvent`**: Represents a single MIDI note with properties for `time`, `duration`, `pitch`, and `velocity`.
-- **`ControlChangeEvent`**: Represents a MIDI CC message with `time`, `controller` number, and `value`.
-- **`TempoEvent`**: Represents a tempo change event with `time` and `bpm`.
+- **`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.
 
 ### MIDI Clip Types
 
-- **`TMidiClipData`**: A comprehensive type representing all the essential data extracted from a single MIDI clip in Ableton Live. It includes:
-  - `clipStartInBeats`: The clip's start time in beats.
-  - `clipLength`: The clip's duration.
-  - `notes`: An array of `NoteEvent` objects.
-  - `cc`: An array of `ControlChangeEvent` objects.
-  - and other metadata.
+- **`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`.
 
 ### Project & UI Types
 
-- **`TMidiClipSummary<T>`**: A generic type for creating a summary of a MIDI clip, often used for UI purposes. It includes a unique `id`, `clipName`, and `trackName`.
-- **`TTrackInfo<T>`**: Represents the information for a single track, including its `name`, `color`, and a collection of its associated `TMidiClipSummary` objects.
-- **`TParsedLiveAlsProject<T>`**: Represents the entire parsed project, containing `ticksPerQuarter` and an array of `TTrackInfo` objects.
+- **`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.
 
 ### Ableton Color Utilities
 
-This library also provides a predefined Ableton Live color palette and utility functions.
-
-```ts
-import { abletonColorPalette, getColorFromIndex } from "@jeffy-g/live-midi-types";
-
-console.log(getColorFromIndex(5)); // → "#1aff2f"
-```
+- **`abletonColorPalette`**: Array of 70+ Ableton Live color hex codes.
+- **`getColorFromIndex(index: number): string`**: Returns color code for given index, fallback is gray ("#888").
 
 > ## License
 

package/dist/midi-clip.d.ts

@@ -34,6 +34,10 @@ export type TMidiClipData = {
    * Time adjustment for tempo mapping (in beats).
    */
   adjustTimeOftempee: number;
+  /**
+   * List of known CC events in this clip.
+   */
+  knownCCEvents: number[];
   /**
    * Array of extracted note events.
    */

package/dist/project.d.ts

@@ -8,6 +8,7 @@
 /**
  * @file src/project.ts
  */
+import type { TempoEvent } from "./midi-event.ts";
 export type TClipSummary<T extends Record<string, any>> = {
   /**
    * UI などで使用する時のために付与される ID
@@ -52,4 +53,8 @@ export type TParsedAbletonLiveSet<T extends Record<string, any>> = {
    * NOTE: currently, this is a Midi tracks only.
    */
   tracks: TTrackInfo<T>[];
+  /**
+   * Tempo automation events.
+   */
+  tempoAutomation?: TempoEvent[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffy-g/live-midi-types",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Common TypeScript types for Ableton Live MIDI clip and event data.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,11 +27,5 @@
     "typescript",
     "types",
     "music"
-  ],
-  "scripts": {
-    "prebuild": "rimraf -g ./dist/*",
-    "format": "prettier --tab-width 2 -w \"./dist/**/*\"",
-    "build": "tsc",
-    "watch": "tsc -w"
-  }
+  ]
 }