@waveform-playlist/browser 5.0.0-alpha.0 → 5.0.0-alpha.10

package/dist/index.d.ts

@@ -64,18 +64,37 @@ declare interface AnnotationData {
  * IMPORTANT: All positions/durations are stored as SAMPLE COUNTS (integers)
  * to avoid floating-point precision errors. Convert to seconds only when
  * needed for playback using: seconds = samples / sampleRate
+ *
+ * Clips can be created with just waveformData (for instant visual rendering)
+ * and have audioBuffer added later when audio finishes loading.
  */
-declare interface AudioClip {
+export declare interface AudioClip {
     /** Unique identifier for this clip */
     id: string;
-    /** The audio buffer containing the audio data */
-    audioBuffer: AudioBuffer;
+    /**
+     * The audio buffer containing the audio data.
+     * Optional for peaks-first rendering - can be added later.
+     * Required for playback and editing operations.
+     */
+    audioBuffer?: AudioBuffer;
     /** Position on timeline where this clip starts (in samples at timeline sampleRate) */
     startSample: number;
     /** Duration of this clip (in samples) - how much of the audio buffer to play */
     durationSamples: number;
     /** Offset into the audio buffer where playback starts (in samples) - the "trim start" point */
     offsetSamples: number;
+    /**
+     * Sample rate for this clip's audio.
+     * Required when audioBuffer is not provided (for peaks-first rendering).
+     * When audioBuffer is present, this should match audioBuffer.sampleRate.
+     */
+    sampleRate: number;
+    /**
+     * Total duration of the source audio in samples.
+     * Required when audioBuffer is not provided (for trim bounds calculation).
+     * When audioBuffer is present, this should equal audioBuffer.length.
+     */
+    sourceDurationSamples: number;
     /** Optional fade in effect */
     fadeIn?: Fade;
     /** Optional fade out effect */
@@ -86,6 +105,13 @@ declare interface AudioClip {
     name?: string;
     /** Optional color for visual distinction */
     color?: string;
+    /**
+     * Pre-computed waveform data from waveform-data.js library.
+     * When provided, the library will use this instead of computing peaks from the audioBuffer.
+     * Supports resampling to different zoom levels and slicing for clip trimming.
+     * Load with: `const waveformData = await loadWaveformData('/path/to/peaks.dat')`
+     */
+    waveformData?: WaveformDataObject;
 }
 
 /**
@@ -99,9 +125,20 @@ export declare const AudioPosition: default_2.FC<{
 
 /**
  * Configuration for a single audio track to load
+ *
+ * Audio can be provided in three ways:
+ * 1. `src` - URL to fetch and decode (standard loading)
+ * 2. `audioBuffer` - Pre-loaded AudioBuffer (skip fetch/decode)
+ * 3. `waveformData` only - Peaks-first rendering (audio loads later)
+ *
+ * For peaks-first rendering, just provide `waveformData` - the sample rate
+ * and duration are derived from the waveform data automatically.
  */
 export declare interface AudioTrackConfig {
-    src: string;
+    /** URL to audio file - used if audioBuffer not provided */
+    src?: string;
+    /** Pre-loaded AudioBuffer - skips fetch/decode if provided */
+    audioBuffer?: AudioBuffer;
     name?: string;
     muted?: boolean;
     soloed?: boolean;
@@ -114,6 +151,7 @@ export declare interface AudioTrackConfig {
     offset?: number;
     fadeIn?: Fade;
     fadeOut?: Fade;
+    waveformData?: WaveformDataObject;
 }
 
 /**
@@ -152,7 +190,7 @@ declare interface ClipPeaks {
 /**
  * Represents a track containing multiple audio clips
  */
-declare interface ClipTrack {
+export declare interface ClipTrack {
     /** Unique identifier for this track */
     id: string;
     /** Display name for this track */
@@ -206,6 +244,37 @@ export declare const DownloadAnnotationsButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Hook for configuring @dnd-kit sensors for clip dragging
+ *
+ * Provides consistent drag activation behavior across all examples.
+ * Supports both desktop (immediate feedback) and mobile (delay-based) interactions.
+ */
+declare interface DragSensorOptions {
+    /**
+     * Enable mobile-optimized touch handling with delay-based activation.
+     * When true, uses TouchSensor with 250ms delay to distinguish drag from scroll.
+     * When false (default), uses PointerSensor with 1px activation for immediate feedback.
+     */
+    touchOptimized?: boolean;
+    /**
+     * Delay in milliseconds before touch drag activates (only when touchOptimized is true).
+     * Default: 250ms - long enough to distinguish from scroll intent
+     */
+    touchDelay?: number;
+    /**
+     * Distance tolerance during touch delay (only when touchOptimized is true).
+     * If finger moves more than this during delay, drag is cancelled.
+     * Default: 5px - allows slight finger movement
+     */
+    touchTolerance?: number;
+    /**
+     * Distance in pixels before mouse drag activates.
+     * Default: 1px for immediate feedback on desktop
+     */
+    mouseDistance?: number;
+}
+
 /**
  * Editable annotations checkbox that uses the playlist context
  * Uses split contexts to avoid re-rendering during animation
@@ -328,7 +397,7 @@ export declare interface ExportWavButtonProps {
 /**
  * Simple fade configuration
  */
-declare interface Fade {
+export declare interface Fade {
     /** Duration of the fade in seconds */
     duration: number;
     /** Type of fade curve (default: 'linear') */
@@ -445,6 +514,10 @@ export declare function loadPeaksFromWaveformData(src: string, channelIndex?: nu
  */
 export declare function loadWaveformData(src: string): Promise<default_3>;
 
+export declare const LoopButton: default_2.FC<{
+    className?: string;
+}>;
+
 /**
  * Master volume control that uses the playlist context
  */
@@ -553,6 +626,10 @@ declare interface PlaylistControlsContextValue {
     setAnnotationsEditable: (enabled: boolean) => void;
     setAnnotations: (annotations: AnnotationData[]) => void;
     setActiveAnnotationId: (id: string | null) => void;
+    setLoopEnabled: (enabled: boolean) => void;
+    setLoopRegion: (start: number, end: number) => void;
+    setLoopRegionFromSelection: () => void;
+    clearLoopRegion: () => void;
 }
 
 declare interface PlaylistDataContextValue {
@@ -586,11 +663,14 @@ declare interface PlaylistStateContextValue {
     linkEndpoints: boolean;
     annotationsEditable: boolean;
     isAutomaticScroll: boolean;
+    isLoopEnabled: boolean;
     annotations: AnnotationData[];
     activeAnnotationId: string | null;
     selectionStart: number;
     selectionEnd: number;
     selectedTrackId: string | null;
+    loopStart: number;
+    loopEnd: number;
 }
 
 /**
@@ -611,6 +691,10 @@ export declare const SelectionTimeInputs: default_2.FC<{
     className?: string;
 }>;
 
+export declare const SetLoopRegionButton: default_2.FC<{
+    className?: string;
+}>;
+
 export declare const SkipBackwardButton: default_2.FC<{
     skipAmount?: number;
     className?: string;
@@ -660,6 +744,11 @@ declare class TonePlayout {
     private gainToDb;
     init(): Promise<void>;
     addTrack(trackOptions: ToneTrackOptions): ToneTrack;
+    /**
+     * Apply solo muting after all tracks have been added.
+     * Call this after adding all tracks to ensure solo logic is applied correctly.
+     */
+    applyInitialSoloState(): void;
     removeTrack(trackId: string): void;
     getTrack(trackId: string): ToneTrack | undefined;
     play(when?: number, offset?: number, duration?: number): void;
@@ -735,17 +824,6 @@ declare type TrackClipPeaks = ClipPeaks[];
 
 export declare type TrackEffectsFunction = (graphEnd: Gain, masterGainNode: ToneAudioNode, isOffline: boolean) => void | (() => void);
 
-/**
- * Clip-Based Model Types
- *
- * These types support a professional multi-track editing model where:
- * - Each track can contain multiple audio clips
- * - Clips can be positioned anywhere on the timeline
- * - Clips have independent trim points (offset/duration)
- * - Gaps between clips are silent
- * - Clips can overlap (for crossfades)
- */
-
 /**
  * Generic effects function type for track-level audio processing.
  *
@@ -920,7 +998,8 @@ declare interface UseAnnotationKeyboardControlsOptions {
  * with a single clip per track. Supports custom positioning for multi-clip arrangements.
  *
  * @param configs - Array of audio track configurations
- * @returns Object with tracks array and loading state
+ * @param options - Optional configuration for loading behavior
+ * @returns Object with tracks array, loading state, and progress info
  *
  * @example
  * ```typescript
@@ -930,25 +1009,48 @@ declare interface UseAnnotationKeyboardControlsOptions {
  *   { src: 'audio/drums.mp3', name: 'Drums' },
  * ]);
  *
- * // Multi-clip positioning (clips at different times with gaps)
- * const { tracks, loading, error } = useAudioTracks([
- *   { src: 'audio/guitar.mp3', name: 'Guitar Clip 1', startTime: 0, duration: 3 },
- *   { src: 'audio/guitar.mp3', name: 'Guitar Clip 2', startTime: 5, duration: 3, offset: 5 },
- *   { src: 'audio/vocals.mp3', name: 'Vocals', startTime: 2, duration: 4 },
+ * // Progressive loading (tracks appear as they load)
+ * const { tracks, loading, loadedCount, totalCount } = useAudioTracks(
+ *   [{ src: 'audio/vocals.mp3' }, { src: 'audio/drums.mp3' }],
+ *   { progressive: true }
+ * );
+ *
+ * // Pre-loaded AudioBuffer (skip fetch/decode)
+ * const { tracks } = useAudioTracks([
+ *   { audioBuffer: myPreloadedBuffer, name: 'Pre-loaded' },
  * ]);
  *
- * if (loading) return <div>Loading...</div>;
+ * // Peaks-first rendering (instant visual, audio loads later)
+ * const { tracks } = useAudioTracks([
+ *   { waveformData: preloadedPeaks, name: 'Peaks Only' },  // Renders immediately
+ * ]);
+ *
+ * if (loading) return <div>Loading {loadedCount}/{totalCount}...</div>;
  * if (error) return <div>Error: {error}</div>;
  *
  * return <WaveformPlaylistProvider tracks={tracks}>...</WaveformPlaylistProvider>;
  * ```
  */
-export declare function useAudioTracks(configs: AudioTrackConfig[]): {
+export declare function useAudioTracks(configs: AudioTrackConfig[], options?: UseAudioTracksOptions): {
     tracks: ClipTrack[];
     loading: boolean;
     error: string | null;
+    loadedCount: number;
+    totalCount: number;
 };
 
+/**
+ * Options for useAudioTracks hook
+ */
+declare interface UseAudioTracksOptions {
+    /**
+     * When true, tracks are added to the playlist progressively as they load,
+     * rather than waiting for all tracks to finish loading.
+     * Default: false (wait for all tracks)
+     */
+    progressive?: boolean;
+}
+
 /**
  * Custom hook for handling clip drag operations (movement and trimming)
  *
@@ -1045,17 +1147,29 @@ declare interface UseClipSplittingResult {
     splitClipAt: (trackIndex: number, clipIndex: number, splitTime: number) => boolean;
 }
 
-/**
- * Hook for configuring @dnd-kit sensors for clip dragging
- *
- * Provides consistent drag activation behavior across all examples
- */
 /**
  * Returns configured sensors for @dnd-kit drag operations
  *
- * @returns Configured sensors with 1px activation distance for immediate feedback
+ * @param options - Configuration options for drag sensors
+ * @returns Configured sensors appropriate for the interaction mode
+ *
+ * @example
+ * // Desktop-optimized (default)
+ * const sensors = useDragSensors();
+ *
+ * @example
+ * // Mobile-optimized with touch delay
+ * const sensors = useDragSensors({ touchOptimized: true });
+ *
+ * @example
+ * // Custom touch settings
+ * const sensors = useDragSensors({
+ *   touchOptimized: true,
+ *   touchDelay: 300,
+ *   touchTolerance: 8
+ * });
  */
-export declare function useDragSensors(): SensorDescriptor<SensorOptions>[];
+export declare function useDragSensors(options?: DragSensorOptions): SensorDescriptor<SensorOptions>[];
 
 /**
  * Hook for managing a dynamic chain of audio effects with real-time parameter updates
@@ -1310,6 +1424,56 @@ export declare const Waveform: default_2.FC<WaveformProps>;
  */
 declare type WaveformColor = string | WaveformGradient;
 
+/**
+ * Clip-Based Model Types
+ *
+ * These types support a professional multi-track editing model where:
+ * - Each track can contain multiple audio clips
+ * - Clips can be positioned anywhere on the timeline
+ * - Clips have independent trim points (offset/duration)
+ * - Gaps between clips are silent
+ * - Clips can overlap (for crossfades)
+ */
+
+/**
+ * WaveformData object from waveform-data.js library.
+ * Supports resample() and slice() for dynamic zoom levels.
+ * See: https://github.com/bbc/waveform-data.js
+ */
+declare interface WaveformDataObject {
+    /** Sample rate of the original audio */
+    readonly sample_rate: number;
+    /** Number of audio samples per pixel */
+    readonly scale: number;
+    /** Length of waveform data in pixels */
+    readonly length: number;
+    /** Bit depth (8 or 16) */
+    readonly bits: number;
+    /** Duration in seconds */
+    readonly duration: number;
+    /** Number of channels */
+    readonly channels: number;
+    /** Get channel data */
+    channel: (index: number) => {
+        min_array: () => number[];
+        max_array: () => number[];
+    };
+    /** Resample to different scale */
+    resample: (options: {
+        scale: number;
+    } | {
+        width: number;
+    }) => WaveformDataObject;
+    /** Slice a portion of the waveform */
+    slice: (options: {
+        startTime: number;
+        endTime: number;
+    } | {
+        startIndex: number;
+        endIndex: number;
+    }) => WaveformDataObject;
+}
+
 /**
  * Convert WaveformData to our internal Peaks format
  *
@@ -1442,6 +1606,8 @@ declare interface WaveformPlaylistTheme {
     timescaleBackgroundColor: string;
     playheadColor: string;
     selectionColor: string;
+    loopRegionColor: string;
+    loopMarkerColor: string;
     clipHeaderBackgroundColor: string;
     clipHeaderBorderColor: string;
     clipHeaderTextColor: string;
@@ -1491,6 +1657,12 @@ export declare interface WaveformProps {
     showClipHeaders?: boolean;
     interactiveClips?: boolean;
     showFades?: boolean;
+    /**
+     * Enable mobile-optimized touch interactions.
+     * When true, increases touch target sizes for clip boundaries.
+     * Use with useDragSensors({ touchOptimized: true }) for best results.
+     */
+    touchOptimized?: boolean;
     recordingState?: {
         isRecording: boolean;
         trackId: string;