@hyperframes/studio 0.8.6 → 0.8.8

package/src/hooks/useCaptionDetection.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useCaptionStore } from "../captions/store";
 import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
 import { useCaptionSync } from "../captions/hooks/useCaptionSync";
@@ -25,6 +25,24 @@ export function useCaptionDetection({
   captionSync,
   setRightCollapsed,
 }: UseCaptionDetectionParams) {
+  // Switching compositions must drop the previous comp's caption state — a
+  // stale model + full-canvas overlay otherwise blocks normal element editing
+  // on the new composition (and edit mode could never be exited).
+  const prevCompPathRef = useRef<string | null>(activeCompPath);
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (prevCompPathRef.current !== activeCompPath) {
+      prevCompPathRef.current = activeCompPath;
+      const store = useCaptionStore.getState();
+      if (store.model || store.isEditMode) {
+        // Flush the last debounced caption edit before the reset destroys the
+        // model — otherwise a save landing after the switch writes nothing.
+        store.retrySave?.();
+        store.reset();
+      }
+    }
+  }, [activeCompPath]);
+
   // eslint-disable-next-line no-restricted-syntax
   useEffect(() => {
     if (!projectId) return;
@@ -32,7 +50,9 @@ export function useCaptionDetection({
     let activating = false;
 
     const tryActivateCaptions = () => {
-      if (useCaptionStore.getState().isEditMode || activating) {
+      const captionState = useCaptionStore.getState();
+      // `dismissed` = user explicitly exited caption editing; don't re-trap them.
+      if (captionState.isEditMode || captionState.dismissed || activating) {
         return;
       }
 

package/src/hooks/useDomEditCommits.test.tsx

@@ -1376,6 +1376,30 @@ describe("useDomEditCommits attribute persist handling", () => {
     }
   });
 
+  it("sets and removes data-audio-group like any other data attribute", async () => {
+    stubPatchFetch({ ok: true, changed: true, matched: true });
+    const { iframe, element } = createPreviewElement();
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomAttributeLiveCommit("audio-group", "voiceover", undefined, {
+          previewOnly: true,
+        });
+      });
+      expect(element.getAttribute("data-audio-group")).toBe("voiceover");
+
+      await act(async () => {
+        await rendered.hook.handleDomAttributeLiveCommit("audio-group", "", undefined, {
+          previewOnly: true,
+        });
+      });
+      expect(element.getAttribute("data-audio-group")).toBeNull();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
   it("keeps a data-attribute commit on success", async () => {
     stubPatchFetch({
       ok: true,

package/src/hooks/useEffectiveTimelineDuration.ts

@@ -0,0 +1,20 @@
+import { useMemo } from "react";
+import type { TimelineElement } from "../player/store/timelineElement";
+
+/**
+ * The stored `duration` lags a moment behind an edit that pushes an element
+ * past it (drag, trim, paste) — this is the actual end of the timeline, the
+ * later of the stored duration and the furthest element's end.
+ */
+export function useEffectiveTimelineDuration(
+  timelineDuration: number,
+  timelineElements: readonly TimelineElement[],
+): number {
+  return useMemo(() => {
+    const maxEnd =
+      timelineElements.length > 0
+        ? Math.max(...timelineElements.map((el) => el.start + el.duration))
+        : 0;
+    return Math.max(timelineDuration, maxEnd);
+  }, [timelineDuration, timelineElements]);
+}

package/src/hooks/useGroupLevel.ts

@@ -0,0 +1,36 @@
+/**
+ * A group's live meter reading (0..1 RMS-ish level, whether it just clipped),
+ * or null when the group is idle/unknown — never zero for "not playing yet".
+ *
+ * Mirrors useLivePlayheadTime's shape: the runtime posts readings at its own
+ * cadence (only while playing — see `postGroupLevels` in init.ts), this just
+ * throttles the re-render, it does not add its own polling loop.
+ */
+import { useEffect, useRef, useState } from "react";
+import { groupLevels, type GroupLevelReading } from "../player/store/groupLevels";
+
+const THROTTLE_MS = 33;
+
+export function useGroupLevel(groupId: string): GroupLevelReading | null {
+  const latestRef = useRef<GroupLevelReading | null>(groupLevels.get().get(groupId) ?? null);
+  const [, forceRender] = useState(0);
+
+  useEffect(() => {
+    let timerId: ReturnType<typeof setTimeout> | 0 = 0;
+    const unsubscribe = groupLevels.subscribe((levels) => {
+      latestRef.current = levels.get(groupId) ?? null;
+      if (!timerId) {
+        timerId = setTimeout(() => {
+          timerId = 0;
+          forceRender((v) => v + 1);
+        }, THROTTLE_MS);
+      }
+    });
+    return () => {
+      unsubscribe();
+      if (timerId) clearTimeout(timerId);
+    };
+  }, [groupId]);
+
+  return latestRef.current;
+}

package/src/hooks/useHydrateActiveCompPathFromUrl.ts

@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+import type { MutableRefObject } from "react";
+import { normalizeStudioCompositionPath, type StudioUrlState } from "../utils/studioUrlState";
+
+/**
+ * One-time hydration of `activeCompPath` from the initial URL state, once the
+ * file tree has loaded (a path that isn't in the tree yet can't be
+ * validated). Runs exactly once — `hydrated` flips true whether or not the
+ * URL named a valid path, so a later file-tree change never re-fires it.
+ */
+export function useHydrateActiveCompPathFromUrl({
+  hydrated,
+  fileTreeLoaded,
+  fileTree,
+  initialUrlStateRef,
+  setActiveCompPath,
+  setHydrated,
+}: {
+  hydrated: boolean;
+  fileTreeLoaded: boolean;
+  fileTree: string[];
+  initialUrlStateRef: MutableRefObject<StudioUrlState>;
+  setActiveCompPath: (updater: (current: string | null) => string | null) => void;
+  setHydrated: (value: boolean) => void;
+}): void {
+  useEffect(() => {
+    if (hydrated) return;
+    if (!fileTreeLoaded) return;
+    const nextCompPath = normalizeStudioCompositionPath(
+      initialUrlStateRef.current.activeCompPath,
+      fileTree,
+    );
+    setActiveCompPath((current) => (current === nextCompPath ? current : nextCompPath));
+    setHydrated(true);
+  }, [hydrated, fileTree, fileTreeLoaded, initialUrlStateRef, setActiveCompPath, setHydrated]);
+}

package/src/hooks/useMusicBeatAnalysis.ts

@@ -4,6 +4,8 @@ import { resolveBeatSourceTrack } from "../utils/timelineInspector";
 import { analyzeMusicFromUrl } from "@hyperframes/core/beats";
 import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
 import { mergeUserBeats } from "../utils/beatEditing";
+import { getTimelineElementIndexes } from "../player/lib/timelineElementIndexes";
+import { remapBeatAnalysisToComposition } from "../utils/beatEditActions";
 import {
   audioRelPathForSrc,
   beatFilePathForSrc,
@@ -90,6 +92,17 @@ async function loadBeatAnalysis(
   }
 }
 
+/** The current beat analysis, remapped onto the composition's edited beat grid. */
+export function useAdjustedBeatAnalysis() {
+  const beatAnalysis = usePlayerStore((s) => s.beatAnalysis);
+  const musicElement = usePlayerStore((s) => getTimelineElementIndexes(s.elements).musicElement);
+  const beatEdits = usePlayerStore((s) => s.beatEdits);
+  return useMemo(
+    () => remapBeatAnalysisToComposition(beatAnalysis, musicElement, beatEdits),
+    [beatAnalysis, musicElement, beatEdits],
+  );
+}
+
 export function useMusicBeatAnalysis(): void {
   const elements = usePlayerStore((s) => s.elements);
   const setBeatAnalysis = usePlayerStore((s) => s.setBeatAnalysis);

package/src/hooks/useTimelineDeleteOps.ts

@@ -0,0 +1,170 @@
+// Timeline clip deletion: the marquee/multi path and the single-clip wrapper
+// the context menu uses. Extracted verbatim from useTimelineEditing.ts to keep
+// it under the studio 600-line cap, following useTimelineAssetDropOps.
+import { useCallback, type MutableRefObject, type RefObject } from "react";
+import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { getTimelineElementLabel } from "../utils/studioHelpers";
+import { buildPatchTarget } from "./timelineEditingHelpers";
+import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
+import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
+import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
+
+interface UseTimelineDeleteOpsOptions {
+  projectIdRef: MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  timelineElements: TimelineElement[];
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  reloadPreview: () => void;
+  isRecordingRef?: MutableRefObject<boolean>;
+  forceReloadSdkSession?: () => void;
+  previewIframeRef: RefObject<HTMLIFrameElement | null>;
+}
+
+export function useTimelineDeleteOps({
+  projectIdRef,
+  activeCompPath,
+  timelineElements,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  reloadPreview,
+  isRecordingRef,
+  forceReloadSdkSession,
+  previewIframeRef,
+}: UseTimelineDeleteOpsOptions) {
+  // fallow-ignore-next-line complexity
+  const handleTimelineElementsDelete = useCallback(
+    // fallow-ignore-next-line complexity
+    async (selection: TimelineElement[]) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+      const [element] = selection;
+      if (!element) return;
+      const label =
+        selection.length === 1 ? getTimelineElementLabel(element) : `${selection.length} clips`;
+
+      // One file per delete pass. Every element in a marquee selection lives in
+      // the composition being edited, so they share a target; anything that
+      // does not is dropped rather than written to the wrong file.
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const sameFile = selection.filter(
+        (candidate) => (candidate.sourceFile || activeCompPath || "index.html") === targetPath,
+      );
+      try {
+        const originalContent = await readFileContent(pid, targetPath);
+
+        // Remove every selected element before saving once. The server rewrites
+        // the file per call, so `removedContent` after the last one holds them
+        // all — which is what makes this a single history entry, and a single
+        // undo, rather than one per clip.
+        let removedContent = originalContent;
+        for (const target of sameFile) {
+          const patchTarget = buildPatchTarget(target);
+          if (!patchTarget) {
+            throw new Error(`Timeline element ${target.id} is missing a patchable target`);
+          }
+
+          const removeResponse = await fetch(
+            `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+            {
+              method: "POST",
+              headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+              body: JSON.stringify({ target: patchTarget }),
+            },
+          );
+          if (!removeResponse.ok) {
+            throw new Error(`Failed to delete ${target.id} from ${targetPath}`);
+          }
+
+          const removeData = (await removeResponse.json()) as {
+            changed?: boolean;
+            content?: string;
+          };
+          if (typeof removeData.content === "string") removedContent = removeData.content;
+        }
+        // Content-driven duration: shrink the composition to the furthest
+        // remaining clip end, read from the post-removal SOURCE (raw
+        // data-duration), so deleting the last/longest clip removes trailing
+        // empty space. Measured from the source, not the store, whose
+        // durations are runtime-truncated.
+        const deleteContentEnd = furthestClipEndFromSource(removedContent);
+        const patchedContent = setCompositionDurationToContent(removedContent, deleteContentEnd);
+        // Optimistically reflect the shrunk length in the readout/seek bar,
+        // rolling it back if the persist below fails (see captureDurationRollback).
+        const rollbackDuration = captureDurationRollback(previewIframeRef.current);
+        if (deleteContentEnd > 0 && targetPath === (activeCompPath || "index.html")) {
+          usePlayerStore.getState().setDuration(deleteContentEnd);
+        }
+
+        domEditSaveTimestampRef.current = Date.now();
+        try {
+          await saveProjectFilesWithHistory({
+            projectId: pid,
+            label: "Delete timeline clip",
+            kind: "timeline",
+            files: { [targetPath]: patchedContent },
+            readFile: async () => originalContent,
+            // remove-element already wrote the removal, so disk holds THAT — not the
+            // content read at the top. Undo still goes back to the original.
+            diskContent: { [targetPath]: removedContent },
+            writeFile: writeProjectFile,
+            recordEdit,
+          });
+        } catch (error) {
+          rollbackDuration();
+          throw error;
+        }
+
+        const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
+        usePlayerStore
+          .getState()
+          .setElements(timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id)));
+        usePlayerStore.getState().setSelectedElementId(null);
+        usePlayerStore.getState().setSelectedElementIds(new Set());
+        forceReloadSdkSession?.();
+        reloadPreview();
+        showToast(
+          `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
+          "info",
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
+        showToast(message);
+      }
+    },
+    [
+      activeCompPath,
+      projectIdRef,
+      recordEdit,
+      showToast,
+      timelineElements,
+      writeProjectFile,
+      domEditSaveTimestampRef,
+      reloadPreview,
+      isRecordingRef,
+      forceReloadSdkSession,
+      previewIframeRef,
+    ],
+  );
+
+  /** Single-clip delete — the context menu and clip chrome path. */
+  const handleTimelineElementDelete = useCallback(
+    async (element: TimelineElement) => {
+      await handleTimelineElementsDelete([element]);
+    },
+    [handleTimelineElementsDelete],
+  );
+
+  return { handleTimelineElementsDelete, handleTimelineElementDelete };
+}

package/src/hooks/useTimelineEditing.ts

@@ -1,16 +1,10 @@
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
-import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
 import { useTimelineAssetDropOps } from "./useTimelineAssetDropOps";
-import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
-import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
-import { getTimelineElementLabel } from "../utils/studioHelpers";
 import {
   applyTimelineStackingReorder,
-  buildPatchTarget,
   patchIframeDomTiming,
   playbackStartAttributeForElement,
   persistTimelineEdit,
@@ -27,7 +21,11 @@ import {
 } from "./timelineTimingSync";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
+import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
+import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import {
+  useAudioGroupCarveAssignment,
   useTimelineElementVisibilityEditing,
   useTimelineTrackVisibilityEditing,
 } from "./timelineTrackVisibility";
@@ -36,7 +34,6 @@ import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
-import { studioWriteHeaders } from "../utils/studioFileVersion";
 
 type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
   stackingReorder?: TimelineStackingReorderIntent | null;
@@ -388,131 +385,55 @@ export function useTimelineEditing({
     forceReloadSdkSession,
   });
 
-  // fallow-ignore-next-line complexity
-  const handleTimelineElementsDelete = useCallback(
-    // fallow-ignore-next-line complexity
-    async (selection: TimelineElement[]) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) throw new Error("No active project");
-      const [element] = selection;
-      if (!element) return;
-      const label =
-        selection.length === 1 ? getTimelineElementLabel(element) : `${selection.length} clips`;
-
-      // One file per delete pass. Every element in a marquee selection lives in
-      // the composition being edited, so they share a target; anything that
-      // does not is dropped rather than written to the wrong file.
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
-      const sameFile = selection.filter(
-        (candidate) => (candidate.sourceFile || activeCompPath || "index.html") === targetPath,
-      );
-      try {
-        const originalContent = await readFileContent(pid, targetPath);
-
-        // Remove every selected element before saving once. The server rewrites
-        // the file per call, so `removedContent` after the last one holds them
-        // all — which is what makes this a single history entry, and a single
-        // undo, rather than one per clip.
-        let removedContent = originalContent;
-        for (const target of sameFile) {
-          const patchTarget = buildPatchTarget(target);
-          if (!patchTarget) {
-            throw new Error(`Timeline element ${target.id} is missing a patchable target`);
-          }
-
-          const removeResponse = await fetch(
-            `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
-            {
-              method: "POST",
-              headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-              body: JSON.stringify({ target: patchTarget }),
-            },
-          );
-          if (!removeResponse.ok) {
-            throw new Error(`Failed to delete ${target.id} from ${targetPath}`);
-          }
-
-          const removeData = (await removeResponse.json()) as {
-            changed?: boolean;
-            content?: string;
-          };
-          if (typeof removeData.content === "string") removedContent = removeData.content;
-        }
-        // Content-driven duration: shrink the composition to the furthest
-        // remaining clip end, read from the post-removal SOURCE (raw
-        // data-duration), so deleting the last/longest clip removes trailing
-        // empty space. Measured from the source, not the store, whose
-        // durations are runtime-truncated.
-        const deleteContentEnd = furthestClipEndFromSource(removedContent);
-        const patchedContent = setCompositionDurationToContent(removedContent, deleteContentEnd);
-        // Optimistically reflect the shrunk length in the readout/seek bar,
-        // rolling it back if the persist below fails (see captureDurationRollback).
-        const rollbackDuration = captureDurationRollback(previewIframeRef.current);
-        if (deleteContentEnd > 0 && targetPath === (activeCompPath || "index.html")) {
-          usePlayerStore.getState().setDuration(deleteContentEnd);
-        }
+  const handleAutoGroupCarveSources = useAudioGroupCarveAssignment({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+  });
 
-        domEditSaveTimestampRef.current = Date.now();
-        try {
-          await saveProjectFilesWithHistory({
-            projectId: pid,
-            label: "Delete timeline clip",
-            kind: "timeline",
-            files: { [targetPath]: patchedContent },
-            readFile: async () => originalContent,
-            // remove-element already wrote the removal, so disk holds THAT — not the
-            // content read at the top. Undo still goes back to the original.
-            diskContent: { [targetPath]: removedContent },
-            writeFile: writeProjectFile,
-            recordEdit,
-          });
-        } catch (error) {
-          rollbackDuration();
-          throw error;
-        }
+  const setElementFxAttribute = useSetElementAttribute({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+  });
 
-        const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
-        usePlayerStore
-          .getState()
-          .setElements(timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id)));
-        usePlayerStore.getState().setSelectedElementId(null);
-        usePlayerStore.getState().setSelectedElementIds(new Set());
-        forceReloadSdkSession?.();
-        reloadPreview();
-        showToast(
-          `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
-          "info",
-        );
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
-        showToast(message);
-      }
-    },
-    [
-      activeCompPath,
-      recordEdit,
-      showToast,
-      timelineElements,
-      writeProjectFile,
-      domEditSaveTimestampRef,
-      reloadPreview,
-      isRecordingRef,
-      forceReloadSdkSession,
-      previewIframeRef,
-    ],
-  );
+  const setAudioGroupAttribute = useSetAudioGroupAttribute({
+    projectIdRef,
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    previewIframeRef,
+    pendingTimelineEditPathRef,
+    isRecordingRef,
+  });
 
-  /** Single-clip delete — the context menu and clip chrome path. */
-  const handleTimelineElementDelete = useCallback(
-    async (element: TimelineElement) => {
-      await handleTimelineElementsDelete([element]);
-    },
-    [handleTimelineElementsDelete],
-  );
+  const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({
+    projectIdRef,
+    activeCompPath,
+    timelineElements,
+    showToast,
+    writeProjectFile,
+    recordEdit,
+    domEditSaveTimestampRef,
+    reloadPreview,
+    isRecordingRef,
+    forceReloadSdkSession,
+    previewIframeRef,
+  });
 
   const { handleTimelineAssetDrop, handleTimelineFileDrop, handleTimelineCompositionDrop } =
     useTimelineAssetDropOps({
@@ -558,6 +479,9 @@ export function useTimelineEditing({
     handleTimelineElementResize,
     handleToggleTrackHidden,
     handleToggleElementHidden,
+    handleAutoGroupCarveSources,
+    setAudioGroupAttribute,
+    setElementFxAttribute,
     handleTimelineElementDelete,
     handleTimelineElementsDelete,
     handleTimelineElementSplit: handleRazorSplit,

package/src/player/components/AudioWaveform.tsx

@@ -35,37 +35,19 @@ function extractPeaks(channelData: Float32Array, barCount: number): number[] {
   return peaks.map((peak) => peak / maxPeak);
 }
 
-function fakePeaks(url: string, count: number): number[] {
-  let seed = 0;
-  for (let index = 0; index < url.length; index++) {
-    seed = ((seed << 5) - seed + url.charCodeAt(index)) | 0;
-  }
-  seed = Math.abs(seed) || 42;
-  const random = () => {
-    seed = (seed * 16807) % 2147483647;
-    return (seed & 0x7fffffff) / 2147483647;
-  };
-  return Array.from({ length: count }, (_, index) => {
-    const time = index / count;
-    const envelope =
-      0.3 + 0.3 * Math.sin(time * Math.PI * 3.2) + 0.2 * Math.sin(time * Math.PI * 7.1);
-    return Math.max(0.05, Math.min(1, envelope * (0.4 + 0.6 * random())));
-  });
-}
-
 async function loadWaveform(
   audioUrl: string,
   waveformUrl: string | undefined,
   signal: AbortSignal,
 ): Promise<number[]> {
-  try {
-    return waveformUrl
-      ? await fetchWaveformPeaks(waveformUrl, signal)
-      : await decodeWaveformPeaks(audioUrl, signal);
-  } catch (error) {
-    if (signal.aborted) throw error;
-    return fakePeaks(waveformUrl ?? audioUrl, 4000);
-  }
+  // Failures propagate. Synthesised peaks are worse than an honest gap: an
+  // author trims and beat-aligns against this waveform, and a plausible
+  // fabrication is indistinguishable from the real thing while being wrong.
+  // The scheduler caches the failure (metadataFailureTtlMs) so the degraded
+  // state neither refetch-loops nor pins itself past a transient error.
+  return waveformUrl
+    ? await fetchWaveformPeaks(waveformUrl, signal)
+    : await decodeWaveformPeaks(audioUrl, signal);
 }
 
 async function fetchWaveformPeaks(url: string, signal: AbortSignal): Promise<number[]> {
@@ -193,6 +175,27 @@ export const AudioWaveform = memo(function AudioWaveform({
           }}
         />
       )}
+      {/* Degraded state — the decode failed; say so rather than paint a
+          waveform the author could edit against. */}
+      {snapshot.status === "error" && (
+        <div
+          className="absolute inset-x-0 flex items-center justify-center gap-1.5"
+          style={{ top: 16, bottom: 0 }}
+        >
+          <div
+            className="absolute inset-x-0"
+            style={{
+              bottom: "20%",
+              height: 2,
+              background:
+                "repeating-linear-gradient(90deg, rgba(75,163,210,0.35) 0 2px, transparent 2px 5px)",
+            }}
+          />
+          <span className="relative rounded bg-black/50 px-1 text-[8px] text-neutral-500">
+            waveform unavailable
+          </span>
+        </div>
+      )}
       {label && (
         <div className="absolute inset-x-0 top-0 z-10 px-1.5 py-0.5">
           <span