@waveform-playlist/browser 11.3.1 → 12.1.0

package/dist/index.d.mts

@@ -54,10 +54,23 @@ interface PlaybackAnimationContextValue {
     isPlaying: boolean;
     currentTime: number;
     currentTimeRef: React__default.RefObject<number>;
+    /**
+     * Visually-aligned playback time (raw engine time minus `outputLatency` and
+     * `engine.lookAhead`). Kept current by the animation loop during playback
+     * and by pause/seek/stop paths when stopped. Read from this for any visual
+     * positioning that should match the audible output.
+     */
+    visualTimeRef: React__default.RefObject<number>;
     playbackStartTimeRef: React__default.RefObject<number>;
     audioStartPositionRef: React__default.RefObject<number>;
-    /** Returns current playback time from engine (auto-wraps at loop boundaries). */
+    /** Returns raw playback time from engine (auto-wraps at loop boundaries). */
     getPlaybackTime: () => number;
+    /**
+     * Returns the current adapter scheduler lookahead (Tone ~0.1s, native 0).
+     * Use this for any audible-latency calculation that must match the playhead
+     * (e.g., recording live-preview peak slicing).
+     */
+    getLookAhead: () => 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. */

package/dist/index.d.ts

@@ -54,10 +54,23 @@ interface PlaybackAnimationContextValue {
     isPlaying: boolean;
     currentTime: number;
     currentTimeRef: React__default.RefObject<number>;
+    /**
+     * Visually-aligned playback time (raw engine time minus `outputLatency` and
+     * `engine.lookAhead`). Kept current by the animation loop during playback
+     * and by pause/seek/stop paths when stopped. Read from this for any visual
+     * positioning that should match the audible output.
+     */
+    visualTimeRef: React__default.RefObject<number>;
     playbackStartTimeRef: React__default.RefObject<number>;
     audioStartPositionRef: React__default.RefObject<number>;
-    /** Returns current playback time from engine (auto-wraps at loop boundaries). */
+    /** Returns raw playback time from engine (auto-wraps at loop boundaries). */
     getPlaybackTime: () => number;
+    /**
+     * Returns the current adapter scheduler lookahead (Tone ~0.1s, native 0).
+     * Use this for any audible-latency calculation that must match the playhead
+     * (e.g., recording live-preview peak slicing).
+     */
+    getLookAhead: () => 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. */

package/dist/index.js

@@ -3692,6 +3692,7 @@ var WaveformPlaylistProvider = ({
   isPlayingRef.current = isPlaying;
   const playStartPositionRef = (0, import_react24.useRef)(0);
   const currentTimeRef = (0, import_react24.useRef)(0);
+  const visualTimeRef = (0, import_react24.useRef)(0);
   const tracksRef = (0, import_react24.useRef)(tracks);
   const soundFontCacheRef = (0, import_react24.useRef)(soundFontCache);
   soundFontCacheRef.current = soundFontCache;
@@ -4162,6 +4163,25 @@ var WaveformPlaylistProvider = ({
     const elapsed = (0, import_tone4.getContext)().currentTime - ((_a2 = playbackStartTimeRef.current) != null ? _a2 : 0);
     return ((_b2 = audioStartPositionRef.current) != null ? _b2 : 0) + elapsed;
   }, []);
+  const toVisualTime = (0, import_react24.useCallback)((rawTime) => {
+    var _a2, _b2;
+    const audioCtx = (0, import_playout5.getGlobalAudioContext)();
+    const latency = "outputLatency" in audioCtx ? audioCtx.outputLatency : 0;
+    const lookAhead = (_b2 = (_a2 = engineRef.current) == null ? void 0 : _a2.lookAhead) != null ? _b2 : 0;
+    const visual = rawTime - latency - lookAhead;
+    return Number.isFinite(visual) ? Math.max(0, visual) : 0;
+  }, []);
+  const setCurrentTimeRefs = (0, import_react24.useCallback)(
+    (rawTime) => {
+      currentTimeRef.current = rawTime;
+      visualTimeRef.current = toVisualTime(rawTime);
+    },
+    [toVisualTime]
+  );
+  const getLookAhead = (0, import_react24.useCallback)(() => {
+    var _a2, _b2;
+    return (_b2 = (_a2 = engineRef.current) == null ? void 0 : _a2.lookAhead) != null ? _b2 : 0;
+  }, []);
   const registerFrameCallback = (0, import_react24.useCallback)((id, cb) => {
     frameCallbacksRef.current.set(id, cb);
   }, []);
@@ -4171,10 +4191,14 @@ var WaveformPlaylistProvider = ({
   const startAnimationLoop = (0, import_react24.useCallback)(() => {
     const audioCtx = (0, import_playout5.getGlobalAudioContext)();
     const updateTime = () => {
+      var _a2, _b2;
       const time = getPlaybackTime();
       currentTimeRef.current = time;
       const latency = "outputLatency" in audioCtx ? audioCtx.outputLatency : 0;
-      const visualTime = Math.max(0, time - latency);
+      const lookAhead = (_b2 = (_a2 = engineRef.current) == null ? void 0 : _a2.lookAhead) != null ? _b2 : 0;
+      const visualRaw = time - latency - lookAhead;
+      const visualTime = Number.isFinite(visualRaw) ? Math.max(0, visualRaw) : 0;
+      visualTimeRef.current = visualTime;
       const sr = sampleRateRef.current;
       const spp = samplesPerPixelRef.current;
       const frameData = {
@@ -4207,7 +4231,7 @@ var WaveformPlaylistProvider = ({
                 engineRef.current.stop();
               }
               setIsPlaying(false);
-              currentTimeRef.current = playStartPositionRef.current;
+              setCurrentTimeRefs(playStartPositionRef.current);
               setCurrentTime(playStartPositionRef.current);
               return;
             }
@@ -4230,7 +4254,7 @@ var WaveformPlaylistProvider = ({
           engineRef.current.stop();
         }
         setIsPlaying(false);
-        currentTimeRef.current = playbackEndTimeRef.current;
+        setCurrentTimeRefs(playbackEndTimeRef.current);
         setCurrentTime(playbackEndTimeRef.current);
         playbackEndTimeRef.current = null;
         return;
@@ -4240,7 +4264,7 @@ var WaveformPlaylistProvider = ({
           engineRef.current.stop();
         }
         setIsPlaying(false);
-        currentTimeRef.current = playStartPositionRef.current;
+        setCurrentTimeRefs(playStartPositionRef.current);
         setCurrentTime(playStartPositionRef.current);
         setActiveAnnotationId(null);
         return;
@@ -4248,7 +4272,13 @@ var WaveformPlaylistProvider = ({
       startAnimationFrameLoop(updateTime);
     };
     startAnimationFrameLoop(updateTime);
-  }, [duration, setActiveAnnotationId, startAnimationFrameLoop, getPlaybackTime]);
+  }, [
+    duration,
+    setActiveAnnotationId,
+    startAnimationFrameLoop,
+    getPlaybackTime,
+    setCurrentTimeRefs
+  ]);
   const stopAnimationLoop = stopAnimationFrameLoop;
   (0, import_react24.useEffect)(() => {
     const reschedulePlayback = () => __async(null, null, function* () {
@@ -4304,7 +4334,7 @@ var WaveformPlaylistProvider = ({
       if (!engineRef.current) return;
       const actualStartTime = startTime != null ? startTime : currentTimeRef.current;
       playStartPositionRef.current = actualStartTime;
-      currentTimeRef.current = actualStartTime;
+      setCurrentTimeRefs(actualStartTime);
       engineRef.current.stop();
       engineRef.current.seek(actualStartTime);
       stopAnimationLoop();
@@ -4328,7 +4358,7 @@ var WaveformPlaylistProvider = ({
       setIsPlaying(true);
       startAnimationLoop();
     }),
-    [startAnimationLoop, stopAnimationLoop]
+    [startAnimationLoop, stopAnimationLoop, setCurrentTimeRefs]
   );
   const pause = (0, import_react24.useCallback)(() => {
     if (!engineRef.current) return;
@@ -4336,28 +4366,28 @@ var WaveformPlaylistProvider = ({
     engineRef.current.pause();
     setIsPlaying(false);
     stopAnimationLoop();
-    currentTimeRef.current = pauseTime;
+    setCurrentTimeRefs(pauseTime);
     setCurrentTime(pauseTime);
-  }, [stopAnimationLoop, getPlaybackTime]);
+  }, [stopAnimationLoop, getPlaybackTime, setCurrentTimeRefs]);
   const stop = (0, import_react24.useCallback)(() => {
     if (!engineRef.current) return;
     engineRef.current.stop();
     setIsPlaying(false);
     stopAnimationLoop();
-    currentTimeRef.current = playStartPositionRef.current;
+    setCurrentTimeRefs(playStartPositionRef.current);
     setCurrentTime(playStartPositionRef.current);
     setActiveAnnotationId(null);
-  }, [stopAnimationLoop, setActiveAnnotationId]);
+  }, [stopAnimationLoop, setActiveAnnotationId, setCurrentTimeRefs]);
   const seekTo = (0, import_react24.useCallback)(
     (time) => {
       const clampedTime = Math.max(0, Math.min(time, duration));
-      currentTimeRef.current = clampedTime;
+      setCurrentTimeRefs(clampedTime);
       setCurrentTime(clampedTime);
       if (isPlaying && engineRef.current) {
         play(clampedTime);
       }
     },
-    [duration, isPlaying, play]
+    [duration, isPlaying, play, setCurrentTimeRefs]
   );
   const setTrackMute = (0, import_react24.useCallback)(
     (trackIndex, muted) => {
@@ -4418,7 +4448,7 @@ var WaveformPlaylistProvider = ({
   const setSelection = (0, import_react24.useCallback)(
     (start, end) => {
       setSelectionEngine(start, end);
-      currentTimeRef.current = start;
+      setCurrentTimeRefs(start);
       setCurrentTime(start);
       if (isPlaying && engineRef.current) {
         engineRef.current.stop();
@@ -4426,7 +4456,7 @@ var WaveformPlaylistProvider = ({
         engineRef.current.play(start);
       }
     },
-    [isPlaying, setSelectionEngine]
+    [isPlaying, setSelectionEngine, setCurrentTimeRefs]
   );
   const setScrollContainer = (0, import_react24.useCallback)((element) => {
     scrollContainerRef.current = element;
@@ -4456,9 +4486,11 @@ var WaveformPlaylistProvider = ({
       isPlaying,
       currentTime,
       currentTimeRef,
+      visualTimeRef,
       playbackStartTimeRef,
       audioStartPositionRef,
       getPlaybackTime,
+      getLookAhead,
       registerFrameCallback,
       unregisterFrameCallback
     }),
@@ -4466,9 +4498,11 @@ var WaveformPlaylistProvider = ({
       isPlaying,
       currentTime,
       currentTimeRef,
+      visualTimeRef,
       playbackStartTimeRef,
       audioStartPositionRef,
       getPlaybackTime,
+      getLookAhead,
       registerFrameCallback,
       unregisterFrameCallback
     ]
@@ -4511,10 +4545,10 @@ var WaveformPlaylistProvider = ({
   );
   const setCurrentTimeControl = (0, import_react24.useCallback)(
     (time) => {
-      currentTimeRef.current = time;
+      setCurrentTimeRefs(time);
       setCurrentTime(time);
     },
-    [currentTimeRef]
+    [setCurrentTimeRefs]
   );
   const setAutomaticScrollControl = (0, import_react24.useCallback)((enabled) => {
     setIsAutomaticScroll(enabled);
@@ -5402,6 +5436,7 @@ var import_react_dom = require("react-dom");
 var import_styled_components6 = __toESM(require("styled-components"));
 var import_playout6 = require("@waveform-playlist/playout");
 var import_ui_components9 = require("@waveform-playlist/ui-components");
+var import_core8 = require("@waveform-playlist/core");
 
 // src/components/AnimatedPlayhead.tsx
 var import_react30 = require("react");
@@ -5423,7 +5458,13 @@ var PlayheadLine = import_styled_components4.default.div.attrs((props) => ({
 `;
 var AnimatedPlayhead = ({ color = "#ff0000" }) => {
   const playheadRef = (0, import_react30.useRef)(null);
-  const { isPlaying, currentTimeRef, registerFrameCallback, unregisterFrameCallback } = usePlaybackAnimation();
+  const {
+    isPlaying,
+    currentTimeRef,
+    visualTimeRef,
+    registerFrameCallback,
+    unregisterFrameCallback
+  } = usePlaybackAnimation();
   const { samplesPerPixel, sampleRate, progressBarWidth } = usePlaylistData();
   (0, import_react30.useEffect)(() => {
     const id = "playhead";
@@ -5438,9 +5479,9 @@ var AnimatedPlayhead = ({ color = "#ff0000" }) => {
     return () => unregisterFrameCallback(id);
   }, [isPlaying, registerFrameCallback, unregisterFrameCallback]);
   (0, import_react30.useEffect)(() => {
-    var _a;
+    var _a, _b;
     if (!isPlaying && playheadRef.current) {
-      const time = (_a = currentTimeRef.current) != null ? _a : 0;
+      const time = (_b = (_a = visualTimeRef.current) != null ? _a : currentTimeRef.current) != null ? _b : 0;
       const position = time * sampleRate / samplesPerPixel;
       playheadRef.current.style.transform = `translate3d(${position}px, 0, 0)`;
     }
@@ -5511,7 +5552,13 @@ var ChannelWithProgress = (_a) => {
   const callbackId = (0, import_react31.useId)();
   const theme = (0, import_ui_components8.useTheme)();
   const { waveHeight } = (0, import_ui_components8.usePlaylistInfo)();
-  const { isPlaying, currentTimeRef, registerFrameCallback, unregisterFrameCallback } = usePlaybackAnimation();
+  const {
+    isPlaying,
+    currentTimeRef,
+    visualTimeRef,
+    registerFrameCallback,
+    unregisterFrameCallback
+  } = usePlaybackAnimation();
   const { samplesPerPixel, sampleRate } = usePlaylistData();
   const progressColor = (theme == null ? void 0 : theme.waveProgressColor) || "rgba(0, 0, 0, 0.1)";
   const clipPixelWidth = (0, import_core7.clipPixelWidth)(
@@ -5548,9 +5595,9 @@ var ChannelWithProgress = (_a) => {
     unregisterFrameCallback
   ]);
   (0, import_react31.useEffect)(() => {
-    var _a2;
+    var _a2, _b2;
     if (!isPlaying && progressRef.current) {
-      const currentTime = (_a2 = currentTimeRef.current) != null ? _a2 : 0;
+      const currentTime = (_b2 = (_a2 = visualTimeRef.current) != null ? _a2 : currentTimeRef.current) != null ? _b2 : 0;
       const currentSample = currentTime * sampleRate;
       const clipEndSample = clipStartSample + clipDurationSamples;
       let ratio = 0;
@@ -5658,25 +5705,28 @@ var ControlSlot = import_styled_components6.default.div.attrs((props) => ({
   ${(props) => props.$isSelected && `background: ${props.theme.selectedTrackControlsBackground};`}
 `;
 var CustomPlayhead = ({ renderPlayhead, color, samplesPerPixel, sampleRate }) => {
-  var _a;
+  var _a, _b;
   const {
     isPlaying,
     currentTimeRef,
+    visualTimeRef,
     playbackStartTimeRef,
     audioStartPositionRef,
     getPlaybackTime
   } = usePlaybackAnimation();
+  const visualTime = (_b = (_a = visualTimeRef.current) != null ? _a : currentTimeRef.current) != null ? _b : 0;
   return renderPlayhead({
-    position: ((_a = currentTimeRef.current) != null ? _a : 0) * sampleRate / samplesPerPixel,
+    position: visualTime * sampleRate / samplesPerPixel,
     color,
     isPlaying,
     currentTimeRef,
+    visualTimeRef,
     playbackStartTimeRef,
     audioStartPositionRef,
     samplesPerPixel,
     sampleRate,
     controlsOffset: 0,
-    getAudioContextTime: () => (0, import_playout6.getGlobalContext)().rawContext.currentTime,
+    getAudioContextTime: () => (0, import_playout6.getGlobalAudioContext)().currentTime,
     getPlaybackTime
   });
 };
@@ -5701,7 +5751,7 @@ var PlaylistVisualization = ({
 }) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
   const theme = (0, import_ui_components9.useTheme)();
-  const { isPlaying } = usePlaybackAnimation();
+  const { isPlaying, getLookAhead } = usePlaybackAnimation();
   const {
     selectionStart,
     selectionEnd,
@@ -6160,22 +6210,39 @@ var PlaylistVisualization = ({
                           clip.clipId
                         );
                       }),
-                      (recordingState == null ? void 0 : recordingState.isRecording) && recordingState.trackId === track.id && ((_d2 = recordingState.peaks[0]) == null ? void 0 : _d2.length) > 0 && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
-                        import_ui_components9.Clip,
-                        {
-                          clipId: "recording-preview",
-                          trackIndex,
-                          clipIndex: trackClipPeaks.length,
-                          trackName: "Recording...",
-                          startSample: recordingState.startSample,
-                          durationSamples: recordingState.durationSamples,
-                          samplesPerPixel,
-                          showHeader: showClipHeaders,
-                          disableHeaderDrag: true,
-                          isSelected: track.id === selectedTrackId,
-                          trackId: track.id,
-                          children: (mono ? recordingState.peaks.slice(0, 1) : recordingState.peaks).map(
-                            (channelPeaks, chIdx) => /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+                      (recordingState == null ? void 0 : recordingState.isRecording) && recordingState.trackId === track.id && ((_d2 = recordingState.peaks[0]) == null ? void 0 : _d2.length) > 0 && (() => {
+                        const audioCtx = (0, import_playout6.getGlobalAudioContext)();
+                        const outputLatency = "outputLatency" in audioCtx ? audioCtx.outputLatency : 0;
+                        const lookAhead = getLookAhead();
+                        const latencyOffsetSamples = (0, import_core8.audibleLatencySamples)(
+                          outputLatency,
+                          lookAhead,
+                          sampleRate
+                        );
+                        const latencyPixels = Math.floor(latencyOffsetSamples / samplesPerPixel);
+                        const skipPeakElements = latencyPixels * 2;
+                        const previewDuration = Math.max(
+                          0,
+                          recordingState.durationSamples - latencyOffsetSamples
+                        );
+                        const previewChannels = (mono ? recordingState.peaks.slice(0, 1) : recordingState.peaks).map(
+                          (channelPeaks) => skipPeakElements > 0 && skipPeakElements < channelPeaks.length ? channelPeaks.subarray(skipPeakElements) : channelPeaks
+                        );
+                        return /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+                          import_ui_components9.Clip,
+                          {
+                            clipId: "recording-preview",
+                            trackIndex,
+                            clipIndex: trackClipPeaks.length,
+                            trackName: "Recording...",
+                            startSample: recordingState.startSample,
+                            durationSamples: previewDuration,
+                            samplesPerPixel,
+                            showHeader: showClipHeaders,
+                            disableHeaderDrag: true,
+                            isSelected: track.id === selectedTrackId,
+                            trackId: track.id,
+                            children: previewChannels.map((channelPeaks, chIdx) => /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                               ChannelWithProgress,
                               {
                                 index: chIdx,
@@ -6184,14 +6251,14 @@ var PlaylistVisualization = ({
                                 length: Math.floor(channelPeaks.length / 2),
                                 isSelected: track.id === selectedTrackId,
                                 clipStartSample: recordingState.startSample,
-                                clipDurationSamples: recordingState.durationSamples
+                                clipDurationSamples: previewDuration
                               },
                               `${track.id}-recording-${chIdx}`
-                            )
-                          )
-                        },
-                        `${track.id}-recording`
-                      )
+                            ))
+                          },
+                          `${track.id}-recording`
+                        );
+                      })()
                     ]
                   },
                   track.id
@@ -7024,7 +7091,7 @@ var KeyboardShortcuts = ({
 var import_react40 = __toESM(require("react"));
 var import_react41 = require("@dnd-kit/react");
 var import_modifiers2 = require("@dnd-kit/abstract/modifiers");
-var import_core9 = require("@waveform-playlist/core");
+var import_core10 = require("@waveform-playlist/core");
 var import_ui_components12 = require("@waveform-playlist/ui-components");
 
 // src/modifiers/ClipCollisionModifier.ts
@@ -7053,7 +7120,7 @@ var ClipCollisionModifier = _ClipCollisionModifier;
 
 // src/modifiers/SnapToGridModifier.ts
 var import_abstract2 = require("@dnd-kit/abstract");
-var import_core8 = require("@waveform-playlist/core");
+var import_core9 = require("@waveform-playlist/core");
 var _SnapToGridModifier = class _SnapToGridModifier extends import_abstract2.Modifier {
   apply(operation) {
     const { transform, source } = operation;
@@ -7074,18 +7141,18 @@ var _SnapToGridModifier = class _SnapToGridModifier extends import_abstract2.Mod
     }
     const { snapTo, bpm, timeSignature, sampleRate } = this.options;
     if (snapTo === "off") return transform;
-    const gridTicks = snapTo === "bar" ? (0, import_core8.ticksPerBar)(timeSignature) : (0, import_core8.ticksPerBeat)(timeSignature);
+    const gridTicks = snapTo === "bar" ? (0, import_core9.ticksPerBar)(timeSignature) : (0, import_core9.ticksPerBeat)(timeSignature);
     if (startSample !== void 0) {
       const proposedSamples = startSample + transform.x * samplesPerPixel;
-      const proposedTicks = (0, import_core8.samplesToTicks)(proposedSamples, bpm, sampleRate);
-      const snappedTicks2 = (0, import_core8.snapToGrid)(proposedTicks, gridTicks);
-      const snappedSamples2 = (0, import_core8.ticksToSamples)(snappedTicks2, bpm, sampleRate);
+      const proposedTicks = (0, import_core9.samplesToTicks)(proposedSamples, bpm, sampleRate);
+      const snappedTicks2 = (0, import_core9.snapToGrid)(proposedTicks, gridTicks);
+      const snappedSamples2 = (0, import_core9.ticksToSamples)(snappedTicks2, bpm, sampleRate);
       return { x: (snappedSamples2 - startSample) / samplesPerPixel, y: 0 };
     }
     const deltaSamples = transform.x * samplesPerPixel;
-    const deltaTicks = (0, import_core8.samplesToTicks)(deltaSamples, bpm, sampleRate);
-    const snappedTicks = (0, import_core8.snapToGrid)(deltaTicks, gridTicks);
-    const snappedSamples = (0, import_core8.ticksToSamples)(snappedTicks, bpm, sampleRate);
+    const deltaTicks = (0, import_core9.samplesToTicks)(deltaSamples, bpm, sampleRate);
+    const snappedTicks = (0, import_core9.snapToGrid)(deltaTicks, gridTicks);
+    const snappedSamples = (0, import_core9.ticksToSamples)(snappedTicks, bpm, sampleRate);
     return { x: snappedSamples / samplesPerPixel, y: 0 };
   }
 };
@@ -7116,11 +7183,11 @@ var ClipInteractionProvider = ({
   const snapSamplePosition = (0, import_react40.useMemo)(() => {
     if (useBeatsSnap && beatsAndBars) {
       const { bpm, timeSignature, snapTo } = beatsAndBars;
-      const gridTicks = snapTo === "bar" ? (0, import_core9.ticksPerBar)(timeSignature) : (0, import_core9.ticksPerBeat)(timeSignature);
+      const gridTicks = snapTo === "bar" ? (0, import_core10.ticksPerBar)(timeSignature) : (0, import_core10.ticksPerBeat)(timeSignature);
       return (samplePos) => {
-        const ticks = (0, import_core9.samplesToTicks)(samplePos, bpm, sampleRate);
-        const snapped = (0, import_core9.snapToGrid)(ticks, gridTicks);
-        return (0, import_core9.ticksToSamples)(snapped, bpm, sampleRate);
+        const ticks = (0, import_core10.samplesToTicks)(samplePos, bpm, sampleRate);
+        const snapped = (0, import_core10.snapToGrid)(ticks, gridTicks);
+        return (0, import_core10.ticksToSamples)(snapped, bpm, sampleRate);
       };
     }
     if (useTimescaleSnap) {