@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.
 */
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.
   *
   * 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];