fix(core,studio): bound trimmed audio playback to the clip window

Trimmed audio played to the source file's natural end instead of
stopping at the clip edge, on every audio path:

- WebAudio (the audible path in Studio): schedulePlayback now passes
  the clip's data-duration as the third start() arg, so the decoded
  buffer stops at the trimmed edge instead of running to the file end.
- Runtime element gating: the duration resolver caps each clip by its
  own data-duration (min of source length, host window, authored
  duration), so a trimmed <audio>/<video> element pauses at its edge.

Studio trim UX:

- Resize live-patches the media-start/playback-start offset, so a
  start-edge drag trims into the source instead of only repositioning
  the clip.
- AudioWaveform windows the rendered peaks to the trimmed slice so the
  waveform tracks the clip edges.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>

Author: vanceingalls

packages/core/src/runtime/init.ts

@@ -1469,10 +1469,18 @@ export function initSandboxRuntimeModular(): void {
           Number.isFinite(element.duration) && element.duration > mediaStart
             ? Math.max(0, element.duration - mediaStart)
             : null;
-        if (sourceDuration != null && hostRemaining != null) {
-          return Math.min(sourceDuration, hostRemaining);
-        }
-        return sourceDuration ?? hostRemaining;
+        // The element's own data-duration is an explicit clip-length trim
+        // (the studio writes it when you drag the clip edge). It must bound
+        // playback so a trimmed track stops at its edge instead of running on
+        // to the source-file or host-composition end. Absent → no cap (an
+        // untrimmed clip plays its natural source length).
+        const ownDuration = Number.parseFloat(element.dataset.duration ?? "");
+        const explicitDuration =
+          Number.isFinite(ownDuration) && ownDuration > 0 ? ownDuration : null;
+        const candidates = [sourceDuration, hostRemaining, explicitDuration].filter(
+          (value): value is number => value != null,
+        );
+        return candidates.length > 0 ? Math.min(...candidates) : null;
       },
     });
     // Attach probed volume keyframes to clips so syncRuntimeMedia can use the
@@ -2168,6 +2176,13 @@ export function initSandboxRuntimeModular(): void {
           Number.parseFloat(rawEl.dataset.playbackStart ?? rawEl.dataset.mediaStart ?? "0") || 0;
         const volumeAttr = Number.parseFloat(rawEl.dataset.volume ?? "");
         const vol = Number.isFinite(volumeAttr) ? volumeAttr : 1;
+        // The clip's authored window bounds the WebAudio buffer so a trimmed
+        // clip stops at its edge instead of running to the source's end.
+        const durationAttr = Number.parseFloat(rawEl.dataset.duration ?? "");
+        const clipDuration =
+          Number.isFinite(durationAttr) && durationAttr > 0
+            ? durationAttr
+            : Number.POSITIVE_INFINITY;
         void webAudio.decodeAudioElement(rawEl).then((buffer) => {
           if (!buffer || !clock.isPlaying()) return;
           void webAudio.schedulePlayback(
@@ -2179,6 +2194,7 @@ export function initSandboxRuntimeModular(): void {
             vol * state.bridgeVolume,
             gen,
             state.playbackRate,
+            clipDuration,
           );
         });
       }

packages/core/src/runtime/webAudioTransport.test.ts

@@ -171,6 +171,43 @@ describe("WebAudioTransport", () => {
     });
   });
 
