@drop-ai/core 0.2.0

package/dist/audio/MeterUtils.js

@@ -0,0 +1,71 @@
+/**
+ * Utility functions for audio metering.
+ * Operates on raw Float32Array time-domain data from AnalyserNode.
+ *
+ * Ardour reference: libs/ardour/meter.cc
+ */
+/**
+ * Convert a linear amplitude value to decibels (dBFS).
+ * Returns -Infinity for zero or negative input.
+ */
+export function linearToDb(linear) {
+    if (linear <= 0)
+        return -Infinity;
+    return 20 * Math.log10(linear);
+}
+/**
+ * Convert a decibel value to linear amplitude.
+ * Returns 0 for -Infinity input.
+ */
+export function dbToLinear(db) {
+    if (db === -Infinity)
+        return 0;
+    return Math.pow(10, db / 20);
+}
+/**
+ * Calculate peak level in dBFS from an AnalyserNode's time-domain data.
+ */
+export function calculatePeakDb(analyser) {
+    const buffer = new Float32Array(analyser.fftSize);
+    analyser.getFloatTimeDomainData(buffer);
+    let peak = 0;
+    for (let i = 0; i < buffer.length; i++) {
+        const abs = Math.abs(buffer[i]);
+        if (abs > peak) {
+            peak = abs;
+        }
+    }
+    return linearToDb(peak);
+}
+/**
+ * Calculate RMS level in dBFS from an AnalyserNode's time-domain data.
+ */
+export function calculateRmsDb(analyser) {
+    const buffer = new Float32Array(analyser.fftSize);
+    analyser.getFloatTimeDomainData(buffer);
+    let sumSquares = 0;
+    for (let i = 0; i < buffer.length; i++) {
+        sumSquares += buffer[i] * buffer[i];
+    }
+    const rms = Math.sqrt(sumSquares / buffer.length);
+    return linearToDb(rms);
+}
+/**
+ * K-Metering (Item 7)
+ * K-System meters offset dBFS so that the reference level sits at 0 on the scale.
+ * K-14: 0 on scale = -14 dBFS (mastering/broadcast)
+ * K-20: 0 on scale = -20 dBFS (film/large-venue)
+ */
+/** Apply K-14 offset: dBFS + 14 */
+export function kMeter14(dbfs) {
+    return dbfs + 14;
+}
+/** Apply K-20 offset: dBFS + 20 */
+export function kMeter20(dbfs) {
+    return dbfs + 20;
+}
+/** Generic K-meter offset */
+export function kMeter(dbfs, kLevel) {
+    return dbfs + kLevel;
+}
+//# sourceMappingURL=MeterUtils.js.map

package/dist/audio/MeterUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeterUtils.js","sourceRoot":"","sources":["../../src/audio/MeterUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACrC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,QAAQ,CAAC;IAClC,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACjC,IAAI,EAAE,KAAK,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAsB;IAClD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,GAAG,GAAG,IAAI,EAAE,CAAC;YACb,IAAI,GAAG,GAAG,CAAC;QACf,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB;IACjD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AAEH,mCAAmC;AACnC,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,OAAO,IAAI,GAAG,EAAE,CAAC;AACrB,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,OAAO,IAAI,GAAG,EAAE,CAAC;AACrB,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,MAAe;IAChD,OAAO,IAAI,GAAG,MAAM,CAAC;AACzB,CAAC"}

package/dist/audio/OfflineExporter.d.ts

