@jeffy-g/live-midi-types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jeffy-g
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# **@jeffy-g/live-midi-types** — TypeScript type definitions for Ableton Live MIDI data projects.
+
+[![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.
+
+> ## 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.
+
+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.
+
+> ## Installation
+
+You can install the package using npm or yarn:
+
+```sh
+npm install @jeffy-g/live-midi-types
+```
+
+or
+
+```sh
+yarn add @jeffy-g/live-midi-types
+```
+
+> ## Usage
+
+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.`);
+
+  for (const note of clip.notes) {
+    logNoteInfo(note);
+  }
+}
+
+function logNoteInfo(note: NoteEvent) {
+  console.log(
+    `  - Note Pitch: ${note.pitch}, Velocity: ${note.velocity}, Duration: ${note.duration}`
+  );
+}
+
+```
+
+> ## Core Types
+
+This library exports several key types to model the data within an Ableton Live project.
+
+### 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`.
+
+### 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.
+
+### 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.
+
+### 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"
+```
+
+> ## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+> ## Related Projects
+
+- [live-midi-export](https://github.com/jeffy-g/live-midi-export) — CLI tool for extracting MIDI clips from Ableton Live sets.

package/dist/ableton-colors.d.ts

@@ -0,0 +1,21 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/ableton-colors.ts
+ */
+/**
+ * Ableton Live color palette.
+ * @date 2025/6/27 4:51:48
+ */
+export declare const abletonColorPalette: string[];
+/**
+ * Get color code from Ableton color index.
+ * @param {number} colorIndex Index of Ableton color palette.
+ * @returns {string} Hex color code.
+ */
+export declare function getColorFromIndex(colorIndex: number): string;

package/dist/ableton-colors.js

@@ -0,0 +1,34 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/ableton-colors.ts
+ */
+/**
+ * Ableton Live color palette.
+ * @date 2025/6/27 4:51:48
+ */
+export const abletonColorPalette = [
+    "#ff94a6", "#ffa529", "#cc9927", "#f7f47c", "#bffb00", "#1aff2f", "#25ffa8",
+    "#5cffe8", "#8bc5ff", "#5480e4", "#92a7ff", "#d86ce4", "#e553a0", "#ffffff",
+    "#ff3636", "#f66c03", "#99724b", "#fff034", "#87ff67", "#3dc300", "#00bfaf",
+    "#19e9ff", "#10a4ee", "#007dc0", "#886ce4", "#b677c6", "#ff39d4", "#d0d0d0",
+    "#e2675a", "#ffa374", "#d3ad71", "#edffae", "#d2e498", "#bad074", "#9bc48d",
+    "#d4fde1", "#cdf1f8", "#b9c1e3", "#cdbbe4", "#ae98e5", "#e5dce1", "#a9a9a9",
+    "#c6928b", "#b78256", "#99836a", "#bfba69", "#a6be00", "#7db04d", "#88c2ba",
+    "#9bb3c4", "#85a5c2", "#8393cc", "#a595b5", "#bf9fbe", "#bc7196", "#7b7b7b",
+    "#af3333", "#a95131", "#724f41", "#dbc300", "#85961f", "#539f31", "#0a9c8e",
+    "#236384", "#1a2f96", "#2f52a2", "#624bad", "#a34bad", "#cc2e6e", "#3c3c3c"
+];
+/**
+ * Get color code from Ableton color index.
+ * @param {number} colorIndex Index of Ableton color palette.
+ * @returns {string} Hex color code.
+ */
+export function getColorFromIndex(colorIndex) {
+    return abletonColorPalette[colorIndex] ?? "#888"; // fallback gray
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./midi-event";
+export * from "./midi-clip";
+export * from "./project";
+export * from "./ableton-colors";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./midi-event";
+export * from "./midi-clip";
+export * from "./project";
+export * from "./ableton-colors";

package/dist/midi-clip.d.ts

@@ -0,0 +1,53 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  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.
+ */
+import type { NoteEvent, ControlChangeEvent } from "./midi-event";
+/**
+ * MIDI clip data extracted from Ableton Live's MidiClip object.
+ *
+ * This type represents all essential information for a single MIDI clip,
+ * including note events, control change events, and timing information.
+ *
+ * ```ts
+ * import type { TMidiClipData } from "@jeffy-g/live-midi-types";
+ * const data: TMidiClipData = ...;
+ * ```
+ */
+export type TMidiClipData = {
+    /**
+     * Start position of the clip on the Live MidiTrack (in beats).
+     */
+    clipStartInBeats: number;
+    /**
+     * Length of the clip (in beats).
+     */
+    clipLength: number;
+    /**
+     * Time adjustment for tempo mapping (in beats).
+     */
+    adjustTimeOftempee: number;
+    /**
+     * color for visualization (Color table index)
+     */
+    color: string;
+    /**
+     * Disabled property for the clip.
+     */
+    disabled: boolean;
+    /**
+     * Array of extracted note events.
+     */
+    notes: NoteEvent[];
+    /**
+     * Array of extracted control change events.
+     */
+    cc: ControlChangeEvent[];
+};

package/dist/midi-clip.js

@@ -0,0 +1 @@
+export {};

package/dist/midi-event.d.ts

@@ -0,0 +1,66 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/midi-event.ts
+ * @summary Common MIDI event types for Ableton Live and related tools.
+ */
+export type NoteEvent = {
+    /**
+     * NOTE: floating number
+     */
+    time: number;
+    /**
+     * NOTE: floating number
+     */
+    duration: number;
+    pitch: number;
+    /**
+     * `0` to `127`
+     * NOTE: floating number
+     */
+    velocity: number;
+};
+export type ControlChangeEvent = {
+    /**
+     * Time relative to the start of the clip.
+     *
+     * **This is a floating point number representing the time in quarter notes. (Ableton Live)**
+     */
+    time: number;
+    /**
+     * MIDI controller number.
+     */
+    controller: number;
+    /**
+     * `0` to `127`
+     *
+     * Value of the controller (0-127, may be float).
+     */
+    value: number;
+    /**
+     * Source type: "curve" for interpolated, "single" for discrete.
+     */
+    source?: "curve" | "single";
+};
+/**
+ * Tempo event object.
+ */
+export type TempoEvent = {
+    /**
+     * Time in quarter notes.
+     *
+     * 拍ベースのタイムスタンプ（例：4.5 = 4拍と8分音符）
+     */
+    time: number;
+    /**
+     * Tempo in BPM.
+     *
+     * この地点でのテンポ（BPM）
+     */
+    bpm: number;
+};

package/dist/midi-event.js

@@ -0,0 +1,12 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/midi-event.ts
+ * @summary Common MIDI event types for Ableton Live and related tools.
+ */
+export {};

package/dist/project.d.ts

@@ -0,0 +1,36 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file src/project.ts
+ */
+export type TMidiClipSummary<T extends Record<string, any>> = {
+    /**
+     * UI などで使用する時のために付与される ID
+     *
+     * ```
+     * "clip-" + createUUID().toUpperCase()
+     * ```
+     */
+    id: string;
+    clipName: string;
+    trackName: string;
+} & T;
+export type TTrackInfo<T extends Record<string, any>> = {
+    name: string;
+    color: string;
+    /**
+     * ```
+     * Record<"clipName", TMidiClipSummary>
+     * ```
+     */
+    clips: Record<string, TMidiClipSummary<T>>;
+};
+export type TParsedLiveAlsProject<T extends Record<string, any>> = {
+    ticksPerQuarter: number;
+    tracks: TTrackInfo<T>[];
+};

package/dist/project.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jeffy-g/live-midi-types",
+  "version": "0.1.0",
+  "description": "Common TypeScript types for Ableton Live MIDI clip and event data.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "jeffy-g <hirotom1107@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeffy-g/live-midi-types.git"
+  },
+  "keywords": [
+    "ableton",
+    "midi",
+    "typescript",
+    "types",
+    "music"
+  ],
+  "scripts": {
+    "prebuild": "rimraf -g ./dist/*",
+    "build": "tsc",
+    "watch": "tsc -w"
+  }
+}