@waveform-playlist/browser 5.0.0-alpha.8 → 5.0.0-alpha.9

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.
  */
 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 */
@@ -106,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;
@@ -968,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
@@ -978,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)
  *