+  describe("clip duration bound (trim)", () => {
+    it("bounds an in-progress clip to its remaining authored window", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      // compStart=5, mediaStart=0, compTime=8 → elapsed=3; clipDuration=10 → 7 left
+      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, 8, 1, gen, 1, 10);
+      expect(mock.startFn).toHaveBeenCalledWith(0, 3, 7);
+    });
+
+    it("bounds a future clip to its full authored window", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      // compStart=10, mediaStart=1.5, compTime=2 → elapsed=-8 → delay 8; clipDuration=4
+      await transport.schedulePlayback(mockEl, mockBuffer, 10, 1.5, 2, 1, gen, 1, 4);
+      expect(mock.startFn).toHaveBeenCalledWith(108, 1.5, 4);
+    });
+
+    it("does not schedule a clip whose window has already elapsed", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      // elapsed=15 > clipDuration=10 → nothing to play
+      const result = await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, 20, 1, gen, 1, 10);
+      expect(result).toBeNull();
+      expect(mock.startFn).not.toHaveBeenCalled();
+    });
+
+    it("scales the bound by playback rate (buffer seconds)", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      // rate=2, clipDuration=10 → clipSourceLen=20; elapsed=3 → 17 buffer seconds left
+      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, 8, 1, gen, 2, 10);
+      expect(mock.startFn).toHaveBeenCalledWith(0, 3, 17);
+    });
+
+    it("plays unbounded when clipDuration is omitted (legacy behavior)", async () => {
+      const { transport, mock, gen } = setupTransport(100);
+      await transport.schedulePlayback(mockEl, mockBuffer, 5, 0, 8, 1, gen);
+      expect(mock.startFn).toHaveBeenCalledWith(0, 3);
+    });
+  });
+
   describe("playback rate", () => {
     it("sets sourceNode.playbackRate.value when rate is provided", async () => {
       const { transport, mock, gen } = setupTransport(100);

packages/core/src/runtime/webAudioTransport.ts

@@ -5,6 +5,42 @@ function normalizeRate(rate: number): number {
   return rate;
 }
 
+/**
+ * Start a buffer source, bounding it to the clip's authored window
+ * (`data-duration`) so a trimmed clip stops at its edge instead of running the
+ * buffer to the source file's natural end. `clipSourceLen` is the clip span in
+ * buffer seconds; the third `start()` arg is the portion to play from the
+ * offset. An infinite `clipDuration` plays unbounded (legacy behavior).
+ *
+ * Returns false when the playhead is already past the clip end (nothing to
+ * play); the caller should discard the source.
+ */
+function startBoundedSource(
+  node: AudioBufferSourceNode,
+  opts: {
+    elapsed: number;
+    mediaStart: number;
+    scheduledAt: number;
+    safeRate: number;
+    clipDuration: number;
+  },
+): boolean {
+  const { elapsed, mediaStart, scheduledAt, safeRate, clipDuration } = opts;
+  const hasBound = Number.isFinite(clipDuration) && clipDuration > 0;
+  const clipSourceLen = clipDuration * safeRate;
+  if (elapsed >= 0) {
+    const remaining = clipSourceLen - elapsed;
+    if (hasBound && remaining <= 0) return false;
+    if (hasBound) node.start(0, elapsed + mediaStart, remaining);
+    else node.start(0, elapsed + mediaStart);
+    return true;
+  }
+  const delay = -elapsed / safeRate;
+  if (hasBound) node.start(scheduledAt + delay, mediaStart, clipSourceLen);
+  else node.start(scheduledAt + delay, mediaStart);
+  return true;
+}
+
 export type ScheduledSource = {
   el: HTMLMediaElement;
   sourceNode: AudioBufferSourceNode;
@@ -92,6 +128,7 @@ export class WebAudioTransport {
     volume: number,
     generation: number,
     rate = 1,
+    clipDuration = Number.POSITIVE_INFINITY,
   ): Promise<ScheduledSource | null> {
     if (!this._ctx || !this._masterGain) return null;
     if (generation !== this._playGeneration) return null;
@@ -119,11 +156,19 @@ export class WebAudioTransport {
       this._rateAnchorCtx = scheduledAt;
       this._rateAnchorComp = compositionTime;
 
-      if (elapsed >= 0) {
-        sourceNode.start(0, elapsed + mediaStart);
-      } else {
-        const delay = -elapsed / safeRate;
-        sourceNode.start(scheduledAt + delay, mediaStart);
+      if (
+        !startBoundedSource(sourceNode, {
+          elapsed,
+          mediaStart,
+          scheduledAt,
+          safeRate,
+          clipDuration,
+        })
+      ) {
+        // Playhead already past the clip end — discard the nodes we built.
+        sourceNode.disconnect();
+        gainNode.disconnect();
+        return null;
       }
 
       const priorMuted = el.muted;

packages/studio/src/hooks/useRenderClipContent.ts

@@ -22,6 +22,49 @@ export function normalizeCompositionSrc(
   return compSrc;
 }
 
+/** Resolve a media src to its project-relative preview path, or null. */
+function resolvePreviewRelative(src: string | undefined, pid: string): string | null {
+  if (!src) return null;
+  if (!src.startsWith("http")) return src;
+  const base = `/api/projects/${pid}/preview/`;
+  const idx = src.indexOf(base);
+  return idx !== -1 ? decodeURIComponent(src.slice(idx + base.length)) : null;
+}
+
+/**
+ * The trimmed source slice as start/end fractions (0–1) of the source, so the
+ * waveform can window its peaks to the clip edges. Undefined when the source
+ * length is unknown (renders full).
+ */
+function trimFractions(el: TimelineElement): { start?: number; end?: number } {
+  const sourceDur = el.sourceDuration;
+  if (sourceDur == null || sourceDur <= 0) return {};
+  const mediaStart = el.playbackStart ?? 0;
+  const rate = el.playbackRate ?? 1;
+  const start = Math.max(0, Math.min(1, mediaStart / sourceDur));
+  const end = Math.max(start, Math.min(1, (mediaStart + el.duration * rate) / sourceDur));
+  return { start, end };
+}
+
+/**
+ * Build the waveform element for an audio clip, windowing the rendered peaks to
+ * the trimmed source slice so the bars track the clip edges.
+ */
+function renderAudioClip(el: TimelineElement, pid: string, labelColor: string): ReactNode {
+  const srcRelative = resolvePreviewRelative(el.src, pid);
+  const audioUrl = srcRelative ? `/api/projects/${pid}/preview/${srcRelative}` : (el.src ?? "");
+  const waveformUrl = srcRelative ? `/api/projects/${pid}/waveform/${srcRelative}` : undefined;
+  const { start, end } = trimFractions(el);
+  return createElement(AudioWaveform, {
+    audioUrl,
+    waveformUrl,
+    label: getTimelineElementLabel(el),
+    labelColor,
+    trimStartFraction: start,
+    trimEndFraction: end,
+  });
+}
+
 interface UseRenderClipContentOptions {
   projectIdRef: { current: string | null };
   compIdToSrc: Map<string, string>;
@@ -36,6 +79,8 @@ export function useRenderClipContent({
   effectiveTimelineDuration,
 }: UseRenderClipContentOptions) {
   return useCallback(
+    // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
+    // fallow-ignore-next-line complexity
     (el: TimelineElement, style: { clip: string; label: string }): ReactNode => {
       const pid = projectIdRef.current;
       if (!pid) return null;
@@ -88,27 +133,7 @@ export function useRenderClipContent({
 
       // Audio clips — waveform visualization
       if (el.tag === "audio") {
-        const previewBase = `/api/projects/${pid}/preview/`;
-        const previewIdx = el.src?.startsWith("http") ? el.src.indexOf(previewBase) : -1;
-        const srcRelative = el.src
-          ? previewIdx !== -1
-            ? decodeURIComponent(el.src.slice(previewIdx + previewBase.length))
-            : el.src.startsWith("http")
-              ? null
-              : el.src
-          : null;
-        const audioUrl = srcRelative
-          ? `/api/projects/${pid}/preview/${srcRelative}`
-          : (el.src ?? "");
-        const waveformUrl = srcRelative
-          ? `/api/projects/${pid}/waveform/${srcRelative}`
-          : undefined;
-        return createElement(AudioWaveform, {
-          audioUrl,
-          waveformUrl,
-          label: getTimelineElementLabel(el),
-          labelColor: style.label,
-        });
+        return renderAudioClip(el, pid, style.label);
       }
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {

packages/studio/src/hooks/useTimelineEditing.ts

@@ -143,10 +143,21 @@ export function useTimelineEditing({
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
     ) => {
-      patchIframeDomTiming(previewIframeRef.current, element, [
+      const liveAttrs: Array<[string, string]> = [
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
-      ]);
+      ];
+      // A start-edge trim advances the media-start offset (skips into the
+      // source). Patch it live too — otherwise the iframe keeps the old offset
+      // and the clip only repositions instead of trimming the audio.
+      if (updates.playbackStart != null) {
+        const liveAttr =
+          element.playbackStartAttr === "playback-start"
+            ? "data-playback-start"
+            : "data-media-start";
+        liveAttrs.push([liveAttr, formatTimelineAttributeNumber(updates.playbackStart)]);
+      }
+      patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
       return enqueueEdit(element, "Resize timeline clip", (original, target) => {
         const pbs = resolveResizePlaybackStart(original, target, element, updates);
         let patched = applyPatchByTarget(original, target, {
@@ -173,6 +184,8 @@ export function useTimelineEditing({
   );
 
   const handleTimelineElementDelete = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (element: TimelineElement) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -247,6 +260,8 @@ export function useTimelineEditing({
   );
 
   const handleTimelineAssetDrop = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (
       assetPath: string,
       placement: Pick<TimelineElement, "start" | "track">,
@@ -329,6 +344,8 @@ export function useTimelineEditing({
   );
 
   const handleTimelineFileDrop = useCallback(
+    // Pre-existing handler complexity, unchanged by this PR.
+    // fallow-ignore-next-line complexity
     async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");

packages/studio/src/player/components/AudioWaveform.tsx

@@ -5,6 +5,17 @@ interface AudioWaveformProps {
   waveformUrl?: string;
   label: string;
   labelColor: string;
+  /**
+   * Fraction (0–1) of the source the clip starts at, after the media-start
+   * trim. Defaults to 0 (no front trim).
+   */
+  trimStartFraction?: number;
+  /**
+   * Fraction (0–1) of the source the clip ends at. Defaults to 1 (no tail
+   * trim). Together these window the rendered peaks to the trimmed slice so the
+   * waveform tracks the clip edges instead of squeezing the whole file in.
+   */
+  trimEndFraction?: number;
 }
 
 const BAR_W = 2;
@@ -62,6 +73,8 @@ export const AudioWaveform = memo(function AudioWaveform({
   waveformUrl,
   label,
   labelColor,
+  trimStartFraction,
+  trimEndFraction,
 }: AudioWaveformProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const barsRef = useRef<HTMLDivElement | null>(null);
@@ -116,20 +129,28 @@ export const AudioWaveform = memo(function AudioWaveform({
     const barsEl = barsRef.current;
     if (!container || !barsEl || !peaks) return;
 
+    // Window the peaks to the trimmed slice [start, end) of the source so the
+    // bars track the clip edges. Clamp to a valid, non-empty range.
+    const winStart = Math.max(0, Math.min(1, trimStartFraction ?? 0));
+    const winEnd = Math.max(winStart, Math.min(1, trimEndFraction ?? 1));
+    const lo = Math.floor(winStart * peaks.length);
+    const hi = Math.max(lo + 1, Math.ceil(winEnd * peaks.length));
+    const span = hi - lo;
+
     const w = container.clientWidth || 400;
-    const barCount = Math.min(Math.floor(w / STEP), peaks.length);
+    const barCount = Math.min(Math.floor(w / STEP), span);
 
     let html = "";
     for (let i = 0; i < barCount; i++) {
-      // Map bar index to peak index (resample)
-      const peakIdx = Math.floor((i / barCount) * peaks.length);
+      // Map bar index to peak index within the windowed range (resample)
+      const peakIdx = lo + Math.floor((i / barCount) * span);
       const amp = peaks[peakIdx] ?? 0;
       const pct = Math.max(3, Math.round(amp * 100));
       const opacity = (0.45 + amp * 0.4).toFixed(2);
       html += `<div style="position:absolute;bottom:0;left:${i * STEP}px;width:${BAR_W}px;height:${pct}%;background:rgba(75,163,210,${opacity})"></div>`;
     }
     barsEl.innerHTML = html;
-  }, [peaks]);
+  }, [peaks, trimStartFraction, trimEndFraction]);
 
   // Observe container size and redraw
   const setContainerRef = useCallback(