@jeffy-g/live-midi-types

@jeffy-g/live-midi-types — TypeScript type definitions for Ableton Live MIDI data projects.

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:

npm install @jeffy-g/live-midi-types

or

yarn add @jeffy-g/live-midi-types

Usage

Import the types you need directly into your TypeScript files.

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:

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

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

Project & UI types:

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 file for details.

Related Projects

• live-midi-export — CLI tool for extracting MIDI clips from Ableton Live sets.