audio-ui/types/automation.ts

/**
 * Automation system type definitions
 * Based on Ableton Live's automation model
 */

/**
 * Automation curve types
 * - linear: Straight line between points
 * - bezier: Curved line with control handles
 * - step: Horizontal lines with vertical transitions (for discrete values)
 */
export type AutomationCurveType = 'linear' | 'bezier' | 'step';

/**
 * Automation recording/playback modes
 * - read: Only playback automation
 * - write: Record automation (replaces existing)
 * - touch: Record while touching control, then return to read mode
 * - latch: Record from first touch until stop, then return to read mode
 */
export type AutomationMode = 'read' | 'write' | 'touch' | 'latch';

/**
 * Single automation breakpoint
 */
export interface AutomationPoint {
  id: string;
  time: number; // Position in seconds from track start
  value: number; // Parameter value (normalized 0-1)
  curve: AutomationCurveType;
  // Bezier control handles (only used when curve is 'bezier')
  handleIn?: { x: number; y: number }; // Relative to point position
  handleOut?: { x: number; y: number }; // Relative to point position
}

/**
 * Parameter identifier for automation
 * Examples:
 * - 'volume' - Track volume
 * - 'pan' - Track pan
 * - 'mute' - Track mute (step curve)
 * - 'effect.compressor-1.threshold' - Effect parameter
 * - 'effect.delay-2.time' - Effect parameter
 */
export type AutomationParameterId = string;

/**
 * Single automation lane for a specific parameter
 */
export interface AutomationLane {
  id: string;
  trackId: string;
  parameterId: AutomationParameterId;
  parameterName: string; // Display name (e.g., "Volume", "Compressor Threshold")
  visible: boolean; // Show/hide lane
  height: number; // Lane height in pixels (user-adjustable, 60-120px)
  points: AutomationPoint[];
  mode: AutomationMode;
  color?: string; // Optional color override (defaults to parameter type color)
  // Value range for display (actual values are normalized 0-1)
  valueRange: {
    min: number; // Display minimum (e.g., 0 for volume)
    max: number; // Display maximum (e.g., 1 for volume)
    unit?: string; // Display unit (e.g., 'dB', '%', 'ms', 'Hz')
    formatter?: (value: number) => string; // Custom value formatter
  };
}

/**
 * All automation lanes for a single track
 */
export interface TrackAutomation {
  trackId: string;
  lanes: AutomationLane[];
  showAutomation: boolean; // Master show/hide toggle for all lanes
}

/**
 * Complete automation data for entire project
 */
export interface ProjectAutomation {
  tracks: Record<string, TrackAutomation>;
}

/**
 * Automation parameter value at a specific time
 * Used for real-time playback
 */
export interface AutomationValue {
  parameterId: AutomationParameterId;
  value: number;
  time: number;
}

/**
 * Helper type for creating new automation points
 */
export type CreateAutomationPointInput = Omit<AutomationPoint, 'id'>;

/**
 * Helper type for creating new automation lanes
 */
export type CreateAutomationLaneInput = Omit<AutomationLane, 'id' | 'points'> & {
  points?: AutomationPoint[];
};