@waveform-playlist/browser 5.3.1 → 6.0.0

package/dist/index.d.ts

@@ -25,14 +25,9 @@ export declare interface ActiveEffect {
     bypassed: boolean;
 }
 
-declare interface Annotation$1 {
-    id: string;
-    start: number;
-    end: number;
-    lines: string[];
-    lang?: string;
-}
-
+/**
+ * An action control shown on annotation items (e.g., delete, split).
+ */
 declare interface AnnotationAction {
     class?: string;
     text?: string;
@@ -41,7 +36,8 @@ declare interface AnnotationAction {
 }
 
 /**
- * Configuration options passed to annotation action handlers
+ * Configuration options passed to annotation action handlers.
+ * Used by both browser and annotations packages.
  */
 declare interface AnnotationActionOptions {
     /** Whether annotation endpoints are linked (moving one endpoint moves the other) */
@@ -52,6 +48,12 @@ declare interface AnnotationActionOptions {
     [key: string]: unknown;
 }
 
+/**
+ * Shared annotation types used across waveform-playlist packages
+ */
+/**
+ * Base annotation data structure
+ */
 export declare interface AnnotationData {
     id: string;
     start: number;
@@ -61,18 +63,41 @@ export declare interface AnnotationData {
 }
 
 /**
- * Shared annotation types used across Waveform components
- */
-/**
- * Base annotation data structure
+ * Interface for annotation integration provided by @waveform-playlist/annotations.
+ *
+ * The browser package defines what it needs, and the optional annotations package
+ * provides it via <AnnotationProvider>.
  */
-declare interface AnnotationData_2 {
-    id: string;
-    start: number;
-    end: number;
-    lines: string[];
+export declare interface AnnotationIntegration {
+    parseAeneas: (data: unknown) => AnnotationData;
+    serializeAeneas: (annotation: AnnotationData) => unknown;
+    AnnotationText: React.ComponentType<any>;
+    AnnotationBox: React.ComponentType<any>;
+    AnnotationBoxesWrapper: React.ComponentType<any>;
+    ContinuousPlayCheckbox: React.ComponentType<{
+        checked: boolean;
+        onChange: (checked: boolean) => void;
+        className?: string;
+    }>;
+    LinkEndpointsCheckbox: React.ComponentType<{
+        checked: boolean;
+        onChange: (checked: boolean) => void;
+        className?: string;
+    }>;
+    EditableCheckbox: React.ComponentType<{
+        checked: boolean;
+        onChange: (checked: boolean) => void;
+        className?: string;
+    }>;
+    DownloadAnnotationsButton: React.ComponentType<{
+        annotations: AnnotationData[];
+        filename?: string;
+        className?: string;
+    }>;
 }
 
+export declare const AnnotationIntegrationProvider: Provider<AnnotationIntegration | null>;
+
 /**
  * Represents a single audio clip on the timeline
  *
@@ -250,8 +275,8 @@ declare type ColorMapName = 'viridis' | 'magma' | 'inferno' | 'grayscale' | 'igr
 declare type ColorMapValue = ColorMapName | ColorMapEntry[];
 
 /**
- * Continuous play checkbox that uses the playlist context
- * Uses split contexts to avoid re-rendering during animation
+ * Continuous play checkbox that uses the playlist context.
+ * Must be used within <AnnotationProvider>.
  */
 export declare const ContinuousPlayCheckbox: default_2.FC<{
     className?: string;
@@ -272,8 +297,8 @@ export declare function createEffectChain(effects: EffectInstance[]): {
 export declare function createEffectInstance(definition: EffectDefinition, initialParams?: Record<string, number | string | boolean>): EffectInstance;
 
 /**
- * Download annotations button that uses the playlist context
- * Uses split contexts to avoid re-rendering during animation
+ * Download annotations button that uses the playlist context.
+ * Must be used within <AnnotationProvider>.
  */
 export declare const DownloadAnnotationsButton: default_2.FC<{
     filename?: string;
@@ -312,8 +337,8 @@ declare interface DragSensorOptions {
 }
 
 /**
- * Editable annotations checkbox that uses the playlist context
- * Uses split contexts to avoid re-rendering during animation
+ * Editable annotations checkbox that uses the playlist context.
+ * Must be used within <AnnotationProvider>.
  */
 export declare const EditableCheckbox: default_2.FC<{
     className?: string;
@@ -458,16 +483,8 @@ declare type FFTSize = 256 | 512 | 1024 | 2048 | 4096 | 8192;
  * 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 type GetAnnotationBoxLabelFn = (annotation: AnnotationData, index: number) => string;
 
 export declare const getEffectDefinition: (id: string) => EffectDefinition | undefined;
 
@@ -509,29 +526,6 @@ declare interface GradientStop {
     color: string;
 }
 
-export declare interface IntegratedRecordingOptions {
-    /**
-     * Current playback/cursor position in seconds
-     * Recording will start from max(currentTime, lastClipEndTime)
-     */
-    currentTime?: number;
-    /**
-     * MediaTrackConstraints for audio recording
-     * These will override the recording-optimized defaults (echo cancellation off, low latency)
-     */
-    audioConstraints?: MediaTrackConstraints;
-    /**
-     * Number of channels to record (1 = mono, 2 = stereo)
-     * Default: 1 (mono)
-     */
-    channelCount?: number;
-    /**
-     * Samples per pixel for peak generation
-     * Default: 1024
-     */
-    samplesPerPixel?: number;
-}
-
 declare interface KeyboardShortcut {
     key: string;
     ctrlKey?: boolean;
@@ -544,8 +538,8 @@ declare interface KeyboardShortcut {
 }
 
 /**
- * Link endpoints checkbox that uses the playlist context
- * Uses split contexts to avoid re-rendering during animation
+ * Link endpoints checkbox that uses the playlist context.
+ * Must be used within <AnnotationProvider>.
  */
 export declare const LinkEndpointsCheckbox: default_2.FC<{
     className?: string;
@@ -598,8 +592,8 @@ export declare interface MediaElementAnimationContextValue {
 /**
  * Standalone annotation text list component for MediaElementPlaylistProvider.
  *
- * Reads annotations and playback state from context and renders AnnotationText
- * unconditionally (even when annotations are empty).
+ * Requires @waveform-playlist/annotations with AnnotationProvider.
+ * Throws if used without `<AnnotationProvider>` wrapping the component tree.
  */
 export declare const MediaElementAnnotationList: default_2.FC<MediaElementAnnotationListProps>;
 
@@ -808,17 +802,11 @@ export declare interface MediaElementWaveformProps {
     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;
+export declare type OnAnnotationUpdateFn = (annotations: AnnotationData[]) => void;
 
 /**
  * Effect definitions for all available Tone.js effects
@@ -888,8 +876,8 @@ declare interface PlayheadProps {
 /**
  * Standalone annotation text list component for WaveformPlaylistProvider (WebAudio).
  *
- * Reads annotations and playback state from context and renders AnnotationText
- * unconditionally (even when annotations are empty).
+ * Requires @waveform-playlist/annotations with AnnotationProvider.
+ * Throws if used without `<AnnotationProvider>` wrapping the component tree.
  */
 export declare const PlaylistAnnotationList: default_2.FC<PlaylistAnnotationListProps>;
 
@@ -1044,9 +1032,9 @@ export declare interface PlaylistVisualizationProps {
 }
 
 /**
- * Props passed to the renderAnnotationItem function for custom rendering
+ * Props passed to the renderAnnotationItem function for custom rendering.
  */
-export declare interface RenderAnnotationItemProps {
+declare interface RenderAnnotationItemProps {
     annotation: AnnotationData;
     index: number;
     isActive: boolean;
@@ -1409,14 +1397,23 @@ export declare function useAnnotationDragHandlers({ annotations, onAnnotationsCh
 };
 
 declare interface UseAnnotationDragHandlersOptions {
-    annotations: Annotation$1[];
-    onAnnotationsChange: (annotations: Annotation$1[]) => void;
+    annotations: AnnotationData[];
+    onAnnotationsChange: (annotations: AnnotationData[]) => void;
     samplesPerPixel: number;
     sampleRate: number;
     duration: number;
     linkEndpoints: boolean;
 }
 
+/**
+ * Hook to access annotation integration provided by @waveform-playlist/annotations.
+ * Throws if used without <AnnotationProvider> wrapping the component tree.
+ *
+ * Follows the Kent C. Dodds pattern:
+ * https://kentcdodds.com/blog/how-to-use-react-context-effectively
+ */
+export declare function useAnnotationIntegration(): AnnotationIntegration;
+
 /**
  * Hook for keyboard-based annotation navigation and boundary editing
  *
@@ -1461,9 +1458,9 @@ export declare function useAnnotationKeyboardControls({ annotations, activeAnnot
 };
 
 declare interface UseAnnotationKeyboardControlsOptions {
-    annotations: Annotation$1[];
+    annotations: AnnotationData[];
     activeAnnotationId: string | null;
-    onAnnotationsChange: (annotations: Annotation$1[]) => void;
+    onAnnotationsChange: (annotations: AnnotationData[]) => void;
     /** Callback to set the active annotation ID for selection */
     onActiveAnnotationChange?: (id: string | null) => void;
     duration: number;
@@ -1703,28 +1700,6 @@ export declare interface UseExportWavReturn {
     error: string | null;
 }
 
-export declare function useIntegratedRecording(tracks: ClipTrack[], setTracks: (tracks: ClipTrack[]) => void, selectedTrackId: string | null, options?: IntegratedRecordingOptions): UseIntegratedRecordingReturn;
-
-export declare interface UseIntegratedRecordingReturn {
-    isRecording: boolean;
-    isPaused: boolean;
-    duration: number;
-    level: number;
-    peakLevel: number;
-    error: Error | null;
-    stream: MediaStream | null;
-    devices: MicrophoneDevice[];
-    hasPermission: boolean;
-    selectedDevice: string | null;
-    startRecording: () => void;
-    stopRecording: () => void;
-    pauseRecording: () => void;
-    resumeRecording: () => void;
-    requestMicAccess: () => Promise<void>;
-    changeDevice: (deviceId: string) => Promise<void>;
-    recordingPeaks: Int8Array | Int16Array;
-}
-
 /**
  * Hook for managing keyboard shortcuts
  *
@@ -1867,7 +1842,14 @@ export declare const usePlaylistData: () => PlaylistDataContextValue;
 
 export declare const usePlaylistState: () => PlaylistStateContextValue;
 
-export declare function useSpectrogramIntegration(): SpectrogramIntegration | null;
+/**
+ * Hook to access spectrogram integration provided by @waveform-playlist/spectrogram.
+ * Throws if used without <SpectrogramProvider> wrapping the component tree.
+ *
+ * Follows the Kent C. Dodds pattern:
+ * https://kentcdodds.com/blog/how-to-use-react-context-effectively
+ */
+export declare function useSpectrogramIntegration(): SpectrogramIntegration;
 
 /**
  * Hook to manage time format state