@waveform-playlist/engine 7.1.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Naomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+import { AudioClip, ClipTrack } from '@waveform-playlist/core';
+
+/**
+ * Clip Operations
+ *
+ * Pure functions for constraining clip movement, boundary trimming,
+ * and splitting clips on a timeline. All positions are in samples (integers).
+ */
+
+/**
+ * Constrain clip movement delta to prevent overlaps with adjacent clips
+ * and going before sample 0.
+ *
+ * @param clip - The clip being dragged
+ * @param deltaSamples - Requested movement in samples (negative = left, positive = right)
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the dragged clip in sortedClips
+ * @returns Constrained delta that prevents overlaps
+ */
+declare function constrainClipDrag(clip: AudioClip, deltaSamples: number, sortedClips: AudioClip[], clipIndex: number): number;
+/**
+ * Constrain boundary trim delta for left or right edge of a clip.
+ *
+ * LEFT boundary: delta moves the left edge (positive = shrink, negative = expand)
+ * - startSample += delta, offsetSamples += delta, durationSamples -= delta
+ *
+ * RIGHT boundary: delta applied to durationSamples (positive = expand, negative = shrink)
+ * - durationSamples += delta
+ *
+ * @param clip - The clip being trimmed
+ * @param deltaSamples - Requested trim delta in samples
+ * @param boundary - Which edge is being trimmed: 'left' or 'right'
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the trimmed clip in sortedClips
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns Constrained delta
+ */
+declare function constrainBoundaryTrim(clip: AudioClip, deltaSamples: number, boundary: 'left' | 'right', sortedClips: AudioClip[], clipIndex: number, minDurationSamples: number): number;
+/**
+ * Snap a split sample position to the nearest pixel boundary.
+ *
+ * @param splitSample - The sample position to snap
+ * @param samplesPerPixel - Current zoom level (samples per pixel)
+ * @returns Snapped sample position
+ */
+declare function calculateSplitPoint(splitSample: number, samplesPerPixel: number): number;
+/**
+ * Split a clip into two clips at the given sample position.
+ *
+ * The left clip retains the original fadeIn; the right clip retains the original fadeOut.
+ * Both clips share the same waveformData reference.
+ * If the clip has a name, suffixes " (1)" and " (2)" are appended.
+ *
+ * @param clip - The clip to split
+ * @param splitSample - The timeline sample position where the split occurs
+ * @returns Object with `left` and `right` AudioClip
+ */
+declare function splitClip(clip: AudioClip, splitSample: number): {
+    left: AudioClip;
+    right: AudioClip;
+};
+/**
+ * Check whether a clip can be split at the given sample position.
+ *
+ * The split point must be strictly inside the clip (not at start or end),
+ * and both resulting clips must meet the minimum duration requirement.
+ *
+ * @param clip - The clip to check
+ * @param sample - The timeline sample position to test
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns true if the split is valid
+ */
+declare function canSplitAt(clip: AudioClip, sample: number, minDurationSamples: number): boolean;
+
+/**
+ * Viewport operations for virtual scrolling.
+ *
+ * Pure math helpers that determine which portion of the timeline
+ * is visible and which canvas chunks need to be mounted.
+ */
+/**
+ * Calculate the visible region with an overscan buffer for virtual scrolling.
+ *
+ * The buffer extends the visible range on both sides so that chunks are
+ * mounted slightly before they scroll into view, preventing flicker.
+ *
+ * @param scrollLeft - Current horizontal scroll position in pixels
+ * @param containerWidth - Width of the scroll container in pixels
+ * @param bufferRatio - Multiplier for buffer size (default 1.5x container width)
+ * @returns Object with visibleStart and visibleEnd in pixels
+ */
+declare function calculateViewportBounds(scrollLeft: number, containerWidth: number, bufferRatio?: number): {
+    visibleStart: number;
+    visibleEnd: number;
+};
+/**
+ * Get an array of chunk indices that overlap the visible viewport.
+ *
+ * Chunks are fixed-width segments of the total timeline width. Only chunks
+ * that intersect [visibleStart, visibleEnd) are included. The last chunk
+ * may be narrower than chunkWidth if totalWidth is not evenly divisible.
+ *
+ * @param totalWidth - Total width of the timeline in pixels
+ * @param chunkWidth - Width of each chunk in pixels
+ * @param visibleStart - Left edge of the visible region in pixels
+ * @param visibleEnd - Right edge of the visible region in pixels
+ * @returns Array of chunk indices (0-based) that are visible
+ */
+declare function getVisibleChunkIndices(totalWidth: number, chunkWidth: number, visibleStart: number, visibleEnd: number): number[];
+/**
+ * Determine whether a scroll change is large enough to warrant
+ * recalculating the viewport and re-rendering chunks.
+ *
+ * Small scroll movements are ignored to avoid excessive recomputation
+ * during smooth scrolling.
+ *
+ * @param oldScrollLeft - Previous scroll position in pixels
+ * @param newScrollLeft - Current scroll position in pixels
+ * @param threshold - Minimum pixel delta to trigger an update (default 100)
+ * @returns true if the scroll delta meets or exceeds the threshold
+ */
+declare function shouldUpdateViewport(oldScrollLeft: number, newScrollLeft: number, threshold?: number): boolean;
+
+/**
+ * Calculate total timeline duration in seconds from all tracks/clips.
+ * Iterates all clips, finds the furthest clip end (startSample + durationSamples),
+ * converts to seconds using each clip's sampleRate.
+ *
+ * @param tracks - Array of clip tracks
+ * @returns Duration in seconds
+ */
+declare function calculateDuration(tracks: ClipTrack[]): number;
+/**
+ * Find the zoom level index closest to a given samplesPerPixel.
+ * Returns exact match if found, otherwise the index whose value is
+ * nearest to the target (by absolute difference).
+ *
+ * @param targetSamplesPerPixel - The samplesPerPixel value to find
+ * @param zoomLevels - Array of available zoom levels (samplesPerPixel values)
+ * @returns Index into the zoomLevels array
+ */
+declare function findClosestZoomIndex(targetSamplesPerPixel: number, zoomLevels: number[]): number;
+/**
+ * Keep viewport centered during zoom changes.
+ * Calculates center time from old zoom, computes new pixel position at new zoom,
+ * and returns new scrollLeft clamped to >= 0.
+ *
+ * @param oldSamplesPerPixel - Previous zoom level
+ * @param newSamplesPerPixel - New zoom level
+ * @param scrollLeft - Current horizontal scroll position
+ * @param containerWidth - Viewport width in pixels
+ * @param sampleRate - Audio sample rate
+ * @param controlWidth - Width of track controls panel (defaults to 0)
+ * @returns New scrollLeft value
+ */
+declare function calculateZoomScrollPosition(oldSamplesPerPixel: number, newSamplesPerPixel: number, scrollLeft: number, containerWidth: number, sampleRate: number, controlWidth?: number): number;
+/**
+ * Clamp a seek position to the valid range [0, duration].
+ *
+ * @param time - Requested seek time in seconds
+ * @param duration - Maximum duration in seconds
+ * @returns Clamped time value
+ */
+declare function clampSeekPosition(time: number, duration: number): number;
+
+/**
+ * Interface for pluggable audio playback adapters.
+ * Implement this to connect PlaylistEngine to any audio backend
+ * (Tone.js, openDAW, HTMLAudioElement, etc.)
+ */
+interface PlayoutAdapter {
+    init(): Promise<void>;
+    setTracks(tracks: ClipTrack[]): void;
+    play(startTime: number, endTime?: number): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    getCurrentTime(): number;
+    isPlaying(): boolean;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    dispose(): void;
+}
+/**
+ * Snapshot of playlist engine state, emitted on every state change.
+ */
+interface EngineState {
+    tracks: ClipTrack[];
+    duration: number;
+    currentTime: number;
+    isPlaying: boolean;
+    samplesPerPixel: number;
+    sampleRate: number;
+    selectedTrackId: string | null;
+    zoomIndex: number;
+    canZoomIn: boolean;
+    canZoomOut: boolean;
+}
+/**
+ * Configuration options for PlaylistEngine constructor.
+ */
+interface PlaylistEngineOptions {
+    adapter?: PlayoutAdapter;
+    sampleRate?: number;
+    samplesPerPixel?: number;
+    zoomLevels?: number[];
+}
+/**
+ * Events emitted by PlaylistEngine.
+ */
+interface EngineEvents {
+    statechange: (state: EngineState) => void;
+    timeupdate: (time: number) => void;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+}
+
+/**
+ * PlaylistEngine — Stateful, framework-agnostic timeline engine.
+ *
+ * Composes pure operations from ./operations with an event emitter
+ * and optional PlayoutAdapter for audio playback delegation.
+ */
+
+type EventName = keyof EngineEvents;
+declare class PlaylistEngine {
+    private _tracks;
+    private _currentTime;
+    private _isPlaying;
+    private _selectedTrackId;
+    private _sampleRate;
+    private _zoomLevels;
+    private _zoomIndex;
+    private _adapter;
+    private _animFrameId;
+    private _disposed;
+    private _listeners;
+    constructor(options?: PlaylistEngineOptions);
+    getState(): EngineState;
+    setTracks(tracks: ClipTrack[]): void;
+    addTrack(track: ClipTrack): void;
+    removeTrack(trackId: string): void;
+    selectTrack(trackId: string | null): void;
+    moveClip(trackId: string, clipId: string, deltaSamples: number): void;
+    splitClip(trackId: string, clipId: string, atSample: number): void;
+    trimClip(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number): void;
+    play(startTime?: number, endTime?: number): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setZoomLevel(samplesPerPixel: number): void;
+    on<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    off<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    dispose(): void;
+    private _emit;
+    private _emitStateChange;
+    private _startTimeUpdateLoop;
+    private _stopTimeUpdateLoop;
+}
+
+export { type EngineEvents, type EngineState, PlaylistEngine, type PlaylistEngineOptions, type PlayoutAdapter, calculateDuration, calculateSplitPoint, calculateViewportBounds, calculateZoomScrollPosition, canSplitAt, clampSeekPosition, constrainBoundaryTrim, constrainClipDrag, findClosestZoomIndex, getVisibleChunkIndices, shouldUpdateViewport, splitClip };

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import { AudioClip, ClipTrack } from '@waveform-playlist/core';
+
+/**
+ * Clip Operations
+ *
+ * Pure functions for constraining clip movement, boundary trimming,
+ * and splitting clips on a timeline. All positions are in samples (integers).
+ */
+
+/**
+ * Constrain clip movement delta to prevent overlaps with adjacent clips
+ * and going before sample 0.
+ *
+ * @param clip - The clip being dragged
+ * @param deltaSamples - Requested movement in samples (negative = left, positive = right)
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the dragged clip in sortedClips
+ * @returns Constrained delta that prevents overlaps
+ */
+declare function constrainClipDrag(clip: AudioClip, deltaSamples: number, sortedClips: AudioClip[], clipIndex: number): number;
+/**
+ * Constrain boundary trim delta for left or right edge of a clip.
+ *
+ * LEFT boundary: delta moves the left edge (positive = shrink, negative = expand)
+ * - startSample += delta, offsetSamples += delta, durationSamples -= delta
+ *
+ * RIGHT boundary: delta applied to durationSamples (positive = expand, negative = shrink)
+ * - durationSamples += delta
+ *
+ * @param clip - The clip being trimmed
+ * @param deltaSamples - Requested trim delta in samples
+ * @param boundary - Which edge is being trimmed: 'left' or 'right'
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the trimmed clip in sortedClips
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns Constrained delta
+ */
+declare function constrainBoundaryTrim(clip: AudioClip, deltaSamples: number, boundary: 'left' | 'right', sortedClips: AudioClip[], clipIndex: number, minDurationSamples: number): number;
+/**
+ * Snap a split sample position to the nearest pixel boundary.
+ *
+ * @param splitSample - The sample position to snap
+ * @param samplesPerPixel - Current zoom level (samples per pixel)
+ * @returns Snapped sample position
+ */
+declare function calculateSplitPoint(splitSample: number, samplesPerPixel: number): number;
+/**
+ * Split a clip into two clips at the given sample position.
+ *
+ * The left clip retains the original fadeIn; the right clip retains the original fadeOut.
+ * Both clips share the same waveformData reference.
+ * If the clip has a name, suffixes " (1)" and " (2)" are appended.
+ *
+ * @param clip - The clip to split
+ * @param splitSample - The timeline sample position where the split occurs
+ * @returns Object with `left` and `right` AudioClip
+ */
+declare function splitClip(clip: AudioClip, splitSample: number): {
+    left: AudioClip;
+    right: AudioClip;
+};
+/**
+ * Check whether a clip can be split at the given sample position.
+ *
+ * The split point must be strictly inside the clip (not at start or end),
+ * and both resulting clips must meet the minimum duration requirement.
+ *
+ * @param clip - The clip to check
+ * @param sample - The timeline sample position to test
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns true if the split is valid
+ */
+declare function canSplitAt(clip: AudioClip, sample: number, minDurationSamples: number): boolean;
+
+/**
+ * Viewport operations for virtual scrolling.
+ *
+ * Pure math helpers that determine which portion of the timeline
+ * is visible and which canvas chunks need to be mounted.
+ */
+/**
+ * Calculate the visible region with an overscan buffer for virtual scrolling.
+ *
+ * The buffer extends the visible range on both sides so that chunks are
+ * mounted slightly before they scroll into view, preventing flicker.
+ *
+ * @param scrollLeft - Current horizontal scroll position in pixels
+ * @param containerWidth - Width of the scroll container in pixels
+ * @param bufferRatio - Multiplier for buffer size (default 1.5x container width)
+ * @returns Object with visibleStart and visibleEnd in pixels
+ */
+declare function calculateViewportBounds(scrollLeft: number, containerWidth: number, bufferRatio?: number): {
+    visibleStart: number;
+    visibleEnd: number;
+};
+/**
+ * Get an array of chunk indices that overlap the visible viewport.
+ *
+ * Chunks are fixed-width segments of the total timeline width. Only chunks
+ * that intersect [visibleStart, visibleEnd) are included. The last chunk
+ * may be narrower than chunkWidth if totalWidth is not evenly divisible.
+ *
+ * @param totalWidth - Total width of the timeline in pixels
+ * @param chunkWidth - Width of each chunk in pixels
+ * @param visibleStart - Left edge of the visible region in pixels
+ * @param visibleEnd - Right edge of the visible region in pixels
+ * @returns Array of chunk indices (0-based) that are visible
+ */
+declare function getVisibleChunkIndices(totalWidth: number, chunkWidth: number, visibleStart: number, visibleEnd: number): number[];
+/**
+ * Determine whether a scroll change is large enough to warrant
+ * recalculating the viewport and re-rendering chunks.
+ *
+ * Small scroll movements are ignored to avoid excessive recomputation
+ * during smooth scrolling.
+ *
+ * @param oldScrollLeft - Previous scroll position in pixels
+ * @param newScrollLeft - Current scroll position in pixels
+ * @param threshold - Minimum pixel delta to trigger an update (default 100)
+ * @returns true if the scroll delta meets or exceeds the threshold
+ */
+declare function shouldUpdateViewport(oldScrollLeft: number, newScrollLeft: number, threshold?: number): boolean;
+
+/**
+ * Calculate total timeline duration in seconds from all tracks/clips.
+ * Iterates all clips, finds the furthest clip end (startSample + durationSamples),
+ * converts to seconds using each clip's sampleRate.
+ *
+ * @param tracks - Array of clip tracks
+ * @returns Duration in seconds
+ */
+declare function calculateDuration(tracks: ClipTrack[]): number;
+/**
+ * Find the zoom level index closest to a given samplesPerPixel.
+ * Returns exact match if found, otherwise the index whose value is
+ * nearest to the target (by absolute difference).
+ *
+ * @param targetSamplesPerPixel - The samplesPerPixel value to find
+ * @param zoomLevels - Array of available zoom levels (samplesPerPixel values)
+ * @returns Index into the zoomLevels array
+ */
+declare function findClosestZoomIndex(targetSamplesPerPixel: number, zoomLevels: number[]): number;
+/**
+ * Keep viewport centered during zoom changes.
+ * Calculates center time from old zoom, computes new pixel position at new zoom,
+ * and returns new scrollLeft clamped to >= 0.
+ *
+ * @param oldSamplesPerPixel - Previous zoom level
+ * @param newSamplesPerPixel - New zoom level
+ * @param scrollLeft - Current horizontal scroll position
+ * @param containerWidth - Viewport width in pixels
+ * @param sampleRate - Audio sample rate
+ * @param controlWidth - Width of track controls panel (defaults to 0)
+ * @returns New scrollLeft value
+ */
+declare function calculateZoomScrollPosition(oldSamplesPerPixel: number, newSamplesPerPixel: number, scrollLeft: number, containerWidth: number, sampleRate: number, controlWidth?: number): number;
+/**
+ * Clamp a seek position to the valid range [0, duration].
+ *
+ * @param time - Requested seek time in seconds
+ * @param duration - Maximum duration in seconds
+ * @returns Clamped time value
+ */
+declare function clampSeekPosition(time: number, duration: number): number;
+
+/**
+ * Interface for pluggable audio playback adapters.
+ * Implement this to connect PlaylistEngine to any audio backend
+ * (Tone.js, openDAW, HTMLAudioElement, etc.)
+ */
+interface PlayoutAdapter {
+    init(): Promise<void>;
+    setTracks(tracks: ClipTrack[]): void;
+    play(startTime: number, endTime?: number): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    getCurrentTime(): number;
+    isPlaying(): boolean;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    dispose(): void;
+}
+/**
+ * Snapshot of playlist engine state, emitted on every state change.
+ */
+interface EngineState {
+    tracks: ClipTrack[];
+    duration: number;
+    currentTime: number;
+    isPlaying: boolean;
+    samplesPerPixel: number;
+    sampleRate: number;
+    selectedTrackId: string | null;
+    zoomIndex: number;
+    canZoomIn: boolean;
+    canZoomOut: boolean;
+}
+/**
+ * Configuration options for PlaylistEngine constructor.
+ */
+interface PlaylistEngineOptions {
+    adapter?: PlayoutAdapter;
+    sampleRate?: number;
+    samplesPerPixel?: number;
+    zoomLevels?: number[];
+}
+/**
+ * Events emitted by PlaylistEngine.
+ */
+interface EngineEvents {
+    statechange: (state: EngineState) => void;
+    timeupdate: (time: number) => void;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+}
+
+/**
+ * PlaylistEngine — Stateful, framework-agnostic timeline engine.
+ *
+ * Composes pure operations from ./operations with an event emitter
+ * and optional PlayoutAdapter for audio playback delegation.
+ */
+
+type EventName = keyof EngineEvents;
+declare class PlaylistEngine {
+    private _tracks;
+    private _currentTime;
+    private _isPlaying;
+    private _selectedTrackId;
+    private _sampleRate;
+    private _zoomLevels;
+    private _zoomIndex;
+    private _adapter;
+    private _animFrameId;
+    private _disposed;
+    private _listeners;
+    constructor(options?: PlaylistEngineOptions);
+    getState(): EngineState;
+    setTracks(tracks: ClipTrack[]): void;
+    addTrack(track: ClipTrack): void;
+    removeTrack(trackId: string): void;
+    selectTrack(trackId: string | null): void;
+    moveClip(trackId: string, clipId: string, deltaSamples: number): void;
+    splitClip(trackId: string, clipId: string, atSample: number): void;
+    trimClip(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number): void;
+    play(startTime?: number, endTime?: number): Promise<void>;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setZoomLevel(samplesPerPixel: number): void;
+    on<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    off<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    dispose(): void;
+    private _emit;
+    private _emitStateChange;
+    private _startTimeUpdateLoop;
+    private _stopTimeUpdateLoop;
+}
+
+export { type EngineEvents, type EngineState, PlaylistEngine, type PlaylistEngineOptions, type PlayoutAdapter, calculateDuration, calculateSplitPoint, calculateViewportBounds, calculateZoomScrollPosition, canSplitAt, clampSeekPosition, constrainBoundaryTrim, constrainClipDrag, findClosestZoomIndex, getVisibleChunkIndices, shouldUpdateViewport, splitClip };