@waveform-playlist/ui-components 12.0.0 → 12.1.0

package/dist/index.d.mts

@@ -353,8 +353,20 @@ interface PlayheadProps {
     controlsOffset?: number;
     /** Function to get current audio context time - required for smooth animation */
     getAudioContextTime?: () => number;
-    /** Returns current playback time (auto-wraps at loop boundaries). Preferred over manual elapsed calculation. */
+    /**
+     * Returns raw playback time from the engine (auto-wraps at loop boundaries).
+     * This is the scheduling position — for playhead display use `visualTimeRef`
+     * which already has `outputLatency` and `lookAhead` subtracted.
+     */
     getPlaybackTime?: () => number;
+    /**
+     * Ref to the visually-aligned playback time (raw time minus `outputLatency`
+     * and `engine.lookAhead`), kept current by the provider's animation loop
+     * during playback and by pause/stop/seek paths when stopped. Use this for
+     * playhead positioning so it lines up with audible output and matches the
+     * progress fill in `ChannelWithProgress`.
+     */
+    visualTimeRef?: react__default.RefObject<number>;
 }
 /**
  * Type for custom playhead render functions.

package/dist/index.d.ts

@@ -353,8 +353,20 @@ interface PlayheadProps {
     controlsOffset?: number;
     /** Function to get current audio context time - required for smooth animation */
     getAudioContextTime?: () => number;
-    /** Returns current playback time (auto-wraps at loop boundaries). Preferred over manual elapsed calculation. */
+    /**
+     * Returns raw playback time from the engine (auto-wraps at loop boundaries).
+     * This is the scheduling position — for playhead display use `visualTimeRef`
+     * which already has `outputLatency` and `lookAhead` subtracted.
+     */
     getPlaybackTime?: () => number;
+    /**
+     * Ref to the visually-aligned playback time (raw time minus `outputLatency`
+     * and `engine.lookAhead`), kept current by the provider's animation loop
+     * during playback and by pause/stop/seek paths when stopped. Use this for
+     * playhead positioning so it lines up with audible output and matches the
+     * progress fill in `ChannelWithProgress`.
+     */
+    visualTimeRef?: react__default.RefObject<number>;
 }
 /**
  * Type for custom playhead render functions.

package/dist/index.js

@@ -1602,6 +1602,7 @@ var PlayheadWithMarker = ({
   color = "#ff0000",
   isPlaying,
   currentTimeRef,
+  visualTimeRef,
   playbackStartTimeRef,
   audioStartPositionRef,
   samplesPerPixel,
@@ -1616,7 +1617,9 @@ var PlayheadWithMarker = ({
     const updatePosition = () => {
       if (containerRef.current) {
         let time;
-        if (isPlaying) {
+        if (visualTimeRef?.current !== void 0 && visualTimeRef.current !== null) {
+          time = visualTimeRef.current;
+        } else if (isPlaying) {
           if (getPlaybackTime) {
             time = getPlaybackTime();
           } else if (getAudioContextTime) {
@@ -1652,6 +1655,7 @@ var PlayheadWithMarker = ({
     samplesPerPixel,
     controlsOffset,
     currentTimeRef,
+    visualTimeRef,
     playbackStartTimeRef,
     audioStartPositionRef,
     getAudioContextTime,
@@ -1659,7 +1663,7 @@ var PlayheadWithMarker = ({
   ]);
   (0, import_react9.useEffect)(() => {
     if (!isPlaying && containerRef.current) {
-      const time = currentTimeRef.current ?? 0;
+      const time = visualTimeRef?.current ?? currentTimeRef.current ?? 0;
       const pos = time * sampleRate / samplesPerPixel + controlsOffset;
       containerRef.current.style.transform = `translate3d(${pos}px, 0, 0)`;
     }