@hyperframes/studio 0.6.97 → 0.6.98

package/src/player/components/TimelinePropertyRows.tsx

@@ -1,5 +1,6 @@
 import { memo } from "react";
 import type { KeyframeCacheEntry } from "../store/playerStore";
+import { KF_MIN_PCT, KF_MAX_PCT } from "./TimelineClipDiamonds";
 
 const SUB_TRACK_H = 24;
 const DIAMOND_SIZE = 6;
@@ -44,7 +45,9 @@ export const TimelinePropertyRows = memo(function TimelinePropertyRows({
   return (
     <div className="flex flex-col">
       {properties.map((prop) => {
-        const propKeyframes = keyframesData.keyframes.filter((kf) => prop in kf.properties);
+        const propKeyframes = keyframesData.keyframes
+          .filter((kf) => prop in kf.properties)
+          .filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT);
         if (propKeyframes.length === 0) return null;
 
         return (
@@ -67,7 +70,10 @@ export const TimelinePropertyRows = memo(function TimelinePropertyRows({
                 strokeWidth={1}
               />
               {propKeyframes.map((kf) => {
-                const x = (kf.percentage / 100) * clipWidthPx;
+                const x = Math.max(
+                  HALF,
+                  Math.min(clipWidthPx - HALF, (kf.percentage / 100) * clipWidthPx),
+                );
                 const y = SUB_TRACK_H / 2;
                 const key = `${elementId}:${kf.percentage}`;
                 const isKfSelected = selectedKeyframes.has(key);

package/src/player/components/TimelineRuler.tsx

@@ -2,6 +2,7 @@ import { memo } from "react";
 import type { TimelineTheme } from "./timelineTheme";
 import type { TimelineRangeSelection } from "./timelineEditing";
 import { GUTTER, RULER_H, formatTimelineTickLabel } from "./timelineLayout";
+import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 
 interface TimelineRulerProps {
   major: number[];
@@ -14,6 +15,7 @@ interface TimelineRulerProps {
   shiftHeld: boolean;
   rangeSelection: TimelineRangeSelection | null;
   theme: TimelineTheme;
+  beatAnalysis?: MusicBeatAnalysis | null;
 }
 
 export const TimelineRuler = memo(function TimelineRuler({
@@ -27,13 +29,25 @@ export const TimelineRuler = memo(function TimelineRuler({
   shiftHeld,
   rangeSelection,
   theme,
+  beatAnalysis,
 }: TimelineRulerProps) {
+  const beatTimes = beatAnalysis?.beatTimes ?? [];
+  const beatStrengths = beatAnalysis?.beatStrengths ?? [];
+
+  // Only draw beat lines when they'd be at least 5px apart
+  const avgBeatInterval =
+    beatTimes.length > 1
+      ? (beatTimes[beatTimes.length - 1]! - beatTimes[0]!) / (beatTimes.length - 1)
+      : null;
+  const showBeats = avgBeatInterval !== null && avgBeatInterval * pps >= 5;
+
   return (
     <>
-      {/* Grid lines */}
+      {/* Grid lines (major ticks + beat lines) — behind the tracks (background).
+          Opaque track rows hide them; only the beat dots show on tracks. */}
       <svg
         className="absolute pointer-events-none"
-        style={{ left: GUTTER, width: trackContentWidth }}
+        style={{ left: GUTTER, width: trackContentWidth, zIndex: 0 }}
         height={totalH}
       >
         {major.map((t) => {
@@ -50,6 +64,24 @@ export const TimelineRuler = memo(function TimelineRuler({
             />
           );
         })}
+        {showBeats &&
+          beatTimes.map((t, i) => {
+            const x = t * pps;
+            // Louder beats → brighter line. Gamma curve widens the contrast.
+            const strength = Math.pow(Math.min(1, beatStrengths[i] ?? 0.5), 2.2);
+            const opacity = 0.08 + strength * 0.62;
+            return (
+              <line
+                key={`b-${t}-${i}`}
+                x1={x}
+                y1={0}
+                x2={x}
+                y2={totalH}
+                stroke={`rgba(34, 197, 94, ${opacity.toFixed(3)})`}
+                strokeWidth="1"
+              />
+            );
+          })}
       </svg>
 
       {/* Ruler */}
@@ -64,11 +96,13 @@ export const TimelineRuler = memo(function TimelineRuler({
             </span>
           </div>
         )}
+
         {minor.map((t) => (
           <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps }}>
             <div className="w-px h-[3px]" style={{ background: theme.tickMinor }} />
           </div>
         ))}
+
         {major.map((t) => (
           <div
             key={`M-${t}`}

package/src/player/components/timelineEditing.ts

@@ -1,10 +1,7 @@
 import { formatTime } from "../lib/time";
+import { roundToCenti } from "../../utils/rounding";
 
-const TIME_PRECISION = 100;
-
-function roundToCentiseconds(value: number): number {
-  return Math.round(value * TIME_PRECISION) / TIME_PRECISION;
-}
+const roundToCentiseconds = roundToCenti;
 
 function clamp(value: number, min: number, max: number): number {
   return Math.min(Math.max(value, min), max);
@@ -114,6 +111,34 @@ export function resolveTimelineMove(
   };
 }
 
+/**
+ * Snap a keyframe's clip-relative percentage to the nearest beat within ~8px,
+ * mapping through composition time (pct → time → nearest beat → pct). Returns
+ * the percentage unchanged when no beat is in range, so dragging stays free
+ * between beats.
+ */
+export function snapKeyframePctToBeat(
+  el: { start: number; duration: number },
+  pct: number,
+  beatTimes: number[] | undefined,
+  pixelsPerSecond: number,
+): number {
+  if (!beatTimes || beatTimes.length === 0 || el.duration <= 0) return pct;
+  const t = el.start + (pct / 100) * el.duration;
+  const snapSecs = 8 / Math.max(pixelsPerSecond, 1);
+  let best = t;
+  let bestDist = snapSecs;
+  for (const bt of beatTimes) {
+    const d = Math.abs(bt - t);
+    if (d < bestDist) {
+      bestDist = d;
+      best = bt;
+    }
+  }
+  if (best === t) return pct;
+  return Math.max(0, Math.min(100, ((best - el.start) / el.duration) * 100));
+}
+
 export function resolveTimelineResize(
   input: TimelineResizeInput,
   edge: "start" | "end",

package/src/player/components/useTimelineClipDrag.ts

@@ -1,4 +1,4 @@
-import { useRef, useState, useCallback } from "react";
+import { useRef, useState, useCallback, useMemo } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import {
   resolveTimelineMove,
@@ -9,6 +9,64 @@ import {
 import { usePlayerStore } from "../store/playerStore";
 import type { TimelineElement } from "../store/playerStore";
 import { TRACK_H } from "./timelineLayout";
+import { isMusicTrack } from "../../utils/timelineInspector";
+import { mergeUserBeats } from "../../utils/beatEditing";
+
+const BEAT_SNAP_PX = 8;
+const EMPTY_BEAT_TIMES: number[] = [];
+
+function snapToNearestBeat(time: number, beatTimes: number[], thresholdSecs: number): number {
+  let best = time;
+  let bestDist = thresholdSecs;
+  for (const bt of beatTimes) {
+    const d = Math.abs(bt - time);
+    if (d < bestDist) {
+      bestDist = d;
+      best = bt;
+    }
+  }
+  return best;
+}
+
+/**
+ * Snap a moved clip so whichever edge (start or end) is nearest a beat lands on
+ * it, keeping the duration fixed. Returns the (clamped) start plus the beat time
+ * it snapped to (for the grid-line highlight), or `beat: null` when no edge is
+ * within threshold.
+ */
+function snapMoveStartToBeat(
+  start: number,
+  duration: number,
+  beatTimes: number[],
+  pixelsPerSecond: number,
+  timelineDuration: number,
+): { start: number; beat: number | null } {
+  if (beatTimes.length === 0) return { start, beat: null };
+  const snapSecs = BEAT_SNAP_PX / Math.max(pixelsPerSecond, 1);
+  const snappedStart = snapToNearestBeat(start, beatTimes, snapSecs);
+  const snappedEnd = snapToNearestBeat(start + duration, beatTimes, snapSecs);
+  const startMoved = snappedStart !== start;
+  const endMoved = snappedEnd !== start + duration;
+
+  let candidate = start;
+  let beat: number | null = null;
+  if (
+    startMoved &&
+    (!endMoved || Math.abs(snappedStart - start) <= Math.abs(snappedEnd - (start + duration)))
+  ) {
+    candidate = snappedStart;
+    beat = snappedStart;
+  } else if (endMoved) {
+    candidate = snappedEnd - duration;
+    beat = snappedEnd;
+  }
+
+  const maxStart = Math.max(0, timelineDuration - duration);
+  const clamped = Math.max(0, Math.min(maxStart, Math.round(candidate * 1000) / 1000));
+  // If clamping pulled the clip off the snap target, drop the highlight.
+  if (beat != null && Math.abs(clamped - candidate) > 1e-6) beat = null;
+  return { start: clamped, beat };
+}
 
 /* ── Shared state types ─────────────────────────────────────────── */
 export interface DraggedClipState {
@@ -23,6 +81,8 @@ export interface DraggedClipState {
   pointerOffsetY: number;
   previewStart: number;
   previewTrack: number;
+  /** Beat time the clip will snap to on drop, for the grid-line highlight. */
+  snapBeatTime: number | null;
   started: boolean;
 }
 
@@ -76,6 +136,36 @@ export function useTimelineClipDrag({
   setRangeSelectionRef,
 }: UseTimelineClipDragInput) {
   const updateElement = usePlayerStore((s) => s.updateElement);
+  const rawBeatTimes = usePlayerStore((s) => s.beatAnalysis?.beatTimes ?? EMPTY_BEAT_TIMES);
+  const rawBeatStrengths = usePlayerStore((s) => s.beatAnalysis?.beatStrengths ?? EMPTY_BEAT_TIMES);
+  const beatEdits = usePlayerStore((s) => s.beatEdits);
+  const musicStart = usePlayerStore((s) => s.elements.find(isMusicTrack)?.start ?? 0);
+  const musicPlaybackStart = usePlayerStore(
+    (s) => s.elements.find(isMusicTrack)?.playbackStart ?? 0,
+  );
+  const musicDuration = usePlayerStore((s) => s.elements.find(isMusicTrack)?.duration ?? 0);
+  const musicSrc = usePlayerStore((s) => s.elements.find(isMusicTrack)?.src ?? null);
+
+  const adjustedBeatTimes = useMemo(() => {
+    if (rawBeatTimes === EMPTY_BEAT_TIMES || musicDuration === 0) return EMPTY_BEAT_TIMES;
+    const merged = mergeUserBeats(rawBeatTimes, rawBeatStrengths, beatEdits, musicSrc);
+    const clipEnd = musicPlaybackStart + musicDuration;
+    const offset = musicStart - musicPlaybackStart;
+    return merged.times
+      .filter((t) => t >= musicPlaybackStart && t <= clipEnd)
+      .map((t) => Math.round((t + offset) * 1000) / 1000);
+  }, [
+    rawBeatTimes,
+    rawBeatStrengths,
+    beatEdits,
+    musicSrc,
+    musicStart,
+    musicPlaybackStart,
+    musicDuration,
+  ]);
+
+  const beatTimesRef = useRef<number[]>([]);
+  beatTimesRef.current = adjustedBeatTimes;
 
   const [draggedClip, setDraggedClip] = useState<DraggedClipState | null>(null);
   const draggedClipRef = useRef<DraggedClipState | null>(null);
@@ -118,13 +208,24 @@ export function useTimelineClipDrag({
         clientX,
         clientY,
       );
+      // The music track defines the beats, so it must not snap to itself.
+      const snap = isMusicTrack(drag.element)
+        ? { start: nextMove.start, beat: null }
+        : snapMoveStartToBeat(
+            nextMove.start,
+            drag.element.duration,
+            beatTimesRef.current,
+            ppsRef.current,
+            durationRef.current,
+          );
       return {
         ...drag,
         started: true,
         pointerClientX: clientX,
         pointerClientY: clientY,
-        previewStart: nextMove.start,
+        previewStart: snap.start,
         previewTrack: nextMove.track,
+        snapBeatTime: snap.beat,
       };
     },
     [scrollRef, ppsRef, durationRef, trackOrderRef],
@@ -220,14 +321,16 @@ export function useTimelineClipDrag({
             : Number.POSITIVE_INFINITY;
         const normalizedTag = resize.element.tag.toLowerCase();
         const canSeedPlaybackStart = normalizedTag === "audio" || normalizedTag === "video";
-        const nextResize = resolveTimelineResize(
+        const playbackRate = Math.max(resize.element.playbackRate ?? 1, 0.1);
+        const maxEnd = Math.min(durationRef.current, resize.element.start + sourceRemaining);
+        let nextResize = resolveTimelineResize(
           {
             start: resize.element.start,
             duration: resize.element.duration,
             originClientX: resize.originClientX,
             pixelsPerSecond: ppsRef.current,
             minStart: 0,
-            maxEnd: Math.min(durationRef.current, resize.element.start + sourceRemaining),
+            maxEnd,
             playbackStart:
               resize.edge === "start" && canSeedPlaybackStart
                 ? (resize.element.playbackStart ?? 0)
@@ -238,6 +341,54 @@ export function useTimelineClipDrag({
           e.clientX,
         );
 
+        // Snap edge to beat grid when beat analysis is available. The snap must
+        // stay inside the same limits resolveTimelineResize enforces, or it would
+        // push the edge past the available source media / composition end.
+        // The music track defines the beats, so it must not snap to itself.
+        const beatTimes = beatTimesRef.current;
+        if (beatTimes.length > 0 && !isMusicTrack(resize.element)) {
+          const snapSecs = BEAT_SNAP_PX / Math.max(ppsRef.current, 1);
+          if (resize.edge === "end") {
+            const edgeTime = nextResize.start + nextResize.duration;
+            const snapped = snapToNearestBeat(edgeTime, beatTimes, snapSecs);
+            // Stay within [start+minDuration, maxEnd] so the snap can't create a
+            // degenerate clip or run past the source/composition limit.
+            const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
+            if (snapped !== edgeTime && snapped <= maxEnd + 1e-6 && snappedDuration >= 0.05) {
+              nextResize = { ...nextResize, duration: snappedDuration };
+            }
+          } else {
+            const snapped = snapToNearestBeat(nextResize.start, beatTimes, snapSecs);
+            const delta = nextResize.start - snapped; // >0 when snapping left
+            // Leftward snap reveals more source; cap so playbackStart can't go < 0.
+            const maxLeftDelta =
+              nextResize.playbackStart != null
+                ? nextResize.playbackStart / playbackRate
+                : Number.POSITIVE_INFINITY;
+            // Also require the resulting duration to stay >= minDuration so a
+            // rightward snap (delta < 0) can't collapse the clip to zero/negative.
+            const snappedDuration = Math.round((nextResize.duration + delta) * 1000) / 1000;
+            if (
+              snapped !== nextResize.start &&
+              snapped >= 0 &&
+              delta <= maxLeftDelta + 1e-6 &&
+              snappedDuration >= 0.05
+            ) {
+              nextResize = {
+                ...nextResize,
+                start: snapped,
+                duration: snappedDuration,
+                playbackStart:
+                  nextResize.playbackStart != null
+                    ? Math.round(
+                        Math.max(0, nextResize.playbackStart - delta * playbackRate) * 1000,
+                      ) / 1000
+                    : undefined,
+              };
+            }
+          }
+        }
+
         setResizingClip((prev) =>
           prev
             ? {

package/src/player/components/useTimelinePlayhead.ts

@@ -1,4 +1,4 @@
-import { useRef, useCallback, useEffect } from "react";
+import { useRef, useCallback, useEffect, useLayoutEffect } from "react";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
@@ -54,6 +54,33 @@ export function useTimelinePlayhead({
 }: UseTimelinePlayheadInput) {
   const dragScrollRaf = useRef(0);
   const previousZoomModeRef = useRef<ZoomMode | null>(zoomMode);
+  // Center-anchored magnify: keep the time at the viewport center fixed when
+  // the zoom level (pps) changes via the toolbar / slider. The pinch handler
+  // anchors at the cursor instead, so it opts out via `skipCenterAnchorRef`.
+  const previousAnchorPpsRef = useRef(pps);
+  const skipCenterAnchorRef = useRef(false);
+
+  useLayoutEffect(() => {
+    const scroll = scrollRef.current;
+    const prevPps = previousAnchorPpsRef.current;
+    previousAnchorPpsRef.current = pps;
+    // Always consume the skip flag, even when pps didn't change — otherwise a
+    // pinch that produced no pps change (already at the zoom clamp) would strand
+    // it true and the next toolbar zoom would wrongly skip center-anchoring.
+    const skip = skipCenterAnchorRef.current;
+    skipCenterAnchorRef.current = false;
+    if (!scroll || pps === prevPps || skip) return;
+    const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
+      pointerX: scroll.clientWidth / 2,
+      currentScrollLeft: scroll.scrollLeft,
+      gutter: GUTTER,
+      currentPixelsPerSecond: prevPps,
+      nextPixelsPerSecond: pps,
+      duration: durationRef.current,
+    });
+    const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+    scroll.scrollLeft = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft));
+  }, [pps, scrollRef, durationRef]);
 
   const syncPlayheadPosition = useCallback(
     (time: number) => {
@@ -169,6 +196,8 @@ export function useTimelinePlayhead({
         nextPixelsPerSecond: nextPps,
         duration: durationRef.current,
       });
+      // Pinch anchors at the cursor (below), so skip the center-anchor effect.
+      skipCenterAnchorRef.current = true;
       setZoomMode("manual");
       setManualZoomPercent(nextZoomPercent);
       requestAnimationFrame(() => {

package/src/player/hooks/useTimelinePlayer.ts

@@ -41,9 +41,30 @@ import {
   setPreviewPlaybackRate,
   shouldMutePreviewAudio,
 } from "../lib/timelineIframeHelpers";
-import { probeMediaUrl, getCachedProbe } from "../lib/mediaProbe";
+import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
+import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 
+/**
+ * Whether the derived elements differ from the current ones in any field that
+ * affects rendering (identity, timing, track, or source length) — used to skip
+ * redundant store writes.
+ */
+function timelineElementsChanged(prev: TimelineElement[], next: TimelineElement[]): boolean {
+  if (next.length !== prev.length) return true;
+  return next.some((el, i) => {
+    const p = prev[i];
+    return (
+      !p ||
+      el.id !== p.id ||
+      el.start !== p.start ||
+      el.duration !== p.duration ||
+      el.track !== p.track ||
+      el.sourceDuration !== p.sourceDuration
+    );
+  });
+}
+
 export function useTimelinePlayer() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const rafRef = useRef<number>(0);
@@ -65,27 +86,19 @@ export function useTimelinePlayer() {
     (elements: TimelineElement[], nextDuration?: number) => {
       const state = usePlayerStore.getState();
       const resolvedDuration = nextDuration ?? state.duration;
-      const mergedElements = mergeTimelineElementsPreservingDowngrades(
-        state.elements,
-        elements,
-        state.duration,
-        resolvedDuration,
+      // applyCachedSourceDurations re-applies the cached probe duration: re-derived
+      // elements (e.g. after a clip move) can arrive without sourceDuration, which
+      // otherwise makes trimmed waveforms lose their window.
+      const mergedElements = applyCachedSourceDurations(
+        mergeTimelineElementsPreservingDowngrades(
+          state.elements,
+          elements,
+          state.duration,
+          resolvedDuration,
+        ),
       );
 
-      const elementsChanged =
-        mergedElements.length !== state.elements.length ||
-        mergedElements.some((el, i) => {
-          const prev = state.elements[i];
-          return (
-            !prev ||
-            el.id !== prev.id ||
-            el.start !== prev.start ||
-            el.duration !== prev.duration ||
-            el.track !== prev.track
-          );
-        });
-
-      if (elementsChanged) {
+      if (timelineElementsChanged(state.elements, mergedElements)) {
         setElements(mergedElements);
       }
       if (
@@ -99,31 +112,17 @@ export function useTimelinePlayer() {
         setTimelineReady(true);
       }
 
-      // Asynchronously enrich media elements missing sourceDuration via mediabunny.
-      // The probe reads file headers only — no full decode — so this is cheap.
-      const needsProbe = mergedElements.filter(
-        (el) =>
-          el.src &&
-          el.sourceDuration == null &&
-          ["video", "audio"].includes(el.tag.toLowerCase()) &&
-          !getCachedProbe(el.src),
-      );
-      if (needsProbe.length > 0) {
-        void Promise.allSettled(
-          needsProbe.map(async (el) => {
-            const result = await probeMediaUrl(el.src!);
-            if (!result) return;
-            const key = el.key ?? el.id;
-            usePlayerStore.setState((state) => {
-              const idx = state.elements.findIndex((e) => (e.key ?? e.id) === key);
-              if (idx === -1 || state.elements[idx].sourceDuration != null) return {};
-              const patched = state.elements.slice();
-              patched[idx] = { ...state.elements[idx], sourceDuration: result.duration };
-              return { elements: patched };
-            });
-          }),
-        );
-      }
+      // Asynchronously enrich media elements still missing sourceDuration
+      // (header-only probe, cheap), applying each resolved value to the store.
+      void probeMissingSourceDurations(mergedElements, (key, durationSeconds) => {
+        usePlayerStore.setState((state) => {
+          const idx = state.elements.findIndex((e) => (e.key ?? e.id) === key);
+          if (idx === -1 || state.elements[idx].sourceDuration != null) return {};
+          const patched = state.elements.slice();
+          patched[idx] = { ...state.elements[idx], sourceDuration: durationSeconds };
+          return { elements: patched };
+        });
+      });
     },
     [setElements, setTimelineReady, setDuration],
   );
@@ -280,6 +279,7 @@ export function useTimelinePlayer() {
   const play = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
+    stopScrubPreviewAudio();
     const adapter = getAdapter();
     if (!adapter) return;
     if (adapter.getTime() >= adapter.getDuration()) {
@@ -392,6 +392,7 @@ export function useTimelinePlayer() {
       adapter.seek(nextTime, options);
       liveTime.notify(nextTime); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
+      if (!shouldResumeAfterSeek && !keepPlaying) scrubMusicAtSeek(iframeRef.current, nextTime);
       if (shouldResumeAfterSeek) {
         stopRAFLoop();
         applyPlaybackRate(usePlayerStore.getState().playbackRate);
@@ -557,6 +558,7 @@ export function useTimelinePlayer() {
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       stopRAFLoop();
       stopReverseLoop();
+      stopScrubPreviewAudio();
       releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
       if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
     };

package/src/player/lib/mediaProbe.ts

@@ -1,4 +1,4 @@
-export interface MediaProbeResult {
+interface MediaProbeResult {
   duration: number;
   width?: number;
   height?: number;
@@ -61,11 +61,54 @@ async function probeOne(url: string): Promise<MediaProbeResult | null> {
   }
 }
 
-export function getCachedProbe(url: string): MediaProbeResult | undefined {
+function getCachedProbe(url: string): MediaProbeResult | undefined {
   return cache.get(normalizeUrl(url));
 }
 
-export async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
+/**
+ * Re-apply the cached probe `sourceDuration` to media elements that arrive
+ * without it. Re-deriving the timeline (e.g. after a clip move) produces fresh
+ * objects whose duration the DOM scan may not have, and the async probe skips
+ * already-cached srcs — so without this, trimmed waveforms lose their window.
+ */
+export function applyCachedSourceDurations<
+  T extends { src?: string; tag: string; sourceDuration?: number },
+>(elements: T[]): T[] {
+  return elements.map((el) => {
+    const tag = el.tag.toLowerCase();
+    if (!el.src || el.sourceDuration != null || (tag !== "audio" && tag !== "video")) return el;
+    const cached = getCachedProbe(el.src);
+    return cached?.duration && cached.duration > 0
+      ? { ...el, sourceDuration: cached.duration }
+      : el;
+  });
+}
+
+/**
+ * Probe (header-only, cheap) any media elements still missing sourceDuration
+ * after the cache pass, applying each resolved duration via `apply(key, secs)`.
+ * Skips already-cached srcs.
+ */
+export async function probeMissingSourceDurations<
+  T extends { src?: string; tag: string; sourceDuration?: number; key?: string; id: string },
+>(elements: T[], apply: (key: string, durationSeconds: number) => void): Promise<void> {
+  const needs = elements.filter(
+    (el) =>
+      el.src &&
+      el.sourceDuration == null &&
+      ["video", "audio"].includes(el.tag.toLowerCase()) &&
+      !getCachedProbe(el.src),
+  );
+  if (needs.length === 0) return;
+  await Promise.allSettled(
+    needs.map(async (el) => {
+      const result = await probeMediaUrl(el.src!);
+      if (result) apply(el.key ?? el.id, result.duration);
+    }),
+  );
+}
+
+async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
   const key = normalizeUrl(url);
   const cached = cache.get(key);
   if (cached) return cached;

package/src/player/lib/playbackScrub.ts

@@ -0,0 +1,16 @@
+import { usePlayerStore } from "../store/playerStore";
+import { isMusicTrack } from "../../utils/timelineInspector";
+import { scrubPreviewAudio, stopScrubPreviewAudio } from "./timelineIframeHelpers";
+
+export { stopScrubPreviewAudio };
+
+// Scrub the music track's audio at a seeked composition time (paused-seek only).
+// Skipped when audio is muted or the time falls outside the music clip.
+export function scrubMusicAtSeek(iframe: HTMLIFrameElement | null, nextTime: number): void {
+  const s = usePlayerStore.getState();
+  const music = s.elements.find(isMusicTrack);
+  if (!music || s.audioMuted) return;
+  const rel = nextTime - music.start;
+  const audioFileTime = rel >= 0 && rel <= music.duration ? (music.playbackStart ?? 0) + rel : null;
+  scrubPreviewAudio(iframe, audioFileTime, music.domId ?? music.id);
+}

package/src/player/lib/timelineDOM.ts

@@ -115,6 +115,8 @@ export function createTimelineElementFromManifestClip(params: {
 
   if (hostEl) {
     applyMediaMetadataFromElement(entry, hostEl);
+    const timelineRole = hostEl.getAttribute("data-timeline-role");
+    if (timelineRole) entry.timelineRole = timelineRole;
   }
   if (clip.assetUrl) entry.src = clip.assetUrl;
   if (clip.kind === "composition" && clip.compositionId) {
@@ -286,17 +288,23 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       if (mediaEl.tagName === "IMG") {
         entry.tag = "img";
       }
-      const src = mediaEl.getAttribute("src");
-      if (src) entry.src = src;
       const vol = el.getAttribute("data-volume") ?? mediaEl.getAttribute("data-volume");
       if (vol) entry.volume = parseFloat(vol);
       applyMediaMetadataFromElement(entry, el);
+      // Override AFTER the helper (which sets the raw relative attribute) so the
+      // resolved absolute URL wins — the Studio can then fetch the asset
+      // regardless of whether the attribute value was relative or absolute.
+      const resolvedSrc = (mediaEl as HTMLMediaElement | HTMLImageElement).src || undefined;
+      if (resolvedSrc) entry.src = resolvedSrc;
     }
 
     if (el.hasAttribute("data-timeline-locked")) {
       entry.timelineLocked = true;
     }
 
+    const timelineRole = el.getAttribute("data-timeline-role");
+    if (timelineRole) entry.timelineRole = timelineRole;
+
     // Sub-compositions
     const compSrc =
       el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");