@@ -0,0 +1,48 @@
+import { FrameCount, TrackId } from '../domain/types';
+import { ExportConfig } from '../domain/ExportConfig';
+import { ExportStatus } from '../domain/ExportStatus';
+/**
+ * Offline Audio Exporter
+ * Ardour 참조: libs/ardour/export_handler.cc
+ *
+ * Web Audio의 OfflineAudioContext를 활용하여 실시간보다 빠르게 렌더링합니다.
+ */
+export declare class OfflineExporter {
+    /**
+     * Export audio using Offline Rendering
+     *
+     * @param config Export configuration
+     * @param status Export status (for progress tracking)
+     * @param getTrackAudio Callback to get track audio for a given time range
+     */
+    static export(config: ExportConfig, status: ExportStatus, getTrackAudio: (trackIds: TrackId[], startFrame: FrameCount, endFrame: FrameCount) => Promise<AudioBuffer>): Promise<void>;
+    /**
+     * Normalize audio buffer using peak normalization.
+     *
+     * NOTE: Despite previously being labeled as "LUFS", this method performs simple
+     * peak normalization (not ITU-R BS.1770 loudness measurement). The target value
+     * is interpreted as a peak level in dBFS, not as an integrated loudness value.
+     * True LUFS normalization would require K-weighted filtering and gated measurement.
+     *
+     * @param buffer Audio data (modified in-place)
+     * @param targetPeakDb Target peak level in dBFS (default: -14 dBFS)
+     */
+    private static normalizeBuffer;
+    /**
+     * Encode AudioBuffer to Blob
+     */
+    private static encodeToBlob;
+    /**
+     * Encode to MP3 format using lamejs
+     */
+    private static encodeMP3;
+    /**
+     * Stem Export: export each track individually as separate files.
+     * Returns a map of trackId -> { blob, filename }.
+     */
+    static exportStems(config: ExportConfig, status: ExportStatus, trackIds: TrackId[], trackNames: Map<TrackId, string>, getTrackAudio: (ids: TrackId[], startFrame: FrameCount, endFrame: FrameCount) => Promise<AudioBuffer>): Promise<Map<TrackId, {
+        blob: Blob;
+        filename: string;
+    }>>;
+}
+//# sourceMappingURL=OfflineExporter.d.ts.map

package/dist/audio/OfflineExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineExporter.d.ts","sourceRoot":"","sources":["../../src/audio/OfflineExporter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAkB,MAAM,wBAAwB,CAAC;AAOtE;;;;;GAKG;AACH,qBAAa,eAAe;IACxB;;;;;;OAMG;WACiB,MAAM,CACtB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,aAAa,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,GAC3G,OAAO,CAAC,IAAI,CAAC;IAyEhB;;;;;;;;;;OAUG;mBACkB,eAAe;IA0BpC;;OAEG;mBACkB,YAAY;IAkBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IA0CxB;;;OAGG;WACiB,WAAW,CAC3B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,OAAO,EAAE,EACnB,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,EAChC,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,GACtG,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAqD7D"}

package/dist/audio/OfflineExporter.js

