@jeffy-g/live-midi-types/README.md

Common TypeScript types for Ableton Live MIDI clip and event data.

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

> ## Type Origin and Gaps

These definitions were **reverse engineered** from Ableton Live 11 `.als` files.  
Ableton publishes no official specification, so some fields may be missing or misinterpreted.  
If you encounter inaccuracies, please open an issue or pull request.

> ## Directory Structure

```
src/
├─ midi-event.ts      # basic note, control change, and tempo events
├─ midi-clip.ts       # builds on midi-event to describe clips
├─ project.ts         # aggregates clips into a project
├─ ableton-colors.ts  # color utilities
└─ index.ts           # public exports
```

Dependencies flow upward: `midi-event` → `midi-clip` → `project`, while `ableton-colors` stands alone.

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