@waveform-playlist/ui-components 11.3.1 → 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)`;
     }
@@ -2896,6 +2900,14 @@ var StyledTimeScale = (0, import_styled_components23.withTheme)(TimeScale);
 // src/components/SmartScale.tsx
 var import_core7 = require("@waveform-playlist/core");
 var import_jsx_runtime27 = require("react/jsx-runtime");
+function ticksToBarBeatLabel(ticks, timeSignature, ppqn = import_core7.PPQN) {
+  const barTicks = (0, import_core7.ticksPerBar)(timeSignature, ppqn);
+  const beatTicks = (0, import_core7.ticksPerBeat)(timeSignature, ppqn);
+  const bar = Math.floor(ticks / barTicks) + 1;
+  const beatInBar = Math.floor(ticks % barTicks / beatTicks) + 1;
+  if (beatInBar === 1) return `${bar}`;
+  return `${bar}.${beatInBar}`;
+}
 var timeinfo = /* @__PURE__ */ new Map([
   [700, { marker: 1e3, bigStep: 500, smallStep: 100 }],
   [1500, { marker: 2e3, bigStep: 1e3, smallStep: 200 }],
@@ -2978,7 +2990,7 @@ var SmartScale = ({ renderTick }) => {
         const tickHeight = isBarLine ? timeScaleHeight : isLabelTick ? Math.floor(timeScaleHeight / 2) : Math.floor(timeScaleHeight / 5);
         canvasInfo2.set(pix, tickHeight);
         if (isLabelTick) {
-          const label = (0, import_core7.ticksToBarBeatLabel)(tick, timeSignature);
+          const label = ticksToBarBeatLabel(tick, timeSignature);
           const element = renderTick ? /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(import_react23.default.Fragment, { children: renderTick(label, pix) }, `bb-${tick}`) : /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(
             "div",
             {