@drop-ai/core 0.2.0 → 0.3.1

package/dist/audio/engine/PunchRecordManager.d.ts

@@ -0,0 +1,111 @@
+import { Signal } from '../../lib/Signal';
+import { FrameCount, TrackId } from '../../domain/types';
+/**
+ * PunchRecordManager handles automatic punch-in/punch-out recording.
+ *
+ * When punch is enabled:
+ * - Recording starts automatically when playhead enters the punch range
+ * - Recording stops automatically when playhead exits the punch range
+ * - Declick fades are applied at punch boundaries
+ * - Pre-roll audio before punch-in is discarded
+ *
+ * Modes:
+ * - Simple punch: single pass recording within the range
+ * - Loop punch: repeated punch recording when loop + punch are both enabled
+ */
+export interface PunchState {
+    enabled: boolean;
+    punchIn: FrameCount;
+    punchOut: FrameCount;
+    isPunchedIn: boolean;
+    armedTrackIds: TrackId[];
+}
+export declare class PunchRecordManager {
+    private _enabled;
+    private _punchIn;
+    private _punchOut;
+    private _isPunchedIn;
+    private _armedTrackIds;
+    private _declickLength;
+    /** Emitted when the playhead enters the punch range and recording begins. */
+    readonly punchInTriggered: Signal<string[]>;
+    /** Emitted when the playhead exits the punch range and recording stops. */
+    readonly punchOutTriggered: Signal<string[]>;
+    /** Emitted whenever the punch state changes. */
+    readonly stateChanged: Signal<PunchState>;
+    /**
+     * @param sampleRate - Audio sample rate, used to compute declick fade length.
+     *                     Defaults to 44100 if omitted.
+     */
+    constructor(sampleRate?: number);
+    /**
+     * Configure the punch range boundaries.
+     * @param punchIn - Frame at which recording should begin
+     * @param punchOut - Frame at which recording should end
+     */
+    setPunchRange(punchIn: FrameCount, punchOut: FrameCount): void;
+    /**
+     * Enable or disable punch recording.
+     * Disabling while punched-in will trigger an immediate punch-out.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Arm a track for punch recording.
+     * Only armed tracks will be affected by punch-in/punch-out events.
+     */
+    armTrack(trackId: TrackId): void;
+    /**
+     * Disarm a track from punch recording.
+     */
+    disarmTrack(trackId: TrackId): void;
+    /**
+     * Called each audio process cycle with the current transport position.
+     * Checks whether the playhead has crossed a punch boundary and triggers
+     * punch-in or punch-out accordingly.
+     *
+     * @param currentFrame - The current transport playhead position in frames
+     * @returns true if the recording state changed during this call
+     */
+    processPosition(currentFrame: FrameCount): boolean;
+    /**
+     * Get a snapshot of the current punch state.
+     */
+    getState(): PunchState;
+    /**
+     * Whether we're currently in the punched-in state (recording is active
+     * within the punch range).
+     */
+    get isPunchedIn(): boolean;
+    /**
+     * Compute declick fade gain at a given position relative to punch boundaries.
+     *
+     * Returns a gain value between 0.0 and 1.0:
+     * - Ramps from 0->1 over _declickLength frames starting at punchIn (fade-in)
+     * - Ramps from 1->0 over _declickLength frames ending at punchOut (fade-out)
+     * - Returns 1.0 for positions in the middle of the punch range
+     * - Returns 0.0 for positions outside the punch range
+     *
+     * Uses a raised-cosine (Hann) curve for perceptually smooth transitions,
+     * consistent with the Declicker class.
+     */
+    getDeclickGain(frame: FrameCount): number;
+    /**
+     * Reset state (called on transport stop).
+     * Clears the punched-in state without emitting punch-out signals,
+     * since transport stop implies recording has already ceased.
+     */
+    reset(): void;
+    /**
+     * Execute a punch-in: transition to recording state and notify listeners.
+     */
+    private _doPunchIn;
+    /**
+     * Execute a punch-out: transition out of recording state and notify listeners.
+     */
+    private _doPunchOut;
+    /**
+     * Emit a stateChanged signal with the current punch state snapshot.
+     */
+    private _emitStateChanged;
+}
+//# sourceMappingURL=PunchRecordManager.d.ts.map

