npm package: @jeffy-g/live-midi-types
Description: Common TypeScript types for Ableton Live MIDI clip and event data.
Author: jeffy-g
Latest version: 0.6.4

# **@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.

```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]
};
```

Ableton Live color palette and utility functions:

```ts
import { abletonColorPalette, getColorFromIndex } from "@jeffy-g/live-midi-types";

const color: string = getColorFromIndex(5); // "#1aff2f"
```

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]
};
```

> ## Core Type Definitions (Reference)

### MIDI Event Types

- **`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`**: 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

- **`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

- **`abletonColorPalette`**: Array of 70+ Ableton Live color hex codes.
- **`getColorFromIndex(index: number): string`**: Returns color code for given index, fallback is gray ("#888").

> ## 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.