@waveform-playlist/browser 13.1.2 → 13.1.3

package/dist/index.d.mts

@@ -224,6 +224,13 @@ declare const usePlaybackAnimation: () => PlaybackAnimationContextValue;
 declare const usePlaylistState: () => PlaylistStateContextValue;
 declare const usePlaylistControls: () => PlaylistControlsContextValue;
 declare const usePlaylistData: () => PlaylistDataContextValue;
+/**
+ * Like {@link usePlaylistData} but returns `null` instead of throwing when there
+ * is no WaveformPlaylistProvider ancestor. Use this in hooks/components that may
+ * also run in the MediaElement path (MediaElementPlaylistProvider), where the
+ * WebAudio playlist context is absent.
+ */
+declare const usePlaylistDataOptional: () => PlaylistDataContextValue | null;
 
 interface MediaElementTrackConfig {
     /** Audio source URL or Blob URL */
@@ -824,6 +831,14 @@ interface UseAnnotationKeyboardControlsOptions {
     scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
     /** Optional: callback to start playback at a time with optional duration */
     onPlay?: (startTime: number, duration?: number) => void;
+    /**
+     * Pixels-per-sample for auto-scroll positioning. Falls back to the
+     * WaveformPlaylistProvider context when omitted (WebAudio path). Pass
+     * explicitly when used outside that provider (e.g. the MediaElement path).
+     */
+    samplesPerPixel?: number;
+    /** Sample rate for auto-scroll positioning. Falls back to context. */
+    sampleRate?: number;
 }
 /**
  * Hook for keyboard-based annotation navigation and boundary editing
@@ -856,7 +871,7 @@ interface UseAnnotationKeyboardControlsOptions {
  * });
  * ```
  */
-declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, onPlay, }: UseAnnotationKeyboardControlsOptions): {
+declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, onPlay, samplesPerPixel: samplesPerPixelProp, sampleRate: sampleRateProp, }: UseAnnotationKeyboardControlsOptions): {
     moveStartBoundary: (delta: number) => void;
     moveEndBoundary: (delta: number) => void;
     selectPrevious: () => void;
@@ -1850,4 +1865,4 @@ declare function getWaveformDataMetadata(src: string): Promise<{
     bits: 8 | 16;
 }>;
 
-export { type ActiveEffect, type AnnotationIntegration, AnnotationIntegrationProvider, AudioPosition, type AudioTrackConfig, AutomaticScrollCheckbox, ClearAllButton, type ClearAllButtonProps, ClipCollisionModifier, ClipInteractionProvider, type ClipInteractionProviderProps, ContinuousPlayCheckbox, DownloadAnnotationsButton, EditableCheckbox, type EffectDefinition, type EffectInstance, type EffectParameter, type ExportOptions, type ExportResult, ExportWavButton, type ExportWavButtonProps, FastForwardButton, type FrameData, type GetAnnotationBoxLabelFn, KeyboardShortcuts, type KeyboardShortcutsProps, LinkEndpointsCheckbox, LoopButton, MasterVolumeControl, type MasterVolumeControls, type MediaElementAnimationContextValue, MediaElementAnnotationList, type MediaElementAnnotationListProps, type MediaElementControlsContextValue, type MediaElementDataContextValue, MediaElementPlaylist, type MediaElementPlaylistProps, MediaElementPlaylistProvider, type MediaElementStateContextValue, type MediaElementTrackConfig, MediaElementWaveform, type MediaElementWaveformProps, type OnAnnotationUpdateFn, type ParameterType, PauseButton, PlayButton, PlaylistAnnotationList, type PlaylistAnnotationListProps, PlaylistVisualization, type PlaylistVisualizationProps, RewindButton, SelectionTimeInputs, SetLoopRegionButton, SkipBackwardButton, SkipForwardButton, SnapToGridModifier, type SpectrogramCanvasRegistration, type SpectrogramIntegration, SpectrogramIntegrationProvider, StopButton, type TimeFormatControls, TimeFormatSelect, type TrackActiveEffect, type TrackEffectsState, type TrackLoadError, type TrackSource, type TrackState$1 as TrackState, type UseDynamicEffectsReturn, type UseDynamicTracksReturn, type UseExportWavReturn, type UseOutputMeterOptions, type UseOutputMeterReturn, type UsePlaybackShortcutsOptions, type UsePlaybackShortcutsReturn, type UseTrackDynamicEffectsReturn, Waveform, WaveformPlaylistProvider, type WaveformProps, type WaveformTrack, type ZoomControls, ZoomInButton, ZoomOutButton, createEffectChain, createEffectInstance, effectCategories, effectDefinitions, getEffectDefinition, getEffectsByCategory, getWaveformDataMetadata, loadPeaksFromWaveformData, loadWaveformData, noDropAnimationPlugins, useAnnotationDragHandlers, useAnnotationIntegration, useAnnotationKeyboardControls, useAudioTracks, useClipDragHandlers, useClipInteractionEnabled, useClipSplitting, useDragSensors, useDynamicEffects, useDynamicTracks, useExportWav, useKeyboardShortcuts, useMasterAnalyser, useMasterVolume, useMediaElementAnimation, useMediaElementControls, useMediaElementData, useMediaElementState, useOutputMeter, usePlaybackAnimation, usePlaybackShortcuts, usePlaylistControls, usePlaylistData, usePlaylistState, useSpectrogramIntegration, useTimeFormat, useTrackDynamicEffects, useZoomControls, waveformDataToPeaks };
+export { type ActiveEffect, type AnnotationIntegration, AnnotationIntegrationProvider, AudioPosition, type AudioTrackConfig, AutomaticScrollCheckbox, ClearAllButton, type ClearAllButtonProps, ClipCollisionModifier, ClipInteractionProvider, type ClipInteractionProviderProps, ContinuousPlayCheckbox, DownloadAnnotationsButton, EditableCheckbox, type EffectDefinition, type EffectInstance, type EffectParameter, type ExportOptions, type ExportResult, ExportWavButton, type ExportWavButtonProps, FastForwardButton, type FrameData, type GetAnnotationBoxLabelFn, KeyboardShortcuts, type KeyboardShortcutsProps, LinkEndpointsCheckbox, LoopButton, MasterVolumeControl, type MasterVolumeControls, type MediaElementAnimationContextValue, MediaElementAnnotationList, type MediaElementAnnotationListProps, type MediaElementControlsContextValue, type MediaElementDataContextValue, MediaElementPlaylist, type MediaElementPlaylistProps, MediaElementPlaylistProvider, type MediaElementStateContextValue, type MediaElementTrackConfig, MediaElementWaveform, type MediaElementWaveformProps, type OnAnnotationUpdateFn, type ParameterType, PauseButton, PlayButton, PlaylistAnnotationList, type PlaylistAnnotationListProps, PlaylistVisualization, type PlaylistVisualizationProps, RewindButton, SelectionTimeInputs, SetLoopRegionButton, SkipBackwardButton, SkipForwardButton, SnapToGridModifier, type SpectrogramCanvasRegistration, type SpectrogramIntegration, SpectrogramIntegrationProvider, StopButton, type TimeFormatControls, TimeFormatSelect, type TrackActiveEffect, type TrackEffectsState, type TrackLoadError, type TrackSource, type TrackState$1 as TrackState, type UseDynamicEffectsReturn, type UseDynamicTracksReturn, type UseExportWavReturn, type UseOutputMeterOptions, type UseOutputMeterReturn, type UsePlaybackShortcutsOptions, type UsePlaybackShortcutsReturn, type UseTrackDynamicEffectsReturn, Waveform, WaveformPlaylistProvider, type WaveformProps, type WaveformTrack, type ZoomControls, ZoomInButton, ZoomOutButton, createEffectChain, createEffectInstance, effectCategories, effectDefinitions, getEffectDefinition, getEffectsByCategory, getWaveformDataMetadata, loadPeaksFromWaveformData, loadWaveformData, noDropAnimationPlugins, useAnnotationDragHandlers, useAnnotationIntegration, useAnnotationKeyboardControls, useAudioTracks, useClipDragHandlers, useClipInteractionEnabled, useClipSplitting, useDragSensors, useDynamicEffects, useDynamicTracks, useExportWav, useKeyboardShortcuts, useMasterAnalyser, useMasterVolume, useMediaElementAnimation, useMediaElementControls, useMediaElementData, useMediaElementState, useOutputMeter, usePlaybackAnimation, usePlaybackShortcuts, usePlaylistControls, usePlaylistData, usePlaylistDataOptional, usePlaylistState, useSpectrogramIntegration, useTimeFormat, useTrackDynamicEffects, useZoomControls, waveformDataToPeaks };

package/dist/index.d.ts

@@ -224,6 +224,13 @@ declare const usePlaybackAnimation: () => PlaybackAnimationContextValue;
 declare const usePlaylistState: () => PlaylistStateContextValue;
 declare const usePlaylistControls: () => PlaylistControlsContextValue;
 declare const usePlaylistData: () => PlaylistDataContextValue;
+/**
+ * Like {@link usePlaylistData} but returns `null` instead of throwing when there
+ * is no WaveformPlaylistProvider ancestor. Use this in hooks/components that may
+ * also run in the MediaElement path (MediaElementPlaylistProvider), where the
+ * WebAudio playlist context is absent.
+ */
+declare const usePlaylistDataOptional: () => PlaylistDataContextValue | null;
 
 interface MediaElementTrackConfig {
     /** Audio source URL or Blob URL */
@@ -824,6 +831,14 @@ interface UseAnnotationKeyboardControlsOptions {
     scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
     /** Optional: callback to start playback at a time with optional duration */
     onPlay?: (startTime: number, duration?: number) => void;
+    /**
+     * Pixels-per-sample for auto-scroll positioning. Falls back to the
+     * WaveformPlaylistProvider context when omitted (WebAudio path). Pass
+     * explicitly when used outside that provider (e.g. the MediaElement path).
+     */
+    samplesPerPixel?: number;
+    /** Sample rate for auto-scroll positioning. Falls back to context. */
+    sampleRate?: number;
 }
 /**
  * Hook for keyboard-based annotation navigation and boundary editing
@@ -856,7 +871,7 @@ interface UseAnnotationKeyboardControlsOptions {
  * });
  * ```
  */
-declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, onPlay, }: UseAnnotationKeyboardControlsOptions): {
+declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, onPlay, samplesPerPixel: samplesPerPixelProp, sampleRate: sampleRateProp, }: UseAnnotationKeyboardControlsOptions): {
     moveStartBoundary: (delta: number) => void;
     moveEndBoundary: (delta: number) => void;
     selectPrevious: () => void;
@@ -1850,4 +1865,4 @@ declare function getWaveformDataMetadata(src: string): Promise<{
     bits: 8 | 16;
 }>;
 
-export { type ActiveEffect, type AnnotationIntegration, AnnotationIntegrationProvider, AudioPosition, type AudioTrackConfig, AutomaticScrollCheckbox, ClearAllButton, type ClearAllButtonProps, ClipCollisionModifier, ClipInteractionProvider, type ClipInteractionProviderProps, ContinuousPlayCheckbox, DownloadAnnotationsButton, EditableCheckbox, type EffectDefinition, type EffectInstance, type EffectParameter, type ExportOptions, type ExportResult, ExportWavButton, type ExportWavButtonProps, FastForwardButton, type FrameData, type GetAnnotationBoxLabelFn, KeyboardShortcuts, type KeyboardShortcutsProps, LinkEndpointsCheckbox, LoopButton, MasterVolumeControl, type MasterVolumeControls, type MediaElementAnimationContextValue, MediaElementAnnotationList, type MediaElementAnnotationListProps, type MediaElementControlsContextValue, type MediaElementDataContextValue, MediaElementPlaylist, type MediaElementPlaylistProps, MediaElementPlaylistProvider, type MediaElementStateContextValue, type MediaElementTrackConfig, MediaElementWaveform, type MediaElementWaveformProps, type OnAnnotationUpdateFn, type ParameterType, PauseButton, PlayButton, PlaylistAnnotationList, type PlaylistAnnotationListProps, PlaylistVisualization, type PlaylistVisualizationProps, RewindButton, SelectionTimeInputs, SetLoopRegionButton, SkipBackwardButton, SkipForwardButton, SnapToGridModifier, type SpectrogramCanvasRegistration, type SpectrogramIntegration, SpectrogramIntegrationProvider, StopButton, type TimeFormatControls, TimeFormatSelect, type TrackActiveEffect, type TrackEffectsState, type TrackLoadError, type TrackSource, type TrackState$1 as TrackState, type UseDynamicEffectsReturn, type UseDynamicTracksReturn, type UseExportWavReturn, type UseOutputMeterOptions, type UseOutputMeterReturn, type UsePlaybackShortcutsOptions, type UsePlaybackShortcutsReturn, type UseTrackDynamicEffectsReturn, Waveform, WaveformPlaylistProvider, type WaveformProps, type WaveformTrack, type ZoomControls, ZoomInButton, ZoomOutButton, createEffectChain, createEffectInstance, effectCategories, effectDefinitions, getEffectDefinition, getEffectsByCategory, getWaveformDataMetadata, loadPeaksFromWaveformData, loadWaveformData, noDropAnimationPlugins, useAnnotationDragHandlers, useAnnotationIntegration, useAnnotationKeyboardControls, useAudioTracks, useClipDragHandlers, useClipInteractionEnabled, useClipSplitting, useDragSensors, useDynamicEffects, useDynamicTracks, useExportWav, useKeyboardShortcuts, useMasterAnalyser, useMasterVolume, useMediaElementAnimation, useMediaElementControls, useMediaElementData, useMediaElementState, useOutputMeter, usePlaybackAnimation, usePlaybackShortcuts, usePlaylistControls, usePlaylistData, usePlaylistState, useSpectrogramIntegration, useTimeFormat, useTrackDynamicEffects, useZoomControls, waveformDataToPeaks };
+export { type ActiveEffect, type AnnotationIntegration, AnnotationIntegrationProvider, AudioPosition, type AudioTrackConfig, AutomaticScrollCheckbox, ClearAllButton, type ClearAllButtonProps, ClipCollisionModifier, ClipInteractionProvider, type ClipInteractionProviderProps, ContinuousPlayCheckbox, DownloadAnnotationsButton, EditableCheckbox, type EffectDefinition, type EffectInstance, type EffectParameter, type ExportOptions, type ExportResult, ExportWavButton, type ExportWavButtonProps, FastForwardButton, type FrameData, type GetAnnotationBoxLabelFn, KeyboardShortcuts, type KeyboardShortcutsProps, LinkEndpointsCheckbox, LoopButton, MasterVolumeControl, type MasterVolumeControls, type MediaElementAnimationContextValue, MediaElementAnnotationList, type MediaElementAnnotationListProps, type MediaElementControlsContextValue, type MediaElementDataContextValue, MediaElementPlaylist, type MediaElementPlaylistProps, MediaElementPlaylistProvider, type MediaElementStateContextValue, type MediaElementTrackConfig, MediaElementWaveform, type MediaElementWaveformProps, type OnAnnotationUpdateFn, type ParameterType, PauseButton, PlayButton, PlaylistAnnotationList, type PlaylistAnnotationListProps, PlaylistVisualization, type PlaylistVisualizationProps, RewindButton, SelectionTimeInputs, SetLoopRegionButton, SkipBackwardButton, SkipForwardButton, SnapToGridModifier, type SpectrogramCanvasRegistration, type SpectrogramIntegration, SpectrogramIntegrationProvider, StopButton, type TimeFormatControls, TimeFormatSelect, type TrackActiveEffect, type TrackEffectsState, type TrackLoadError, type TrackSource, type TrackState$1 as TrackState, type UseDynamicEffectsReturn, type UseDynamicTracksReturn, type UseExportWavReturn, type UseOutputMeterOptions, type UseOutputMeterReturn, type UsePlaybackShortcutsOptions, type UsePlaybackShortcutsReturn, type UseTrackDynamicEffectsReturn, Waveform, WaveformPlaylistProvider, type WaveformProps, type WaveformTrack, type ZoomControls, ZoomInButton, ZoomOutButton, createEffectChain, createEffectInstance, effectCategories, effectDefinitions, getEffectDefinition, getEffectsByCategory, getWaveformDataMetadata, loadPeaksFromWaveformData, loadWaveformData, noDropAnimationPlugins, useAnnotationDragHandlers, useAnnotationIntegration, useAnnotationKeyboardControls, useAudioTracks, useClipDragHandlers, useClipInteractionEnabled, useClipSplitting, useDragSensors, useDynamicEffects, useDynamicTracks, useExportWav, useKeyboardShortcuts, useMasterAnalyser, useMasterVolume, useMediaElementAnimation, useMediaElementControls, useMediaElementData, useMediaElementState, useOutputMeter, usePlaybackAnimation, usePlaybackShortcuts, usePlaylistControls, usePlaylistData, usePlaylistDataOptional, usePlaylistState, useSpectrogramIntegration, useTimeFormat, useTrackDynamicEffects, useZoomControls, waveformDataToPeaks };

package/dist/index.js

@@ -150,6 +150,7 @@ __export(index_exports, {
   usePlaybackShortcuts: () => usePlaybackShortcuts,
   usePlaylistControls: () => usePlaylistControls,
   usePlaylistData: () => usePlaylistData,
+  usePlaylistDataOptional: () => usePlaylistDataOptional,
   usePlaylistState: () => usePlaylistState,
   useSpectrogramIntegration: () => useSpectrogramIntegration,
   useTimeFormat: () => useTimeFormat,
@@ -1393,9 +1394,13 @@ function useAnnotationKeyboardControls({
   continuousPlay = false,
   enabled = true,
   scrollContainerRef,
-  onPlay
+  onPlay,
+  samplesPerPixel: samplesPerPixelProp,
+  sampleRate: sampleRateProp
 }) {
-  const { samplesPerPixel, sampleRate } = usePlaylistData();
+  const playlistData = usePlaylistDataOptional();
+  const samplesPerPixel = samplesPerPixelProp != null ? samplesPerPixelProp : playlistData == null ? void 0 : playlistData.samplesPerPixel;
+  const sampleRate = sampleRateProp != null ? sampleRateProp : playlistData == null ? void 0 : playlistData.sampleRate;
   const activeIndex = (0, import_react16.useMemo)(() => {
     if (!activeAnnotationId) return -1;
     return annotations.findIndex((a) => a.id === activeAnnotationId);
@@ -4719,6 +4724,7 @@ var usePlaylistData = () => {
   }
   return context;
 };
+var usePlaylistDataOptional = () => (0, import_react24.useContext)(PlaylistDataContext);
 
 // src/MediaElementPlaylistContext.tsx
 var import_react25 = require("react");
@@ -7320,6 +7326,7 @@ var ClipInteractionProvider = ({
   usePlaybackShortcuts,
   usePlaylistControls,
   usePlaylistData,
+  usePlaylistDataOptional,
   usePlaylistState,
   useSpectrogramIntegration,
   useTimeFormat,