From ed8eea14b0c8beefd964485a74027ef3ca9e6ed0 Mon Sep 17 00:00:00 2001
From: smirk-dev <suryansh.mishra.sm6@gmail.com>
Date: Sun, 7 Jun 2026 09:37:45 +0530
Subject: [PATCH] fix: bound waveform extraction memory usage for large video
 files

Waveform extraction called file.arrayBuffer() on the full uploaded video
regardless of size. For uploads up to the 2GB cap this allocated multiple
gigabytes (raw buffer + decoded PCM), spiking the heap and crashing browser
tabs before editing began.

- Add MAX_WAVEFORM_FILE_SIZE_BYTES (300MB) config in src/lib/constants.ts.
- Refactor useAudioWaveform to a discriminated status union
  (idle | loading | ready | disabled | error). Files over the threshold are
  never read into memory; within the threshold audio is read through a bounded
  Blob.slice so decodeAudioData never receives more than the threshold's bytes.
  Small files are unchanged.
- Strengthen cancellation: in-flight reads/decodes bail out on unmount or file
  change before creating an AudioContext or setting state.
- Wire WaveformCanvas into TrimControl and render a placeholder + helper text
  when extraction is disabled for large files.
- Add tests for threshold behaviour, the no-full-read guarantee, custom
  thresholds, decode errors, and unmount cancellation.

Closes #1013

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/components/TrimControl.tsx                |  30 +++-
 src/components/__tests__/TrimControl.test.tsx |  78 ++++++++++
 src/hooks/__tests__/useAudioWaveform.test.tsx | 133 ++++++++++++++++++
 src/hooks/useAudioWaveform.ts                 |  73 ++++++++--
 src/lib/constants.ts                          |  13 ++
 5 files changed, 312 insertions(+), 15 deletions(-)
 create mode 100644 src/components/__tests__/TrimControl.test.tsx
 create mode 100644 src/hooks/__tests__/useAudioWaveform.test.tsx

diff --git a/src/components/TrimControl.tsx b/src/components/TrimControl.tsx
index d48bdd69..a66d0fc5 100644
--- a/src/components/TrimControl.tsx
+++ b/src/components/TrimControl.tsx
@@ -25,7 +25,11 @@ export default function TrimControl({ recipe, onChange, duration, file }: Props)
     recipe.trimStart.toString()
   );
 
-  const { waveform, isLoading: waveformLoading } = useAudioWaveform(file);
+  const {
+    waveform,
+    status: waveformStatus,
+    isLoading: waveformLoading,
+  } = useAudioWaveform(file);
   const hasAudio = waveform.length > 0;
 
   useEffect(() => {
@@ -235,6 +239,30 @@ export default function TrimControl({ recipe, onChange, duration, file }: Props)
           />
         </div>
       )}
+
+      {file && (
+        <div className="space-y-1">
+          {waveformStatus === "disabled" ? (
+            <div
+              role="img"
+              aria-label="Audio waveform preview disabled for large file"
+              className="flex h-16 w-full items-center justify-center rounded-md border border-[var(--border)] bg-[var(--surface)] px-3"
+            >
+              <p className="font-heading text-center text-[10px] text-[var(--muted)]">
+                Waveform preview is disabled for very large files to keep the
+                editor responsive.
+              </p>
+            </div>
+          ) : (
+            <WaveformCanvas
+              samples={waveform}
+              loading={waveformLoading}
+              hasAudio={hasAudio}
+            />
+          )}
+        </div>
+      )}
+
       <div className="flex gap-3">
         <div className="flex-1">
           <label