package/dist/audio/engine/PunchRecordManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PunchRecordManager.d.ts","sourceRoot":"","sources":["../../../src/audio/engine/PunchRecordManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,EAAE,CAAC;CAC5B;AAED,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,cAAc,CAA2B;IAGjD,OAAO,CAAC,cAAc,CAAc;IAEpC,6EAA6E;IAC7E,SAAgB,gBAAgB,mBAA2B;IAE3D,2EAA2E;IAC3E,SAAgB,iBAAiB,mBAA2B;IAE5D,gDAAgD;IAChD,SAAgB,YAAY,qBAA4B;IAExD;;;OAGG;gBACS,UAAU,CAAC,EAAE,MAAM;IAQ/B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,IAAI;IAW9D;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAclC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAKhC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOnC;;;;;;;OAOG;IACH,eAAe,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO;IA6BlD;;OAEG;IACH,QAAQ,IAAI,UAAU;IAUtB;;;OAGG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAgCzC;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAG5B"}

package/dist/audio/engine/PunchRecordManager.js

@@ -0,0 +1,191 @@
+import { Signal } from '../../lib/Signal';
+export class PunchRecordManager {
+    /**
+     * @param sampleRate - Audio sample rate, used to compute declick fade length.
+     *                     Defaults to 44100 if omitted.
+     */
+    constructor(sampleRate) {
+        this._enabled = false;
+        this._punchIn = 0;
+        this._punchOut = 0;
+        this._isPunchedIn = false;
+        this._armedTrackIds = new Set();
+        // Declick fade length in frames (~1.5ms at 44100)
+        this._declickLength = 64;
+        /** Emitted when the playhead enters the punch range and recording begins. */
+        this.punchInTriggered = new Signal();
+        /** Emitted when the playhead exits the punch range and recording stops. */
+        this.punchOutTriggered = new Signal();
+        /** Emitted whenever the punch state changes. */
+        this.stateChanged = new Signal();
+        const rate = sampleRate !== null && sampleRate !== void 0 ? sampleRate : 44100;
+        // ~1.5ms declick fade, minimum 16 samples
+        this._declickLength = Math.max(16, Math.round((1.5 / 1000) * rate));
+    }
+    // ─── Configuration ──────────────────────────────────────────────────
+    /**
+     * Configure the punch range boundaries.
+     * @param punchIn - Frame at which recording should begin
+     * @param punchOut - Frame at which recording should end
+     */
+    setPunchRange(punchIn, punchOut) {
+        if (punchOut <= punchIn) {
+            throw new Error(`Invalid punch range: punchOut (${punchOut}) must be greater than punchIn (${punchIn})`);
+        }
+        this._punchIn = punchIn;
+        this._punchOut = punchOut;
+        this._emitStateChanged();
+    }
+    /**
+     * Enable or disable punch recording.
+     * Disabling while punched-in will trigger an immediate punch-out.
+     */
+    setEnabled(enabled) {
+        const wasEnabled = this._enabled;
+        this._enabled = enabled;
+        // If disabling while currently punched in, trigger punch-out
+        if (wasEnabled && !enabled && this._isPunchedIn) {
+            this._doPunchOut();
+        }
+        this._emitStateChanged();
+    }
+    // ─── Track Arming ───────────────────────────────────────────────────
+    /**
+     * Arm a track for punch recording.
+     * Only armed tracks will be affected by punch-in/punch-out events.
+     */
+    armTrack(trackId) {
+        this._armedTrackIds.add(trackId);
+        this._emitStateChanged();
+    }
+    /**
+     * Disarm a track from punch recording.
+     */
+    disarmTrack(trackId) {
+        this._armedTrackIds.delete(trackId);
+        this._emitStateChanged();
+    }
+    // ─── Processing ─────────────────────────────────────────────────────
+    /**
+     * Called each audio process cycle with the current transport position.
+     * Checks whether the playhead has crossed a punch boundary and triggers
+     * punch-in or punch-out accordingly.
+     *
+     * @param currentFrame - The current transport playhead position in frames
+     * @returns true if the recording state changed during this call
+     */
+    processPosition(currentFrame) {
+        if (!this._enabled) {
+            return false;
+        }
+        if (this._armedTrackIds.size === 0) {
+            return false;
+        }
+        const wasInRange = this._isPunchedIn;
+        const isInRange = currentFrame >= this._punchIn && currentFrame < this._punchOut;
+        if (!wasInRange && isInRange) {
+            // Playhead just entered the punch range -> punch in
+            this._doPunchIn();
+            return true;
+        }
+        if (wasInRange && !isInRange) {
+            // Playhead just exited the punch range -> punch out
+            this._doPunchOut();
+            return true;
+        }
+        return false;
+    }
+    // ─── State Queries ──────────────────────────────────────────────────
+    /**
+     * Get a snapshot of the current punch state.
+     */
+    getState() {
+        return {
+            enabled: this._enabled,
+            punchIn: this._punchIn,
+            punchOut: this._punchOut,
+            isPunchedIn: this._isPunchedIn,
+            armedTrackIds: Array.from(this._armedTrackIds),
+        };
+    }
+    /**
+     * Whether we're currently in the punched-in state (recording is active
+     * within the punch range).
+     */
+    get isPunchedIn() {
+        return this._isPunchedIn;
+    }
+    /**
+     * Compute declick fade gain at a given position relative to punch boundaries.
+     *
+     * Returns a gain value between 0.0 and 1.0:
+     * - Ramps from 0->1 over _declickLength frames starting at punchIn (fade-in)
+     * - Ramps from 1->0 over _declickLength frames ending at punchOut (fade-out)
+     * - Returns 1.0 for positions in the middle of the punch range
+     * - Returns 0.0 for positions outside the punch range
+     *
+     * Uses a raised-cosine (Hann) curve for perceptually smooth transitions,
+     * consistent with the Declicker class.
+     */
+    getDeclickGain(frame) {
+        if (!this._enabled) {
+            return 1.0;
+        }
+        // Outside punch range entirely
+        if (frame < this._punchIn || frame >= this._punchOut) {
+            return 0.0;
+        }
+        const fadeLen = this._declickLength;
+        // Fade-in region: punchIn to punchIn + fadeLen
+        const distFromStart = frame - this._punchIn;
+        if (distFromStart < fadeLen) {
+            // Raised cosine (Hann) fade-in: 0.5 * (1 - cos(pi * t))
+            const t = distFromStart / (fadeLen - 1);
+            return 0.5 * (1 - Math.cos(Math.PI * t));
+        }
+        // Fade-out region: punchOut - fadeLen to punchOut
+        const distFromEnd = this._punchOut - frame;
+        if (distFromEnd <= fadeLen) {
+            // Raised cosine (Hann) fade-out: 0.5 * (1 + cos(pi * t))
+            const t = (fadeLen - distFromEnd) / (fadeLen - 1);
+            return 0.5 * (1 + Math.cos(Math.PI * t));
+        }
+        // In the middle of the range — full gain
+        return 1.0;
+    }
+    /**
+     * Reset state (called on transport stop).
+     * Clears the punched-in state without emitting punch-out signals,
+     * since transport stop implies recording has already ceased.
+     */
+    reset() {
+        this._isPunchedIn = false;
+        this._emitStateChanged();
+    }
+    // ─── Private helpers ────────────────────────────────────────────────
+    /**
+     * Execute a punch-in: transition to recording state and notify listeners.
+     */
+    _doPunchIn() {
+        this._isPunchedIn = true;
+        const trackIds = Array.from(this._armedTrackIds);
+        this.punchInTriggered.emit(trackIds);
+        this._emitStateChanged();
+    }
+    /**
+     * Execute a punch-out: transition out of recording state and notify listeners.
+     */
+    _doPunchOut() {
+        this._isPunchedIn = false;
+        const trackIds = Array.from(this._armedTrackIds);
+        this.punchOutTriggered.emit(trackIds);
+        this._emitStateChanged();
+    }
+    /**
+     * Emit a stateChanged signal with the current punch state snapshot.
+     */
+    _emitStateChanged() {
+        this.stateChanged.emit(this.getState());
+    }
+}
+//# sourceMappingURL=PunchRecordManager.js.map