@@ -0,0 +1,202 @@
+import { ExportProgress } from '../domain/ExportStatus';
+import { AudioBufferToWav } from '../utils/AudioBufferToWav';
+import { OggEncoder } from '../utils/OggEncoder';
+import { FlacEncoder } from '../utils/FlacEncoder';
+import { DitherProcessor, DitherType } from '../utils/DitherProcessor';
+import * as lamejs from 'lamejs';
+/**
+ * Offline Audio Exporter
+ * Ardour 참조: libs/ardour/export_handler.cc
+ *
+ * Web Audio의 OfflineAudioContext를 활용하여 실시간보다 빠르게 렌더링합니다.
+ */
+export class OfflineExporter {
+    /**
+     * Export audio using Offline Rendering
+     *
+     * @param config Export configuration
+     * @param status Export status (for progress tracking)
+     * @param getTrackAudio Callback to get track audio for a given time range
+     */
+    static async export(config, status, getTrackAudio) {
+        try {
+            if (!config.validate()) {
+                throw new Error('Invalid export configuration');
+            }
+            const duration = config.getDuration();
+            const durationSeconds = duration / config.sampleRate;
+            console.log(`[OfflineExporter] Starting export: ${durationSeconds}s at ${config.sampleRate}Hz`);
+            console.log(`[OfflineExporter] Export config trackIds:`, config.trackIds, `exportMasterOnly:`, config.exportMasterOnly);
+            // Initialize status
+            status.init(duration, config.getFullPath());
+            // Render Phase
+            status.setProgress(ExportProgress.RENDERING);
+            // Get trackIds to pass to getTrackAudio
+            const trackIdsToExport = config.trackIds && config.trackIds.length > 0
+                ? config.trackIds
+                : undefined; // undefined means "all tracks"
+            console.log(`[OfflineExporter] Calling getTrackAudio with trackIds:`, trackIdsToExport);
+            const renderedBuffer = await getTrackAudio(trackIdsToExport, config.startFrame, config.endFrame);
+            // Update progress
+            status.updateProcessedFrames(duration);
+            // Normalize Phase (if enabled)
+            if (config.normalize) {
+                status.setProgress(ExportProgress.NORMALIZING);
+                await this.normalizeBuffer(renderedBuffer, config.targetPeakDb);
+            }
+            // Dithering Phase (before encoding, when reducing bit depth)
+            if (config.ditherType !== DitherType.NONE) {
+                const targetBits = config.sampleFormat === 'int16' ? 16 :
+                    config.sampleFormat === 'int24' ? 24 : 32;
+                if (targetBits < 32) {
+                    for (let ch = 0; ch < renderedBuffer.numberOfChannels; ch++) {
+                        DitherProcessor.apply(renderedBuffer.getChannelData(ch), targetBits, config.ditherType);
+                    }
+                }
+            }
+            // Encoding Phase
+            status.setProgress(ExportProgress.ENCODING);
+            const blob = await this.encodeToBlob(renderedBuffer, config);
+            // Create object URL
+            const url = URL.createObjectURL(blob);
+            // Complete
+            status.complete(blob, url);
+            console.log(`[OfflineExporter] Export completed: ${blob.size} bytes`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            console.error(`[OfflineExporter] Export failed:`, error);
+            status.setError(message);
+        }
+    }
+    /**
+     * Normalize audio buffer using peak normalization.
+     *
+     * NOTE: Despite previously being labeled as "LUFS", this method performs simple
+     * peak normalization (not ITU-R BS.1770 loudness measurement). The target value
+     * is interpreted as a peak level in dBFS, not as an integrated loudness value.
+     * True LUFS normalization would require K-weighted filtering and gated measurement.
+     *
+     * @param buffer Audio data (modified in-place)
+     * @param targetPeakDb Target peak level in dBFS (default: -14 dBFS)
+     */
+    static async normalizeBuffer(buffer, targetPeakDb) {
+        const target = targetPeakDb !== null && targetPeakDb !== void 0 ? targetPeakDb : -14; // Default to -14 dBFS
+        let maxPeak = 0;
+        for (let ch = 0; ch < buffer.numberOfChannels; ch++) {
+            const data = buffer.getChannelData(ch);
+            for (let i = 0; i < data.length; i++) {
+                maxPeak = Math.max(maxPeak, Math.abs(data[i]));
+            }
+        }
+        if (maxPeak === 0)
+            return;
+        // Convert dBFS target to linear gain and scale so the peak hits that level
+        const targetLinear = Math.pow(10, target / 20);
+        const gain = targetLinear / maxPeak;
+        // Apply gain
+        for (let ch = 0; ch < buffer.numberOfChannels; ch++) {
+            const data = buffer.getChannelData(ch);
+            for (let i = 0; i < data.length; i++) {
+                data[i] *= gain;
+            }
+        }
+    }
+    /**
+     * Encode AudioBuffer to Blob
+     */
+    static async encodeToBlob(buffer, config) {
+        var _a;
+        switch (config.format) {
+            case 'wav':
+                return AudioBufferToWav.encode(buffer, config.sampleFormat);
+            case 'mp3':
+                return this.encodeMP3(buffer, config);
+            case 'ogg':
+                return OggEncoder.encode(buffer, (_a = config.quality) !== null && _a !== void 0 ? _a : 0.5);
+            case 'flac':
+                return FlacEncoder.encode(buffer, config.sampleFormat === 'int24' ? 24 : 16);
+            default:
+                throw new Error(`Unknown format: ${config.format}`);
+        }
+    }
+    /**
+     * Encode to MP3 format using lamejs
+     */
+    static encodeMP3(buffer, config) {
+        const channels = buffer.numberOfChannels;
+        const sampleRate = buffer.sampleRate;
+        const kbps = config.bitrate || 128; // Default 128kbps
+        const mp3encoder = new lamejs.Mp3Encoder(channels, sampleRate, kbps);
+        const mp3Data = [];
+        // Convert Float32 to Int16
+        // Lamejs expects Int16 PCM data
+        const left = buffer.getChannelData(0);
+        const right = channels > 1 ? buffer.getChannelData(1) : undefined;
+        const leftInt16 = new Int16Array(left.length);
+        const rightInt16 = right ? new Int16Array(right.length) : undefined;
+        for (let i = 0; i < left.length; i++) {
+            // Clamp and convert
+            const s = Math.max(-1, Math.min(1, left[i]));
+            leftInt16[i] = s < 0 ? s * 0x8000 : s * 0x7FFF;
+            if (right && rightInt16) {
+                const sR = Math.max(-1, Math.min(1, right[i]));
+                rightInt16[i] = sR < 0 ? sR * 0x8000 : sR * 0x7FFF;
+            }
+        }
+        // Encode blocks
+        const mp3buf = mp3encoder.encodeBuffer(leftInt16, rightInt16);
+        if (mp3buf.length > 0) {
+            mp3Data.push(mp3buf);
+        }
+        // Flush
+        const mp3bufFlush = mp3encoder.flush();
+        if (mp3bufFlush.length > 0) {
+            mp3Data.push(mp3bufFlush);
+        }
+        return new Blob(mp3Data, { type: 'audio/mp3' });
+    }
+    /**
+     * Stem Export: export each track individually as separate files.
+     * Returns a map of trackId -> { blob, filename }.
+     */
+    static async exportStems(config, status, trackIds, trackNames, getTrackAudio) {
+        const results = new Map();
+        if (!config.validate()) {
+            throw new Error('Invalid export configuration');
+        }
+        const totalTracks = trackIds.length;
+        const duration = config.getDuration();
+        status.init(duration * totalTracks, config.getFullPath());
+        status.setProgress(ExportProgress.RENDERING);
+        for (let i = 0; i < trackIds.length; i++) {
+            if (status.aborted)
+                break;
+            const trackId = trackIds[i];
+            const trackName = trackNames.get(trackId) || `Track_${i + 1}`;
+            const safeTrackName = trackName.replace(/[^a-zA-Z0-9_-]/g, '_');
+            console.log(`[OfflineExporter] Stem ${i + 1}/${totalTracks}: ${trackName}`);
+            // Render single track
+            const renderedBuffer = await getTrackAudio([trackId], config.startFrame, config.endFrame);
+            // Normalize if enabled
+            if (config.normalize) {
+                await this.normalizeBuffer(renderedBuffer, config.targetPeakDb);
+            }
+            // Encode
+            const blob = await this.encodeToBlob(renderedBuffer, config);
+            const filename = `${config.filename}_${safeTrackName}.${config.format}`;
+            results.set(trackId, { blob, filename });
+            status.updateProcessedFrames(duration * (i + 1));
+        }
+        if (!status.aborted) {
+            // Create a combined blob (or return individual stems)
+            const firstResult = results.values().next().value;
+            if (firstResult) {
+                const url = URL.createObjectURL(firstResult.blob);
+                status.complete(firstResult.blob, url);
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=OfflineExporter.js.map

package/dist/audio/OfflineExporter.js.map

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

package/dist/audio/ProcessingGraph.d.ts

@@ -0,0 +1,152 @@
+/**
+ * ProcessingGraph — a directed acyclic graph (DAG) for modeling signal-processing
+ * node execution order.
+ *
+ * Inspired by Ardour's internal graph scheduler (`libs/ardour/graph.cc`).
+ * The graph is a standalone utility with no audio-framework dependencies,
+ * making it suitable for unit testing and headless use.
+ *
+ * Key capabilities:
+ * - Add / remove nodes and directed edges (from → to means "from depends on to")
+ * - Topological sort via Kahn's algorithm — produces a valid execution order
+ * - Cycle detection via iterative DFS
+ * - Parallel-group extraction — nodes at the same "depth" can run concurrently
+ *
+ * @module ProcessingGraph
+ */
+/**
+ * A node in the processing graph.
+ *
+ * `process()` is optional — the graph is purely structural; callers decide
+ * whether to invoke processing logic.
+ */
+export interface GraphNode {
+    /** Unique identifier for this node. */
+    id: string;
+    /** Optional processing callback invoked during graph execution. */
+    process?(): void;
+}
+/**
+ * ProcessingGraph models a DAG of {@link GraphNode}s connected by directed
+ * dependency edges.
+ *
+ * An edge `from → to` means "node `from` depends on node `to`" — i.e. `to`
+ * must be processed **before** `from`.
+ *
+ * @example
+ * ```ts
+ * const graph = new ProcessingGraph();
+ * graph.addNode({ id: 'input' });
+ * graph.addNode({ id: 'eq' });
+ * graph.addNode({ id: 'compressor' });
+ * graph.addNode({ id: 'output' });
+ *
+ * graph.addEdge('eq', 'input');          // eq depends on input
+ * graph.addEdge('compressor', 'eq');     // compressor depends on eq
+ * graph.addEdge('output', 'compressor'); // output depends on compressor
+ *
+ * const order = graph.topologicalSort(); // [input, eq, compressor, output]
+ * ```
+ */
+export declare class ProcessingGraph {
+    /** All registered nodes keyed by id. */
+    private nodes;
+    /**
+     * Adjacency list storing **dependencies** (incoming edges).
+     * `edges.get(nodeId)` → set of node ids that `nodeId` depends on.
+     */
+    private edges;
+    /**
+     * Register a node in the graph.
+     *
+     * If a node with the same `id` already exists it will be replaced,
+     * but its edges are preserved.
+     *
+     * @param node - The graph node to add.
+     */
+    addNode(node: GraphNode): void;
+    /**
+     * Remove a node and all edges that reference it (both incoming and
+     * outgoing).
+     *
+     * @param nodeId - The id of the node to remove.
+     */
+    removeNode(nodeId: string): void;
+    /**
+     * Return the node with the given id, or `undefined` if it does not exist.
+     *
+     * @param nodeId - The id to look up.
+     */
+    getNode(nodeId: string): GraphNode | undefined;
+    /**
+     * The total number of nodes currently in the graph.
+     */
+    get nodeCount(): number;
+    /**
+     * Add a directed dependency edge: `from` depends on `to`.
+     *
+     * Both node ids must already exist in the graph; otherwise the call is a
+     * no-op.
+     *
+     * @param from - The node that has the dependency.
+     * @param to   - The node that must be processed first.
+     */
+    addEdge(from: string, to: string): void;
+    /**
+     * Remove a directed dependency edge.
+     *
+     * @param from - The dependent node.
+     * @param to   - The dependency to remove.
+     */
+    removeEdge(from: string, to: string): void;
+    /**
+     * Return the nodes in a valid execution order (dependencies first) using
+     * Kahn's algorithm.
+     *
+     * @throws {Error} If the graph contains a cycle (not all nodes can be
+     *   sorted).
+     * @returns An array of {@link GraphNode} in topological order.
+     */
+    topologicalSort(): GraphNode[];
+    /**
+     * Partition the graph into groups of nodes that can be executed in
+     * parallel.
+     *
+     * Each group contains nodes whose dependencies have all been satisfied by
+     * earlier groups. Within a group the nodes are independent and can run
+     * concurrently.
+     *
+     * @throws {Error} If the graph contains a cycle.
+     * @returns An array of arrays — each inner array is a parallel group
+     *   ordered from first-to-execute to last.
+     */
+    getParallelGroups(): GraphNode[][];
+    /**
+     * Detect whether the graph contains any cycles using iterative DFS.
+     *
+     * @returns `true` if a cycle exists, `false` otherwise.
+     */
+    detectCycles(): boolean;
+    /**
+     * Return the ids of all nodes that `nodeId` directly depends on
+     * (its prerequisites).
+     *
+     * @param nodeId - The node to query.
+     * @returns An array of dependency node ids, or an empty array if the node
+     *   has no dependencies or does not exist.
+     */
+    getDependencies(nodeId: string): string[];
+    /**
+     * Return the ids of all nodes that directly depend on `nodeId`
+     * (its consumers / dependents).
+     *
+     * @param nodeId - The node to query.
+     * @returns An array of dependent node ids.
+     */
+    getDependents(nodeId: string): string[];
+    /**
+     * Remove all nodes and edges from the graph.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=ProcessingGraph.d.ts.map

package/dist/audio/ProcessingGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessingGraph.d.ts","sourceRoot":"","sources":["../../src/audio/ProcessingGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACtB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,mEAAmE;IACnE,OAAO,CAAC,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAe;IACxB,wCAAwC;IACxC,OAAO,CAAC,KAAK,CAAqC;IAElD;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAuC;IAMpD;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAO9B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAShC;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI9C;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAMD;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAUvC;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAW1C;;;;;;;OAOG;IACH,eAAe,IAAI,SAAS,EAAE;IAoE9B;;;;;;;;;;;OAWG;IACH,iBAAiB,IAAI,SAAS,EAAE,EAAE;IA2ElC;;;;OAIG;IACH,YAAY,IAAI,OAAO;IA6DvB;;;;;;;OAOG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAKzC;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAcvC;;OAEG;IACH,KAAK,IAAI,IAAI;CAIhB"}