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

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { default as default_3 } from 'waveform-data';
 import { DragEndEvent } from '@dnd-kit/core';
 import { Fade as Fade_2 } from '@waveform-playlist/core';
 import { Gain } from 'tone';
+import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
 import { MutableRefObject } from 'react';
 import react__default from 'react';
 import { ReactNode } from 'react';
@@ -50,7 +51,7 @@ declare interface AnnotationActionOptions {
     [key: string]: unknown;
 }
 
-declare interface AnnotationData {
+export declare interface AnnotationData {
     id: string;
     start: number;
     end: number;
@@ -58,24 +59,56 @@ declare interface AnnotationData {
     language?: string;
 }
 
+/**
+ * Shared annotation types used across Waveform components
+ */
+/**
+ * Base annotation data structure
+ */
+declare interface AnnotationData_2 {
+    id: string;
+    start: number;
+    end: number;
+    lines: string[];
+}
+
 /**
  * Represents a single audio clip on the timeline
  *
  * 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 +139,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;
@@ -380,6 +424,21 @@ export declare const FastForwardButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Custom function to generate the label shown on annotation boxes in the waveform.
+ * Receives the annotation data and its index in the list, returns a string label.
+ * Default behavior: displays annotation.id
+ *
+ * @example
+ * // Show sequence numbers
+ * getAnnotationBoxLabel={(annotation, index) => String(index + 1)}
+ *
+ * @example
+ * // Show formatted time
+ * getAnnotationBoxLabel={(annotation) => formatTime(annotation.start)}
+ */
+export declare type GetAnnotationBoxLabelFn = (annotation: AnnotationData_2, index: number) => string;
+
 export declare const getEffectDefinition: (id: string) => EffectDefinition | undefined;
 
 export declare const getEffectsByCategory: (category: EffectDefinition["category"]) => EffectDefinition[];
@@ -500,12 +559,165 @@ export declare interface MasterVolumeControls {
     setMasterVolume: (volume: number) => void;
 }
 
+export declare interface MediaElementAnimationContextValue {
+    isPlaying: boolean;
+    currentTime: number;
+    currentTimeRef: default_2.RefObject<number>;
+}
+
+export declare interface MediaElementControlsContextValue {
+    play: (startTime?: number) => void;
+    pause: () => void;
+    stop: () => void;
+    seekTo: (time: number) => void;
+    setPlaybackRate: (rate: number) => void;
+    setContinuousPlay: (enabled: boolean) => void;
+    setAnnotations: (annotations: AnnotationData[]) => void;
+    setActiveAnnotationId: (id: string | null) => void;
+    setAutomaticScroll: (enabled: boolean) => void;
+    setScrollContainer: (element: HTMLDivElement | null) => void;
+    scrollContainerRef: default_2.RefObject<HTMLDivElement | null>;
+}
+
+export declare interface MediaElementDataContextValue {
+    duration: number;
+    peaksDataArray: TrackClipPeaks[];
+    sampleRate: number;
+    waveHeight: number;
+    timeScaleHeight: number;
+    samplesPerPixel: number;
+    playoutRef: default_2.RefObject<MediaElementPlayout | null>;
+    controls: {
+        show: boolean;
+        width: number;
+    };
+    barWidth: number;
+    barGap: number;
+    progressBarWidth: number;
+}
+
+/**
+ * MediaElementPlaylistProvider
+ *
+ * A simplified playlist provider for single-track playback using HTMLAudioElement.
+ * Key features:
+ * - Pitch-preserving playback rate (0.5x - 2.0x)
+ * - Pre-computed peaks visualization (no AudioBuffer needed)
+ * - Simpler API than full WaveformPlaylistProvider
+ *
+ * Use this for:
+ * - Language learning apps (speed control)
+ * - Podcast players
+ * - Single-track audio viewers
+ *
+ * For multi-track editing, use WaveformPlaylistProvider instead.
+ */
+export declare const MediaElementPlaylistProvider: default_2.FC<MediaElementPlaylistProviderProps>;
+
+declare interface MediaElementPlaylistProviderProps {
+    /** Single track configuration with source URL and waveform data */
+    track: MediaElementTrackConfig;
+    /** Initial samples per pixel (zoom level) */
+    samplesPerPixel?: number;
+    /** Height of each waveform track */
+    waveHeight?: number;
+    /** Show timescale */
+    timescale?: boolean;
+    /** Initial playback rate (0.5 to 2.0) */
+    playbackRate?: number;
+    /** Enable automatic scroll to keep playhead centered */
+    automaticScroll?: boolean;
+    /** Theme configuration */
+    theme?: Partial<WaveformPlaylistTheme>;
+    /** Track controls configuration */
+    controls?: {
+        show: boolean;
+        width: number;
+    };
+    /** Annotations */
+    annotationList?: {
+        annotations?: any[];
+        isContinuousPlay?: boolean;
+    };
+    /** Width of waveform bars */
+    barWidth?: number;
+    /** Gap between waveform bars */
+    barGap?: number;
+    /** Width of progress bars */
+    progressBarWidth?: number;
+    /** Callback when audio is ready */
+    onReady?: () => void;
+    children: ReactNode;
+}
+
+export declare interface MediaElementStateContextValue {
+    continuousPlay: boolean;
+    annotations: AnnotationData[];
+    activeAnnotationId: string | null;
+    playbackRate: number;
+    isAutomaticScroll: boolean;
+}
+
+export declare interface MediaElementTrackConfig {
+    /** Audio source URL or Blob URL */
+    source: string;
+    /** Pre-computed waveform data (required for visualization) */
+    waveformData: WaveformDataObject;
+    /** Track name for display */
+    name?: string;
+}
+
+/**
+ * Simplified Waveform component for MediaElementPlaylistProvider
+ *
+ * This is a stripped-down version of Waveform that works with the
+ * MediaElement context. It supports:
+ * - Single track visualization
+ * - Click to seek
+ * - Annotation display and click-to-play
+ * - Playhead animation
+ *
+ * For multi-track editing, use the full Waveform with WaveformPlaylistProvider.
+ */
+export declare const MediaElementWaveform: default_2.FC<MediaElementWaveformProps>;
+
+export declare interface MediaElementWaveformProps {
+    /** Height in pixels for the annotation text list */
+    annotationTextHeight?: number;
+    /** Custom function to generate the label shown on annotation boxes */
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
+    /**
+     * Custom render function for annotation items in the text list.
+     * When provided, completely replaces the default annotation item rendering.
+     * Use this to customize the appearance of each annotation (e.g., add furigana).
+     */
+    renderAnnotationItem?: (props: RenderAnnotationItemProps) => default_2.ReactNode;
+    /** Whether annotation boundaries can be edited by dragging. Defaults to false. */
+    editable?: boolean;
+    /**
+     * Callback when annotations are updated (e.g., boundaries dragged).
+     * Called with the full updated annotations array.
+     */
+    onAnnotationUpdate?: OnAnnotationUpdateFn;
+    /** Where to position the active annotation when auto-scrolling: 'center', 'start', 'end', or 'nearest'. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
+    /** Which scrollable containers to scroll: 'nearest' (only the annotation list) or 'all' (including viewport). Defaults to 'nearest'. */
+    scrollActiveContainer?: 'nearest' | 'all';
+    className?: string;
+}
+
 declare interface MicrophoneDevice {
     deviceId: string;
     label: string;
     groupId: string;
 }
 
+/**
+ * Callback when annotations are updated (e.g., boundaries dragged).
+ * Called with the full updated annotations array.
+ */
+export declare type OnAnnotationUpdateFn = (annotations: AnnotationData_2[]) => void;
+
 /**
  * Effect definitions for all available Tone.js effects
  * Each effect has parameters with min/max/default values for UI controls
@@ -643,6 +855,17 @@ declare interface PlaylistStateContextValue {
     loopEnd: number;
 }
 
+/**
+ * Props passed to the renderAnnotationItem function for custom rendering
+ */
+export declare interface RenderAnnotationItemProps {
+    annotation: AnnotationData;
+    index: number;
+    isActive: boolean;
+    onClick: () => void;
+    formatTime: (seconds: number) => string;
+}
+
 /**
  * Type for custom playhead render functions.
  * Receives position, color, and animation refs for smooth 60fps animation.
@@ -968,7 +1191,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 +1202,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)
  *
@@ -1249,6 +1496,14 @@ declare interface UseMasterVolumeProps {
     onVolumeChange?: (volume: number) => void;
 }
 
+export declare const useMediaElementAnimation: () => MediaElementAnimationContextValue;
+
+export declare const useMediaElementControls: () => MediaElementControlsContextValue;
+
+export declare const useMediaElementData: () => MediaElementDataContextValue;
+
+export declare const useMediaElementState: () => MediaElementStateContextValue;
+
 export declare const usePlaybackAnimation: () => PlaybackAnimationContextValue;
 
 /**
@@ -1599,6 +1854,21 @@ export declare interface WaveformProps {
     annotationControls?: AnnotationAction[];
     annotationListConfig?: AnnotationActionOptions;
     annotationTextHeight?: number;
+    /**
+     * Custom render function for annotation items in the text list.
+     * Use this to completely customize how each annotation is displayed.
+     */
+    renderAnnotationItem?: (props: RenderAnnotationItemProps) => ReactNode;
+    /**
+     * Custom function to generate the label shown on annotation boxes in the waveform.
+     * Receives the annotation data and its index, returns a string label.
+     * Default: annotation.id
+     */
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
+    /** Where to position the active annotation when auto-scrolling: 'center', 'start', 'end', or 'nearest'. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
+    /** Which scrollable containers to scroll: 'nearest' (only the annotation list) or 'all' (including viewport). Defaults to 'nearest'. */
+    scrollActiveContainer?: 'nearest' | 'all';
     className?: string;
     showClipHeaders?: boolean;
     interactiveClips?: boolean;