@drop-ai/core 0.2.0 → 0.3.1

package/dist/audio/engine/SidechainRouter.js

@@ -0,0 +1,290 @@
+import { Signal } from '../../lib/Signal';
+/**
+ * SidechainRouter manages the actual audio signal routing for sidechain connections.
+ *
+ * In the Web Audio context, sidechain routing works by:
+ * 1. Tapping the source track's audio output (pre or post fader)
+ * 2. Optionally applying a high-pass filter
+ * 3. Feeding it into the target processor's sidechain input
+ *
+ * The router maintains a buffer-per-config that holds the latest audio block
+ * from the source track, available for the target processor to read.
+ */
+export class SidechainRouter {
+    /**
+     * @param sampleRate - The audio sample rate (e.g. 44100, 48000)
+     */
+    constructor(sampleRate = 44100) {
+        this._configs = new Map();
+        /** Buffer storage: configId -> latest audio block from source */
+        this._sidechainBuffers = new Map();
+        /** HPF filter state per config (one state per channel, keyed by configId) */
+        this._filterStates = new Map();
+        this.routingChanged = new Signal();
+        this._sampleRate = sampleRate;
+    }
+    // ─── Configuration Management ──────────────────────────────────────────────
+    /**
+     * Register a sidechain configuration.
+     * Initialises the buffer and filter state for the new config.
+     */
+    addConfig(config) {
+        this._configs.set(config.id, config);
+        // Initialise an empty buffer
+        this._sidechainBuffers.set(config.id, {
+            data: [],
+            blockSize: 0,
+            valid: false,
+        });
+        // Initialise filter states (start with 2 channels; will resize as needed)
+        this._rebuildFilterState(config);
+        // Listen for filter parameter changes so we can recompute coefficients
+        config.filterChanged.connect(() => {
+            this._rebuildFilterState(config);
+        });
+        this.routingChanged.emit();
+    }
+    /**
+     * Remove a sidechain configuration and clean up its resources.
+     */
+    removeConfig(configId) {
+        if (!this._configs.has(configId)) {
+            return;
+        }
+        this._configs.delete(configId);
+        this._sidechainBuffers.delete(configId);
+        this._filterStates.delete(configId);
+        this.routingChanged.emit();
+    }
+    /**
+     * Get config by ID.
+     */
+    getConfig(configId) {
+        return this._configs.get(configId);
+    }
+    /**
+     * Get all configs targeting a specific track.
+     */
+    getConfigsForTarget(trackId) {
+        const result = [];
+        for (const config of this._configs.values()) {
+            if (config.targetTrackId === trackId) {
+                result.push(config);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get all configs sourcing from a specific track.
+     */
+    getConfigsForSource(trackId) {
+        const result = [];
+        for (const config of this._configs.values()) {
+            if (config.sourceTrackId === trackId) {
+                result.push(config);
+            }
+        }
+        return result;
+    }
+    // ─── Audio Routing ─────────────────────────────────────────────────────────
+    /**
+     * Called by the audio engine when a source track produces audio.
+     * Stores the audio block for later retrieval by target processors.
+     *
+     * For every config that sources from the given trackId, we copy the
+     * audio data into the config's sidechain buffer.
+     *
+     * @param trackId - The source track that just produced audio
+     * @param audioData - Per-channel audio data (e.g. [leftChannel, rightChannel])
+     * @param blockSize - Number of samples per channel in this block
+     */
+    feedSourceAudio(trackId, audioData, blockSize) {
+        for (const config of this._configs.values()) {
+            if (config.sourceTrackId !== trackId || !config.enabled) {
+                continue;
+            }
+            const numChannels = audioData.length;
+            let buffer = this._sidechainBuffers.get(config.id);
+            // Allocate or resize the buffer if needed
+            if (!buffer ||
+                buffer.data.length !== numChannels ||
+                buffer.blockSize !== blockSize) {
+                buffer = {
+                    data: new Array(numChannels)
+                        .fill(null)
+                        .map(() => new Float32Array(blockSize)),
+                    blockSize,
+                    valid: false,
+                };
+                this._sidechainBuffers.set(config.id, buffer);
+            }
+            // Copy source audio into the sidechain buffer
+            for (let ch = 0; ch < numChannels; ch++) {
+                buffer.data[ch].set(audioData[ch].subarray(0, blockSize));
+            }
+            buffer.valid = true;
+        }
+    }
+    /**
+     * Called by the target processor to get the sidechain input.
+     * Returns the latest audio block from the source track (with optional HPF applied),
+     * or null if no valid data is available.
+     *
+     * @param configId - The sidechain configuration ID
+     * @returns Per-channel audio data, or null if unavailable
+     */
+    getSidechainInput(configId) {
+        const config = this._configs.get(configId);
+        if (!config || !config.enabled) {
+            return null;
+        }
+        const buffer = this._sidechainBuffers.get(configId);
+        if (!buffer || !buffer.valid || buffer.data.length === 0) {
+            return null;
+        }
+        // If HPF is enabled, apply it to a copy of the buffer
+        if (config.sidechainFilterEnabled) {
+            return this._applyHPF(configId, buffer.data);
+        }
+        // Return copies so the caller can't mutate our internal buffers
+        return buffer.data.map((ch) => new Float32Array(ch));
+    }
+    // ─── HPF (High-Pass Filter) ────────────────────────────────────────────────
+    /**
+     * Apply a 2nd-order Butterworth high-pass filter to the sidechain signal.
+     * Processes in-place on copies of the input channels.
+     *
+     * The Butterworth HPF transfer function is implemented as a Direct Form I
+     * biquad filter: y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]
+     */
+    _applyHPF(configId, inputChannels) {
+        const numChannels = inputChannels.length;
+        let states = this._filterStates.get(configId);
+        // Ensure we have a filter state per channel
+        if (!states || states.length !== numChannels) {
+            const config = this._configs.get(configId);
+            if (!config) {
+                return inputChannels.map((ch) => new Float32Array(ch));
+            }
+            states = new Array(numChannels)
+                .fill(null)
+                .map(() => computeHPFCoefficients(config.sidechainFilterFrequency, this._sampleRate));
+            this._filterStates.set(configId, states);
+        }
+        const output = [];
+        for (let ch = 0; ch < numChannels; ch++) {
+            const input = inputChannels[ch];
+            const out = new Float32Array(input.length);
+            const state = states[ch];
+            for (let i = 0; i < input.length; i++) {
+                const x = input[i];
+                // Direct Form I biquad
+                const y = state.b0 * x +
+                    state.b1 * state.x1 +
+                    state.b2 * state.x2 -
+                    state.a1 * state.y1 -
+                    state.a2 * state.y2;
+                // Shift delay line
+                state.x2 = state.x1;
+                state.x1 = x;
+                state.y2 = state.y1;
+                state.y1 = y;
+                out[i] = y;
+            }
+            output.push(out);
+        }
+        return output;
+    }
+    /**
+     * Rebuild the filter state for a given config.
+     * Called when the config is added or its filter parameters change.
+     */
+    _rebuildFilterState(config) {
+        const buffer = this._sidechainBuffers.get(config.id);
+        const numChannels = buffer ? Math.max(buffer.data.length, 2) : 2;
+        const states = new Array(numChannels)
+            .fill(null)
+            .map(() => computeHPFCoefficients(config.sidechainFilterFrequency, this._sampleRate));
+        this._filterStates.set(config.id, states);
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────────────
+    /**
+     * Reset all buffers and filter states.
+     * Typically called when transport stops or seeks.
+     */
+    reset() {
+        for (const [configId, buffer] of this._sidechainBuffers.entries()) {
+            for (const ch of buffer.data) {
+                ch.fill(0);
+            }
+            buffer.valid = false;
+            // Reset filter delay lines while preserving coefficients
+            const states = this._filterStates.get(configId);
+            if (states) {
+                for (const state of states) {
+                    state.x1 = 0;
+                    state.x2 = 0;
+                    state.y1 = 0;
+                    state.y2 = 0;
+                }
+            }
+        }
+    }
+    /**
+     * Update the sample rate. Recomputes all HPF filter coefficients.
+     */
+    setSampleRate(sampleRate) {
+        this._sampleRate = sampleRate;
+        for (const config of this._configs.values()) {
+            this._rebuildFilterState(config);
+        }
+    }
+}
+// ─── Helper Functions ──────────────────────────────────────────────────────────
+/**
+ * Compute the biquad filter coefficients for a 2nd-order Butterworth high-pass filter.
+ *
+ * Derivation from the analogue Butterworth prototype:
+ *   H(s) = s^2 / (s^2 + sqrt(2)*s + 1)
+ *
+ * Bilinear transform with pre-warping:
+ *   omega_c = 2 * pi * frequency / sampleRate
+ *   K = tan(omega_c / 2)
+ *   norm = 1 / (1 + sqrt(2)*K + K^2)
+ *
+ *   b0 = norm
+ *   b1 = -2 * norm
+ *   b2 = norm
+ *   a1 = 2 * (K^2 - 1) * norm
+ *   a2 = (1 - sqrt(2)*K + K^2) * norm
+ *
+ * The returned state has zeroed delay lines, ready for immediate use.
+ *
+ * @param frequency - HPF cutoff frequency in Hz
+ * @param sampleRate - Audio sample rate in Hz
+ * @returns A BiquadFilterState with computed coefficients and zeroed state
+ */
+export function computeHPFCoefficients(frequency, sampleRate) {
+    // Clamp frequency to a safe range: above 0 and below Nyquist
+    const nyquist = sampleRate / 2;
+    const freq = Math.max(1, Math.min(frequency, nyquist * 0.99));
+    const omega = (2 * Math.PI * freq) / sampleRate;
+    const K = Math.tan(omega / 2);
+    const K2 = K * K;
+    const sqrt2 = Math.SQRT2;
+    const norm = 1 / (1 + sqrt2 * K + K2);
+    return {
+        // Delay line state (zeroed)
+        x1: 0,
+        x2: 0,
+        y1: 0,
+        y2: 0,
+        // Coefficients
+        b0: norm,
+        b1: -2 * norm,
+        b2: norm,
+        a1: 2 * (K2 - 1) * norm,
+        a2: (1 - sqrt2 * K + K2) * norm,
+    };
+}
+//# sourceMappingURL=SidechainRouter.js.map

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

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

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

@@ -0,0 +1,71 @@
+import { Signal } from '../../lib/Signal';
+export interface XrunEvent {
+    timestamp: number;
+    frame: number;
+    type: 'underrun' | 'overrun';
+    duration?: number;
+}
+/**
+ * XrunTracker - Tracks buffer underrun/overrun events during recording
+ * and playback. Provides signals for real-time notification and
+ * query methods for post-session analysis.
+ */
+export declare class XrunTracker {
+    private _events;
+    private _isTracking;
+    private _totalXruns;
+    /** Signal emitted whenever an xrun is detected */
+    readonly xrunDetected: Signal<XrunEvent>;
+    /**
+     * Start tracking xrun events.
+     * Clears any previously recorded events.
+     */
+    startTracking(): void;
+    /**
+     * Stop tracking xrun events.
+     */
+    stopTracking(): void;
+    /**
+     * Record an xrun event.
+     * Only records if tracking is active.
+     * @param frame - The session frame position where the xrun occurred
+     * @param type - Whether this was an underrun or overrun
+     * @param duration - Optional estimated glitch duration in samples
+     */
+    reportXrun(frame: number, type: 'underrun' | 'overrun', duration?: number): void;
+    /**
+     * Get all recorded xrun events.
+     */
+    getEvents(): XrunEvent[];
+    /**
+     * Get all xrun events that occurred at or after the given frame.
+     */
+    getEventsSince(frame: number): XrunEvent[];
+    /**
+     * Get the total number of xruns recorded (persists across reset of events).
+     */
+    getTotalCount(): number;
+    /**
+     * Get the most recent xrun event, if any.
+     */
+    getLastEvent(): XrunEvent | undefined;
+    /**
+     * Check if any xruns have been recorded.
+     */
+    hasXruns(): boolean;
+    /**
+     * Reset all tracked events and counters.
+     */
+    reset(): void;
+    /**
+     * Get a summary of all recorded xrun events.
+     */
+    getSummary(): {
+        total: number;
+        underruns: number;
+        overruns: number;
+        firstFrame?: number;
+        lastFrame?: number;
+    };
+}
+//# sourceMappingURL=XrunTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XrunTracker.d.ts","sourceRoot":"","sources":["../../../src/audio/engine/XrunTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,WAAW,CAAa;IAEhC,kDAAkD;IAClD,SAAgB,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,CAA2B;IAE1E;;;OAGG;IACH,aAAa,IAAI,IAAI;IAIrB;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAehF;;OAEG;IACH,SAAS,IAAI,SAAS,EAAE;IAIxB;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE;IAI1C;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,YAAY,IAAI,SAAS,GAAG,SAAS;IAMrC;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,UAAU,IAAI;QACV,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB;CA6BJ"}

package/dist/audio/engine/XrunTracker.js

@@ -0,0 +1,118 @@
+import { Signal } from '../../lib/Signal';
+/**
+ * XrunTracker - Tracks buffer underrun/overrun events during recording
+ * and playback. Provides signals for real-time notification and
+ * query methods for post-session analysis.
+ */
+export class XrunTracker {
+    constructor() {
+        this._events = [];
+        this._isTracking = false;
+        this._totalXruns = 0;
+        /** Signal emitted whenever an xrun is detected */
+        this.xrunDetected = new Signal();
+    }
+    /**
+     * Start tracking xrun events.
+     * Clears any previously recorded events.
+     */
+    startTracking() {
+        this._isTracking = true;
+    }
+    /**
+     * Stop tracking xrun events.
+     */
+    stopTracking() {
+        this._isTracking = false;
+    }
+    /**
+     * Record an xrun event.
+     * Only records if tracking is active.
+     * @param frame - The session frame position where the xrun occurred
+     * @param type - Whether this was an underrun or overrun
+     * @param duration - Optional estimated glitch duration in samples
+     */
+    reportXrun(frame, type, duration) {
+        if (!this._isTracking)
+            return;
+        const event = {
+            timestamp: Date.now(),
+            frame,
+            type,
+            duration,
+        };
+        this._events.push(event);
+        this._totalXruns++;
+        this.xrunDetected.emit(event);
+    }
+    /**
+     * Get all recorded xrun events.
+     */
+    getEvents() {
+        return [...this._events];
+    }
+    /**
+     * Get all xrun events that occurred at or after the given frame.
+     */
+    getEventsSince(frame) {
+        return this._events.filter(e => e.frame >= frame);
+    }
+    /**
+     * Get the total number of xruns recorded (persists across reset of events).
+     */
+    getTotalCount() {
+        return this._totalXruns;
+    }
+    /**
+     * Get the most recent xrun event, if any.
+     */
+    getLastEvent() {
+        return this._events.length > 0
+            ? this._events[this._events.length - 1]
+            : undefined;
+    }
+    /**
+     * Check if any xruns have been recorded.
+     */
+    hasXruns() {
+        return this._events.length > 0;
+    }
+    /**
+     * Reset all tracked events and counters.
+     */
+    reset() {
+        this._events = [];
+        this._totalXruns = 0;
+    }
+    /**
+     * Get a summary of all recorded xrun events.
+     */
+    getSummary() {
+        let underruns = 0;
+        let overruns = 0;
+        let firstFrame;
+        let lastFrame;
+        for (const event of this._events) {
+            if (event.type === 'underrun') {
+                underruns++;
+            }
+            else {
+                overruns++;
+            }
+            if (firstFrame === undefined || event.frame < firstFrame) {
+                firstFrame = event.frame;
+            }
+            if (lastFrame === undefined || event.frame > lastFrame) {
+                lastFrame = event.frame;
+            }
+        }
+        return {
+            total: this._events.length,
+            underruns,
+            overruns,
+            firstFrame,
+            lastFrame,
+        };
+    }
+}
+//# sourceMappingURL=XrunTracker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XrunTracker.js","sourceRoot":"","sources":["../../../src/audio/engine/XrunTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAS1C;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAAxB;QACY,YAAO,GAAgB,EAAE,CAAC;QAC1B,gBAAW,GAAY,KAAK,CAAC;QAC7B,gBAAW,GAAW,CAAC,CAAC;QAEhC,kDAAkD;QAClC,iBAAY,GAAsB,IAAI,MAAM,EAAa,CAAC;IA0H9E,CAAC;IAxHG;;;OAGG;IACH,aAAa;QACT,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY;QACR,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC7B,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,KAAa,EAAE,IAA4B,EAAE,QAAiB;QACrE,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAE9B,MAAM,KAAK,GAAc;YACrB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,KAAK;YACL,IAAI;YACJ,QAAQ;SACX,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,SAAS;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,KAAa;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,aAAa;QACT,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,YAAY;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAC1B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,UAAU;QAON,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,UAA8B,CAAC;QACnC,IAAI,SAA6B,CAAC;QAElC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC5B,SAAS,EAAE,CAAC;YAChB,CAAC;iBAAM,CAAC;gBACJ,QAAQ,EAAE,CAAC;YACf,CAAC;YAED,IAAI,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,GAAG,UAAU,EAAE,CAAC;gBACvD,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC;YAC7B,CAAC;YACD,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;gBACrD,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;YAC5B,CAAC;QACL,CAAC;QAED,OAAO;YACH,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YAC1B,SAAS;YACT,QAAQ;YACR,UAAU;YACV,SAAS;SACZ,CAAC;IACN,CAAC;CACJ"}

package/dist/audio/export/CDMarkerExporter.d.ts

@@ -0,0 +1,60 @@
+import { CDMarker } from '../../domain/CDMarker';
+/**
+ * CD Marker Exporter
+ *
+ * Generates industry-standard marker/chapter files from CDMarker data.
+ * Supports CUE sheets, cdrdao TOC files, and Nero-style MP4 chapter files.
+ */
+export declare class CDMarkerExporter {
+    /**
+     * Generate a CUE sheet from CD markers.
+     *
+     * CUE format reference: https://en.wikipedia.org/wiki/Cue_sheet_(computing)
+     * Time format: MM:SS:FF where FF = CD frames (75 fps)
+     *
+     * @param markers     Array of CDMarker instances
+     * @param filename    Audio filename referenced in the CUE sheet
+     * @param sampleRate  Sample rate of the audio
+     * @param albumTitle  Optional album title
+     * @param albumPerformer  Optional album performer
+     */
+    static generateCUE(markers: CDMarker[], filename: string, sampleRate: number, albumTitle?: string, albumPerformer?: string): string;
+    /**
+     * Generate a cdrdao-compatible TOC (Table of Contents) file.
+     *
+     * TOC format reference: cdrdao(1) man page
+     *
+     * @param markers     Array of CDMarker instances
+     * @param filename    Audio filename
+     * @param sampleRate  Sample rate of the audio
+     */
+    static generateTOC(markers: CDMarker[], filename: string, sampleRate: number): string;
+    /**
+     * Generate Nero-style MP4 chapter metadata.
+     *
+     * Format: CHAPTERXX=HH:MM:SS.mmm / CHAPTERXXNAME=Title
+     * This format is understood by ffmpeg via -i chapters.txt.
+     *
+     * @param markers     Array of CDMarker instances
+     * @param sampleRate  Sample rate of the audio
+     */
+    static generateMP4Chapters(markers: CDMarker[], sampleRate: number): string;
+    /**
+     * Convert a sample-frame position to CD time format MM:SS:FF.
+     * CD frames run at 75 fps (Red Book standard).
+     *
+     * @param frames      Position in audio sample frames
+     * @param sampleRate  Audio sample rate (e.g. 44100)
+     * @returns           Time string in MM:SS:FF format
+     */
+    static framesToCDTime(frames: number, sampleRate: number): string;
+    /**
+     * Convert a sample-frame position to HH:MM:SS.mmm timestamp.
+     *
+     * @param frames      Position in audio sample frames
+     * @param sampleRate  Audio sample rate
+     * @returns           Time string in HH:MM:SS.mmm format
+     */
+    static framesToTimestamp(frames: number, sampleRate: number): string;
+}
+//# sourceMappingURL=CDMarkerExporter.d.ts.map

package/dist/audio/export/CDMarkerExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CDMarkerExporter.d.ts","sourceRoot":"","sources":["../../../src/audio/export/CDMarkerExporter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD;;;;;GAKG;AACH,qBAAa,gBAAgB;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,CACd,OAAO,EAAE,QAAQ,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,MAAmB,EAC/B,cAAc,GAAE,MAAW,GAC5B,MAAM;IAiCT;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,CACd,OAAO,EAAE,QAAQ,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACnB,MAAM;IA2DT;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,CACtB,OAAO,EAAE,QAAQ,EAAE,EACnB,UAAU,EAAE,MAAM,GACnB,MAAM;IAgBT;;;;;;;OAOG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAajE;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAcvE"}