@waveform-playlist/browser 11.2.0 → 11.3.1

package/dist/index.d.mts

@@ -41,6 +41,15 @@ interface TrackState$1 {
     volume: number;
     pan: number;
 }
+/** Per-frame data passed to registered animation callbacks. */
+interface FrameData {
+    /** Raw engine time (for state/logic — NOT for visual positioning). */
+    readonly time: number;
+    /** time - outputLatency (for DOM positioning — matches speaker output). */
+    readonly visualTime: number;
+    readonly sampleRate: number;
+    readonly samplesPerPixel: number;
+}
 interface PlaybackAnimationContextValue {
     isPlaying: boolean;
     currentTime: number;
@@ -49,6 +58,10 @@ interface PlaybackAnimationContextValue {
     audioStartPositionRef: React__default.RefObject<number>;
     /** Returns current playback time from engine (auto-wraps at loop boundaries). */
     getPlaybackTime: () => number;
+    /** Register a per-frame callback driven by the single animation loop. */
+    registerFrameCallback: (id: string, cb: (data: FrameData) => void) => void;
+    /** Unregister a per-frame callback. */
+    unregisterFrameCallback: (id: string) => void;
 }
 interface PlaylistStateContextValue {
     continuousPlay: boolean;
@@ -949,7 +962,7 @@ type TrackEffectsFunction = (graphEnd: unknown, destination: unknown, isOffline:
 interface ExportOptions extends WavEncoderOptions {
     /** Filename for download (without extension) */
     filename?: string;
-    /** Export mode: 'master' for stereo mix, 'individual' for single track */
+    /** Export mode: 'master' for full mixdown, 'individual' for single track */
     mode?: 'master' | 'individual';
     /** Track index for individual export (only used when mode is 'individual') */
     trackIndex?: number;
@@ -958,8 +971,8 @@ interface ExportOptions extends WavEncoderOptions {
     /** Whether to apply effects (fades, etc.) - defaults to true */
     applyEffects?: boolean;
     /**
-     * Optional Tone.js effects function for master effects. When provided, export will use Tone.Offline
-     * to render through the effects chain. The function receives isOffline=true.
+     * Optional Tone.js effects function for master effects. When provided, export renders
+     * through the effects chain. The function receives isOffline=true.
      */
     effectsFunction?: EffectsFunction;
     /**
@@ -996,8 +1009,8 @@ interface TrackState {
     pan: number;
 }
 /**
- * Hook for exporting the waveform playlist to WAV format
- * Uses OfflineAudioContext for fast, non-real-time rendering
+ * Hook for exporting the waveform playlist to WAV format.
+ * Uses Tone.Offline for non-real-time rendering, mirroring the live playback graph.
  */
 declare function useExportWav(): UseExportWavReturn;
 
@@ -1174,7 +1187,7 @@ declare const TimeFormatSelect: React__default.FC<{
 }>;
 /**
  * Audio position display that uses the playlist context.
- * Uses requestAnimationFrame for smooth 60fps updates during playback.
+ * Updates via the shared animation frame registry — no own rAF loop.
  * Direct DOM manipulation avoids React re-renders.
  */
 declare const AudioPosition: React__default.FC<{
@@ -1811,4 +1824,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 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 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 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 };

package/dist/index.d.ts

@@ -41,6 +41,15 @@ interface TrackState$1 {
     volume: number;
     pan: number;
 }
+/** Per-frame data passed to registered animation callbacks. */
+interface FrameData {
+    /** Raw engine time (for state/logic — NOT for visual positioning). */
+    readonly time: number;
+    /** time - outputLatency (for DOM positioning — matches speaker output). */
+    readonly visualTime: number;
+    readonly sampleRate: number;
+    readonly samplesPerPixel: number;
+}
 interface PlaybackAnimationContextValue {
     isPlaying: boolean;
     currentTime: number;
@@ -49,6 +58,10 @@ interface PlaybackAnimationContextValue {
     audioStartPositionRef: React__default.RefObject<number>;
     /** Returns current playback time from engine (auto-wraps at loop boundaries). */
     getPlaybackTime: () => number;
+    /** Register a per-frame callback driven by the single animation loop. */
+    registerFrameCallback: (id: string, cb: (data: FrameData) => void) => void;
+    /** Unregister a per-frame callback. */
+    unregisterFrameCallback: (id: string) => void;
 }
 interface PlaylistStateContextValue {
     continuousPlay: boolean;
@@ -949,7 +962,7 @@ type TrackEffectsFunction = (graphEnd: unknown, destination: unknown, isOffline:
 interface ExportOptions extends WavEncoderOptions {
     /** Filename for download (without extension) */
     filename?: string;
-    /** Export mode: 'master' for stereo mix, 'individual' for single track */
+    /** Export mode: 'master' for full mixdown, 'individual' for single track */
     mode?: 'master' | 'individual';
     /** Track index for individual export (only used when mode is 'individual') */
     trackIndex?: number;
@@ -958,8 +971,8 @@ interface ExportOptions extends WavEncoderOptions {
     /** Whether to apply effects (fades, etc.) - defaults to true */
     applyEffects?: boolean;
     /**
-     * Optional Tone.js effects function for master effects. When provided, export will use Tone.Offline
-     * to render through the effects chain. The function receives isOffline=true.
+     * Optional Tone.js effects function for master effects. When provided, export renders
+     * through the effects chain. The function receives isOffline=true.
      */
     effectsFunction?: EffectsFunction;
     /**
@@ -996,8 +1009,8 @@ interface TrackState {
     pan: number;
 }
 /**
- * Hook for exporting the waveform playlist to WAV format
- * Uses OfflineAudioContext for fast, non-real-time rendering
+ * Hook for exporting the waveform playlist to WAV format.
+ * Uses Tone.Offline for non-real-time rendering, mirroring the live playback graph.
  */
 declare function useExportWav(): UseExportWavReturn;
 
@@ -1174,7 +1187,7 @@ declare const TimeFormatSelect: React__default.FC<{
 }>;
 /**
  * Audio position display that uses the playlist context.
- * Uses requestAnimationFrame for smooth 60fps updates during playback.
+ * Updates via the shared animation frame registry — no own rAF loop.
  * Direct DOM manipulation avoids React re-renders.
  */
 declare const AudioPosition: React__default.FC<{
@@ -1811,4 +1824,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 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 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 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 };