@waveform-playlist/browser 5.0.0-alpha.15 → 5.0.0-alpha.17

package/dist/index.d.ts

@@ -59,6 +59,19 @@ export 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
  *
@@ -411,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[];
@@ -546,6 +574,9 @@ export declare interface MediaElementControlsContextValue {
     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 {
@@ -594,6 +625,8 @@ declare interface MediaElementPlaylistProviderProps {
     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 */
@@ -622,6 +655,7 @@ export declare interface MediaElementStateContextValue {
     annotations: AnnotationData[];
     activeAnnotationId: string | null;
     playbackRate: number;
+    isAutomaticScroll: boolean;
 }
 
 export declare interface MediaElementTrackConfig {
@@ -651,12 +685,7 @@ 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?: (annotation: {
-        id: string;
-        start: number;
-        end: number;
-        lines: string[];
-    }) => string;
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
     /**
      * Custom render function for annotation items in the text list.
      * When provided, completely replaces the default annotation item rendering.
@@ -669,12 +698,9 @@ export declare interface MediaElementWaveformProps {
      * Callback when annotations are updated (e.g., boundaries dragged).
      * Called with the full updated annotations array.
      */
-    onAnnotationUpdate?: (annotations: {
-        id: string;
-        start: number;
-        end: number;
-        lines: string[];
-    }[]) => void;
+    onAnnotationUpdate?: OnAnnotationUpdateFn;
+    /** Where to position the active annotation when auto-scrolling: 'center', 'start', 'end', or 'nearest'. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
     className?: string;
 }
 
@@ -684,6 +710,12 @@ declare interface MicrophoneDevice {
     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
@@ -1827,15 +1859,12 @@ export declare interface WaveformProps {
     renderAnnotationItem?: (props: RenderAnnotationItemProps) => ReactNode;
     /**
      * Custom function to generate the label shown on annotation boxes in the waveform.
-     * Receives the annotation data and should return a string label.
+     * Receives the annotation data and its index, returns a string label.
      * Default: annotation.id
      */
-    getAnnotationBoxLabel?: (annotation: {
-        id: string;
-        start: number;
-        end: number;
-        lines: string[];
-    }) => string;
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
+    /** Where to position the active annotation when auto-scrolling: 'center', 'start', 'end', or 'nearest'. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
     className?: string;
     showClipHeaders?: boolean;
     interactiveClips?: boolean;