diff --git a/src/components/__tests__/TrimControl.test.tsx b/src/components/__tests__/TrimControl.test.tsx
new file mode 100644
index 00000000..04b18e06
--- /dev/null
+++ b/src/components/__tests__/TrimControl.test.tsx
@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import "@testing-library/jest-dom/vitest";
+import { render, screen } from "@testing-library/react";
+import TrimControl from "../TrimControl";
+import { DEFAULT_RECIPE } from "@/lib/constants";
+import type { UseAudioWaveformResult } from "@/hooks/useAudioWaveform";
+
+vi.mock("@/hooks/useAudioWaveform", () => ({
+  useAudioWaveform: vi.fn(),
+}));
+
+import { useAudioWaveform } from "@/hooks/useAudioWaveform";
+
+const mockedHook = vi.mocked(useAudioWaveform);
+
+function setWaveform(result: UseAudioWaveformResult) {
+  mockedHook.mockReturnValue(result);
+}
+
+function renderTrim(file: File | null) {
+  return render(
+    <TrimControl
+      recipe={DEFAULT_RECIPE}
+      onChange={() => {}}
+      duration={10}
+      file={file}
+    />
+  );
+}
+
+const sampleFile = new File(["video-bytes"], "clip.mp4", { type: "video/mp4" });
+
+beforeEach(() => {
+  mockedHook.mockReset();
+});
+
+describe("TrimControl waveform fallback", () => {
+  it("renders the disabled placeholder for very large files", () => {
+    setWaveform({ waveform: [], status: "disabled", isLoading: false });
+
+    renderTrim(sampleFile);
+
+    expect(
+      screen.getByLabelText("Audio waveform preview disabled for large file")
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(/disabled for very large files/i)
+    ).toBeInTheDocument();
+    // The canvas waveform must not render in the disabled state.
+    expect(screen.queryByLabelText("Audio waveform")).not.toBeInTheDocument();
+  });
+
+  it("renders the waveform canvas for normal files", () => {
+    setWaveform({
+      waveform: [0.1, 0.5, 0.9],
+      status: "ready",
+      isLoading: false,
+    });
+
+    renderTrim(sampleFile);
+
+    expect(screen.getByLabelText("Audio waveform")).toBeInTheDocument();
+    expect(
+      screen.queryByText(/disabled for very large files/i)
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not render any waveform UI when no file is selected", () => {
+    setWaveform({ waveform: [], status: "idle", isLoading: false });
+
+    renderTrim(null);
+
+    expect(
+      screen.queryByText(/disabled for very large files/i)
+    ).not.toBeInTheDocument();
+    expect(screen.queryByLabelText("Audio waveform")).not.toBeInTheDocument();
+  });
+});
diff --git a/src/hooks/__tests__/useAudioWaveform.test.tsx b/src/hooks/__tests__/useAudioWaveform.test.tsx
new file mode 100644
index 00000000..df9ad2f7
--- /dev/null
+++ b/src/hooks/__tests__/useAudioWaveform.test.tsx
@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { useAudioWaveform } from "../useAudioWaveform";
+import { MAX_WAVEFORM_FILE_SIZE_BYTES } from "@/lib/constants";
+
+// --- Test doubles -----------------------------------------------------------
+
+type FakeAudioBuffer = { getChannelData: () => Float32Array };
+
+class FakeAudioContext {
+  static instances: FakeAudioContext[] = [];
+  static decodeImpl: () => Promise<FakeAudioBuffer> = async () => ({
+    getChannelData: () => new Float32Array([0, 0.25, 0.5, 0.75, 1]),
+  });
+
+  decodeAudioData = vi.fn(() => FakeAudioContext.decodeImpl());
+  close = vi.fn(async () => {});
+
+  constructor() {
+    FakeAudioContext.instances.push(this);
+  }
+}
+
+/**
+ * Builds a minimal File stand-in. The hook only touches `file.size` and
+ * `file.slice(...).arrayBuffer()`, so we expose spies for both to assert that
+ * the full file is never read for oversized inputs.
+ */
+function makeFile(size: number, readBytes: () => Promise<ArrayBuffer>) {
+  const arrayBuffer = vi.fn(readBytes);
+  const slice = vi.fn(() => ({ arrayBuffer }) as unknown as Blob);
+  return { size, slice, arrayBuffer } as unknown as File;
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+beforeEach(() => {
+  FakeAudioContext.instances = [];
+  FakeAudioContext.decodeImpl = async () => ({
+    getChannelData: () => new Float32Array([0, 0.25, 0.5, 0.75, 1]),
+  });
+  vi.stubGlobal("AudioContext", FakeAudioContext);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.clearAllMocks();
+});
+
+// --- Tests ------------------------------------------------------------------
+
+describe("useAudioWaveform", () => {
+  it("is idle when no file is provided", async () => {
+    const { result } = renderHook(() => useAudioWaveform(null));
+    await waitFor(() => expect(result.current.status).toBe("idle"));
+    expect(result.current.waveform).toEqual([]);
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("extracts a waveform for files within the size threshold", async () => {
+    const file = makeFile(1024, () => Promise.resolve(new ArrayBuffer(8)));
+
+    const { result } = renderHook(() => useAudioWaveform(file, 5));
+
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(result.current.waveform).toHaveLength(5);
+    expect(result.current.isLoading).toBe(false);
+    // Reads through a bounded slice, never the raw File in one shot.
+    expect(file.slice).toHaveBeenCalledWith(0, MAX_WAVEFORM_FILE_SIZE_BYTES);
+    expect(FakeAudioContext.instances).toHaveLength(1);
+  });
+
+  it("skips extraction and reports 'disabled' for very large files", async () => {
+    const file = makeFile(MAX_WAVEFORM_FILE_SIZE_BYTES + 1, () =>
+      Promise.resolve(new ArrayBuffer(8))
+    );
+
+    const { result } = renderHook(() => useAudioWaveform(file));
+
+    await waitFor(() => expect(result.current.status).toBe("disabled"));
+    expect(result.current.waveform).toEqual([]);
+    // The whole point of #1013: the oversized file is never read into memory.
+    expect(file.slice).not.toHaveBeenCalled();
+    expect(file.arrayBuffer).not.toHaveBeenCalled();
+    expect(FakeAudioContext.instances).toHaveLength(0);
+  });
+
+  it("respects a custom size threshold", async () => {
+    const file = makeFile(2048, () => Promise.resolve(new ArrayBuffer(8)));
+
+    const { result } = renderHook(() => useAudioWaveform(file, 96, 1024));
+
+    await waitFor(() => expect(result.current.status).toBe("disabled"));
+    expect(file.slice).not.toHaveBeenCalled();
+  });
+
+  it("reports 'error' when decoding fails", async () => {
+    FakeAudioContext.decodeImpl = () => Promise.reject(new Error("bad audio"));
+    const file = makeFile(1024, () => Promise.resolve(new ArrayBuffer(8)));
+
+    const { result } = renderHook(() => useAudioWaveform(file));
+
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(result.current.waveform).toEqual([]);
+  });
+
+  it("cancels in-flight work and does not update state after unmount", async () => {
+    const gate = deferred<ArrayBuffer>();
+    const file = makeFile(1024, () => gate.promise);
+
+    const { result, unmount } = renderHook(() => useAudioWaveform(file));
+
+    await waitFor(() => expect(result.current.status).toBe("loading"));
+
+    unmount();
+
+    // Resolve the pending read *after* unmount — the hook must bail out before
+    // creating an AudioContext or advancing to "ready".
+    await act(async () => {
+      gate.resolve(new ArrayBuffer(8));
+      await Promise.resolve();
+    });
+
+    expect(result.current.status).toBe("loading");
+    expect(FakeAudioContext.instances).toHaveLength(0);
+  });
+});
diff --git a/src/hooks/useAudioWaveform.ts b/src/hooks/useAudioWaveform.ts
index 25ed57d5..cb1ece4d 100644
--- a/src/hooks/useAudioWaveform.ts
+++ b/src/hooks/useAudioWaveform.ts
@@ -1,9 +1,28 @@
 "use client";
 
 import { useEffect, useState } from "react";
+import { MAX_WAVEFORM_FILE_SIZE_BYTES } from "@/lib/constants";
 
 const DEFAULT_BAR_COUNT = 96;
 
+/**
+ * Lifecycle of a waveform extraction request:
+ * - `idle`     — no file selected.
+ * - `loading`  — reading/decoding audio.
+ * - `ready`    — `waveform` holds the downsampled peaks.
+ * - `disabled` — file exceeds the size threshold; extraction was skipped to
+ *                keep memory bounded (#1013). UI should show a placeholder.
+ * - `error`    — decoding failed or Web Audio is unavailable.
+ */
+export type WaveformStatus = "idle" | "loading" | "ready" | "disabled" | "error";
+
+export interface UseAudioWaveformResult {
+  waveform: number[];
+  status: WaveformStatus;
+  /** Convenience flag, retained for backward compatibility. */
+  isLoading: boolean;
+}
+
 type BrowserWindow = Window &
   typeof globalThis & {
     webkitAudioContext?: typeof AudioContext;
@@ -27,12 +46,23 @@ function downsampleWaveform(channelData: Float32Array, barCount: number): number
   return peaks.map((peak) => peak / maxPeak);
 }
 
+/**
+ * Extracts a low-resolution audio waveform from a media file.
+ *
+ * Memory safety (#1013): files larger than `maxFileSizeBytes` are not read into
+ * memory at all — the hook reports `status: "disabled"` and the caller renders a
+ * placeholder instead. Within the threshold the audio is read through a bounded
+ * `Blob.slice` so the amount of data handed to `decodeAudioData` never exceeds
+ * the threshold, even if the underlying file grows unexpectedly. Small files
+ * (the common case) are read in full exactly as before — no behavioural change.
+ */
 export function useAudioWaveform(
   file: File | null,
-  barCount = DEFAULT_BAR_COUNT
-) {
+  barCount = DEFAULT_BAR_COUNT,
+  maxFileSizeBytes = MAX_WAVEFORM_FILE_SIZE_BYTES
+): UseAudioWaveformResult {
   const [waveform, setWaveform] = useState<number[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
+  const [status, setStatus] = useState<WaveformStatus>("idle");
 
   useEffect(() => {
     let isCancelled = false;
@@ -41,7 +71,14 @@ export function useAudioWaveform(
     async function extractWaveform() {
       if (!file) {
         setWaveform([]);
-        setIsLoading(false);
+        setStatus("idle");
+        return;
+      }
+
+      // Hard memory guard: never pull a multi-gigabyte file into the heap.
+      if (file.size > maxFileSizeBytes) {
+        setWaveform([]);
+        setStatus("disabled");
         return;
       }
 
@@ -50,41 +87,49 @@ export function useAudioWaveform(
 
       if (!AudioContextCtor) {
         setWaveform([]);
-        setIsLoading(false);
+        setStatus("error");
         return;
       }
 
-      setIsLoading(true);
+      setWaveform([]);
+      setStatus("loading");
 
       try {
+        // Read at most `maxFileSizeBytes`. For files within the threshold this
+        // is the whole file (unchanged); the slice bounds the allocation so we
+        // never decode more than the threshold's worth of bytes.
+        const audioBytes = await file.slice(0, maxFileSizeBytes).arrayBuffer();
+        if (isCancelled) return;
+
         audioContext = new AudioContextCtor();
-        const audioBuffer = await audioContext.decodeAudioData(
-          await file.arrayBuffer()
-        );
+        const audioBuffer = await audioContext.decodeAudioData(audioBytes);
+        if (isCancelled) return;
+
         const channelData = audioBuffer.getChannelData(0);
         const peaks = downsampleWaveform(channelData, barCount);
 
         if (!isCancelled) {
           setWaveform(peaks);
+          setStatus("ready");
         }
       } catch {
         if (!isCancelled) {
           setWaveform([]);
+          setStatus("error");
         }
       } finally {
         await audioContext?.close();
-        if (!isCancelled) {
-          setIsLoading(false);
-        }
       }
     }
 
     extractWaveform();
 
+    // Cancellation: a new file, a changed bar count, or an unmount stops the
+    // in-flight read/decode and prevents state updates on a dead component.
     return () => {
       isCancelled = true;
     };
-  }, [barCount, file]);
+  }, [barCount, file, maxFileSizeBytes]);
 
-  return { waveform, isLoading };
+  return { waveform, status, isLoading: status === "loading" };
 }
diff --git a/src/lib/constants.ts b/src/lib/constants.ts
index e713f779..93707580 100644
--- a/src/lib/constants.ts
+++ b/src/lib/constants.ts
@@ -3,6 +3,19 @@ import { RECIPE_VERSION } from "./types"
 
 export const SPEED_STEPS = [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 4] as const;
 
+/**
+ * Upper bound (in bytes) on the file size for which audio waveform extraction
+ * is attempted. The app accepts uploads up to 2 GB, but decoding a file of that
+ * size with the Web Audio API reads the whole thing into memory (raw buffer +
+ * decoded PCM), which spikes the heap and crashes browser tabs (#1013).
+ *
+ * Files at or below this threshold are decoded as before; larger files skip
+ * waveform extraction and fall back to a static placeholder so the editor stays
+ * responsive. 300 MB keeps the worst-case waveform allocation bounded while
+ * still covering the vast majority of real-world clips.
+ */
+export const MAX_WAVEFORM_FILE_SIZE_BYTES = 300 * 1024 * 1024;
+
 export const DEFAULT_RECIPE: EditRecipe = {
   preset: "vertical-9-16",
   customWidth: 1920,