package/dist/audio/engine/PunchRecordManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PunchRecordManager.js","sourceRoot":"","sources":["../../../src/audio/engine/PunchRecordManager.ts"],"names":[],"mappings":"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"}

package/dist/audio/engine/RoutingGraph.d.ts

@@ -0,0 +1,133 @@
+import { Signal } from '../../lib/Signal';
+/**
+ * RoutingGraph represents the DAW's signal flow as a directed graph.
+ *
+ * Each node is a track/bus/aux route. Edges represent audio connections:
+ *  - Direct outputs (track -> master bus)
+ *  - Send connections (track -> aux bus)
+ *  - Sidechain connections (track -> processor on another track)
+ *
+ * The graph is used to:
+ *  1. Compute topological processing order
+ *  2. Detect feedback loops
+ *  3. Determine which routes "feed" other routes
+ *  4. Optimize parallel processing opportunities
+ */
+export interface GraphNode {
+    id: string;
+    name: string;
+    type: 'audio' | 'midi' | 'aux' | 'bus' | 'master' | 'folder' | 'vca';
+    inputs: Set<string>;
+    outputs: Set<string>;
+    processed: boolean;
+    depth: number;
+}
+export interface FeedbackLoop {
+    path: string[];
+    description: string;
+}
+export declare class RoutingGraph {
+    private _nodes;
+    readonly graphChanged: Signal<void>;
+    readonly feedbackDetected: Signal<FeedbackLoop>;
+    /**
+     * Add a node to the graph.
+     * If a node with the same ID already exists, it is updated in place.
+     */
+    addNode(id: string, name: string, type: GraphNode['type']): void;
+    /**
+     * Remove a node and all edges that reference it.
+     */
+    removeNode(id: string): void;
+    /**
+     * Add a directed edge from one node to another.
+     * Both nodes must already exist in the graph.
+     */
+    addEdge(fromId: string, toId: string): void;
+    /**
+     * Remove a directed edge between two nodes.
+     */
+    removeEdge(fromId: string, toId: string): void;
+    /**
+     * Rebuild the entire graph from session state.
+     * Clears all existing nodes/edges and reconstructs from the provided
+     * track descriptors. Typically called after bulk routing changes.
+     */
+    rebuild(tracks: Array<{
+        id: string;
+        name: string;
+        type: string;
+        sendTargets: string[];
+        outputTarget: string;
+    }>): void;
+    /**
+     * Compute a valid processing order using Kahn's algorithm for
+     * topological sorting. Leaf nodes (no inputs) are processed first,
+     * working upward to the master bus.
+     *
+     * If cycles exist, the returned order will be incomplete (nodes
+     * involved in cycles are omitted). Use detectFeedback() to identify
+     * those cycles.
+     *
+     * @returns An array of node IDs in processing order.
+     */
+    getProcessingOrder(): string[];
+    /**
+     * Detect all feedback loops (cycles) in the graph using DFS.
+     * Returns an array of FeedbackLoop descriptors, each containing the
+     * ordered path of node IDs that form the cycle.
+     */
+    detectFeedback(): FeedbackLoop[];
+    /**
+     * Check whether route A feeds (directly or indirectly) into route B.
+     * Uses BFS from A, following output edges, to determine reachability.
+     */
+    feeds(fromId: string, toId: string): boolean;
+    /**
+     * Check whether route A directly feeds into route B (single hop).
+     */
+    directFeeds(fromId: string, toId: string): boolean;
+    /**
+     * Get all routes that feed (directly or indirectly) into the given route.
+     * Traverses backward from the target, following input edges via BFS.
+     */
+    getUpstream(nodeId: string): string[];
+    /**
+     * Get all routes that the given route feeds (directly or indirectly) into.
+     * Traverses forward from the source, following output edges via BFS.
+     */
+    getDownstream(nodeId: string): string[];
+    /**
+     * Find groups of nodes that can be processed in parallel.
+     * Nodes at the same depth in the topological ordering have no
+     * dependencies on each other and can safely run concurrently.
+     *
+     * Uses a BFS-based level assignment: leaf nodes (in-degree 0) are
+     * at level 0, their consumers at level 1, and so on. Nodes at the
+     * same level form a parallel group.
+     *
+     * @returns An array of groups, where each group is an array of node IDs
+     *          that can be processed simultaneously. Groups are returned in
+     *          processing order (group 0 first, then group 1, etc.).
+     */
+    getParallelGroups(): string[][];
+    /**
+     * Get a single node by ID.
+     */
+    getNode(id: string): GraphNode | undefined;
+    /**
+     * Get all nodes as a read-only array.
+     */
+    get nodes(): ReadonlyArray<GraphNode>;
+    /**
+     * Clear all nodes and edges, resetting the graph to an empty state.
+     */
+    clear(): void;
+    /**
+     * Compute the depth of each node (longest path from any leaf to this node).
+     * Leaf nodes (no inputs) have depth 0. Used for parallel group assignment
+     * and rendering the graph visualization.
+     */
+    private _computeDepths;
+}
+//# sourceMappingURL=RoutingGraph.d.ts.map

package/dist/audio/engine/RoutingGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingGraph.d.ts","sourceRoot":"","sources":["../../../src/audio/engine/RoutingGraph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAqC;IAEnD,SAAgB,YAAY,eAAsB;IAClD,SAAgB,gBAAgB,uBAA8B;IAI9D;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI;IAmBhE;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAoB5B;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAU3C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAY9C;;;;OAIG;IACH,OAAO,CACH,MAAM,EAAE,KAAK,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACxB,CAAC,GACH,IAAI;IAkDP;;;;;;;;;;OAUG;IACH,kBAAkB,IAAI,MAAM,EAAE;IA0C9B;;;;OAIG;IACH,cAAc,IAAI,YAAY,EAAE;IA6DhC;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAyB5C;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAMlD;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAyBrC;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IA2BvC;;;;;;;;;;;;OAYG;IACH,iBAAiB,IAAI,MAAM,EAAE,EAAE;IAqE/B;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI1C;;OAEG;IACH,IAAI,KAAK,IAAI,aAAa,CAAC,SAAS,CAAC,CAEpC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAoBzB"}