@jeffy-g/live-midi-types/dist/midi-event.d.ts

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

/*!
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//  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.
 */
/**
 * ```
 * // Path to `MidiClip` element
 * `/Ableton/LiveSet/Tracks/MidiTrack[]/DeviceChain/MainSequencer/ClipTimeable/ArrangerAutomation/Events/MidiClip[]`
 * // this type is `MidiNoteEvent`
 * `<MidiClip>/Notes/KeyTracks/KeyTrack[]/Notes/MidiNoteEvent[]`
 * ```
 */
export type NoteEvent = {
  /**
   * NOTE: floating number
   */
  time: number;
  /**
   * NOTE: floating number
   */
  duration: number;
  /**
   * NOTE: Must be an integer. Floating-point values are not valid.
   */
  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, floating number).
   */
  value: number;
  /**
   * Source type: "curve" for interpolated, "single" for discrete.
   */
  source?: "curve" | "single";
};
/**
 * Tempo event object.
 */
export type TempoEvent = {
  /**
   * Time in quarter notes.
   *
   * Beat-based timestamps (e.g. 4.5 = 4 beats and an eighth note)
   */
  time: number;
  /**
   * Tempo in BPM.
   */
  bpm: number;
};
/**
 * Type alias for MIDI event types.
 *
 * This type maps event names to their corresponding event types.
 */
export type TEventMap = {
  note: NoteEvent[];
  cc: ControlChangeEvent[];
  tempo: TempoEvent[];
};
/**
 * Type guard to check if the events array contains a specific type of MIDI event.
 * @template {keyof TEventMap} K
 * @param {unknown[]} events Array of events to check.
 * @param {K} type Type of event to check against.
 * @returns {events is TEventMap[K]} True if the events match the specified type.
 */
export declare const eventsIs: <K extends keyof TEventMap>(events: unknown[], type: K) => events is TEventMap[K];