@waveform-playlist/browser 9.1.2 → 9.2.0

package/dist/index.d.ts

@@ -1112,7 +1112,7 @@ export declare const PlaylistVisualization: default_2.FC<PlaylistVisualizationPr
 
 export declare interface PlaylistVisualizationProps {
     renderTrackControls?: (trackIndex: number) => ReactNode;
-    renderTimestamp?: (timeMs: number, pixelPosition: number) => ReactNode;
+    renderTick?: (label: string, pixelPosition: number) => ReactNode;
     /** Custom playhead render function. Receives position (pixels) and color from theme. */
     renderPlayhead?: RenderPlayheadFunction;
     annotationControls?: AnnotationAction[];
@@ -1189,6 +1189,43 @@ export declare const SkipForwardButton: default_2.FC<{
     className?: string;
 }>;
 
+declare type SnapTo = 'bar' | 'beat' | 'off';
+
+declare interface SnapToGridBeatsOptions {
+    mode: 'beats';
+    snapTo: SnapTo;
+    bpm: number;
+    timeSignature: [number, number];
+    samplesPerPixel: number;
+    sampleRate: number;
+}
+
+/**
+ * dnd-kit modifier that quantizes clip drag movement to a grid.
+ *
+ * Two modes:
+ * - "beats": Snaps to beat/bar grid using PPQN tick space for exact musical timing.
+ * - "temporal": Snaps to a sample-based grid derived from timescale markers.
+ *
+ * Designed to compose with ClipCollisionModifier — snap first,
+ * then collision constrains the snapped position.
+ */
+export declare class SnapToGridModifier extends Modifier<DragDropManager<any, any>, SnapToGridOptions> {
+    apply(operation: DragOperation): {
+        x: number;
+        y: number;
+    };
+    static configure: (options: SnapToGridBeatsOptions | SnapToGridTemporalOptions) => PluginDescriptor<any, any, typeof SnapToGridModifier>;
+}
+
+declare type SnapToGridOptions = SnapToGridBeatsOptions | SnapToGridTemporalOptions;
+
+declare interface SnapToGridTemporalOptions {
+    mode: 'temporal';
+    gridSamples: number;
+    samplesPerPixel: number;
+}
+
 /**
  * Caches parsed SoundFont2 data and AudioBuffers for efficient playback.
  *
@@ -1608,10 +1645,19 @@ declare interface UseAnnotationKeyboardControlsOptions {
  *   { src: 'audio/drums.mp3', name: 'Drums' },
  * ]);
  *
- * // Progressive loading (tracks appear as they load)
- * const { tracks, loading, loadedCount, totalCount } = useAudioTracks(
- *   [{ src: 'audio/vocals.mp3' }, { src: 'audio/drums.mp3' }],
- *   { progressive: true }
+ * // Immediate rendering with deferred engine build (recommended for multi-track)
+ * const { tracks, loading } = useAudioTracks(
+ *   [
+ *     { src: 'audio/vocals.mp3', name: 'Vocals', duration: 30 },
+ *     { src: 'audio/drums.mp3', name: 'Drums', duration: 30 },
+ *   ],
+ *   { immediate: true }
+ * );
+ * // All tracks render instantly as placeholders, peaks fill in as files load
+ * return (
+ *   <WaveformPlaylistProvider tracks={tracks} deferEngineRebuild={loading}>
+ *     ...
+ *   </WaveformPlaylistProvider>
  * );
  *
  * // Pre-loaded AudioBuffer (skip fetch/decode)
@@ -1623,11 +1669,6 @@ declare interface UseAnnotationKeyboardControlsOptions {
  * 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[], options?: UseAudioTracksOptions): {
@@ -1643,10 +1684,16 @@ export declare function useAudioTracks(configs: AudioTrackConfig[], options?: Us
  */
 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)
+     * When true, all tracks render immediately as placeholders with clip geometry
+     * from the config. Audio fills in progressively as files decode, and peaks
+     * render as each buffer becomes available. Use with `deferEngineRebuild={loading}`
+     * on the provider for a single engine build when all tracks are ready.
+     *
+     * Requires `duration` or `waveformData` in each config so clip dimensions are known upfront.
+     * Default: false
      */
+    immediate?: boolean;
+    /** @deprecated Use `immediate` instead. */
     progressive?: boolean;
 }
 
@@ -1688,7 +1735,7 @@ declare interface UseAudioTracksOptions {
  * );
  * ```
  */
-export declare function useClipDragHandlers({ tracks, onTracksChange, samplesPerPixel, sampleRate, engineRef, isDraggingRef, }: UseClipDragHandlersOptions): {
+export declare function useClipDragHandlers({ tracks, onTracksChange, samplesPerPixel, sampleRate, engineRef, isDraggingRef, snapSamplePosition, }: UseClipDragHandlersOptions): {
     onDragStart: (event: Parameters<DragStartEvent>[0]) => void;
     onDragMove: (event: Parameters<DragMoveEvent>[0]) => void;
     onDragEnd: (event: Parameters<DragEndEvent>[0]) => void;
@@ -1704,6 +1751,9 @@ declare interface UseClipDragHandlersOptions {
      *  skips engine rebuilds so engine keeps original clip positions. On drag end,
      *  engine.trimClip() commits the final delta. Obtain from usePlaylistData(). */
     isDraggingRef: default_2.MutableRefObject<boolean>;
+    /** Optional function that snaps a sample position to the nearest grid position.
+     *  Used for boundary trim snapping (move snapping is handled by the SnapToGridModifier). */
+    snapSamplePosition?: (samplePosition: number) => number;
 }
 
 /**
@@ -2166,6 +2216,10 @@ declare interface WaveformPlaylistProviderProps {
     /** SoundFont cache for sample-based MIDI playback. When provided, MIDI clips
      *  use SoundFont samples instead of PolySynth synthesis. */
     soundFontCache?: SoundFontCache;
+    /** When true, tracks render visually but the engine build is deferred.
+     *  Use this during progressive loading to avoid rebuilding the engine for
+     *  each track — flip to false when all tracks are ready for a single build. */
+    deferEngineRebuild?: boolean;
     children: ReactNode;
 }
 
@@ -2226,6 +2280,10 @@ declare interface WaveformPlaylistTheme {
 
 export declare interface WaveformProps {
     renderTrackControls?: (trackIndex: number) => ReactNode;
+    /** Custom render function for timescale tick labels. `label` is a formatted string
+     * (bar/beat notation like "2.3" in beats mode, or "m:ss" in temporal mode). */
+    renderTick?: (label: string, pixelPosition: number) => ReactNode;
+    /** @deprecated Use `renderTick` instead. */
     renderTimestamp?: (timeMs: number, pixelPosition: number) => ReactNode;
     /** Custom playhead render function. Receives position (pixels) and color from theme. */
     renderPlayhead?: RenderPlayheadFunction;