fix(video): write faststart mp4/mov output from stabilize-video (#593)

Add -movflags +faststart for mp4/mov/m4v output from stabilize-video so
the stabilized result streams and previews progressively instead of
appearing broken or corrupted (moov atom was landing after mdat).

Fixes #588

apps/api/src/routes/tools/stabilize-video.ts

@@ -47,6 +47,20 @@ function codecForContainer(ext: string): {
   };
 }
 
+/**
+ * mp4/mov muxers write the moov atom at the end of the file by default. A
+ * progressive player (browsers, the in-app player, most mobile players) then
+ * cannot start playback or seek until the whole file is downloaded, so the
+ * stabilized result looks broken or "corrupted" on preview. +faststart moves
+ * the moov atom to the front. Mirrors convert-video / compress-video (#588).
+ */
+function faststartArgs(ext: string): string[] {
+  const lower = ext.toLowerCase();
+  return lower === ".mp4" || lower === ".m4v" || lower === ".mov"
+    ? ["-movflags", "+faststart"]
+    : [];
+}
+
 export function registerStabilizeVideo(app: FastifyInstance) {
   createToolRoute(app, {
     toolId: "stabilize-video",
@@ -98,6 +112,7 @@ export function registerStabilizeVideo(app: FastifyInstance) {
           `vidstabtransform=input=${trf}:smoothing=${settings.smoothing}`,
           ...encodeArgs,
           ...audioArgs,
+          ...faststartArgs(origExt),
           outPath,
         ],
         info.durationS,

tests/integration/tools/video/stabilize-video.test.ts

@@ -67,7 +67,8 @@ async function resolveResult(res: Awaited<ReturnType<typeof runTool>>): Promise<
     await new Promise((r) => setTimeout(r, 500));
   }
   expect(row?.status).toBe("completed");
-  const outName = (row?.outputRefs as string[])[0].split("/").pop() as string;
+  if (!row) throw new Error("job row not found after polling");
+  const outName = (row.outputRefs as string[])[0].split("/").pop() as string;
   const dl = await testApp.app.inject({
     method: "GET",
     url: `/api/v1/download/${jobId}/${encodeURIComponent(outName)}`,
@@ -90,6 +91,32 @@ describe.skipIf(!ffmpegAvailable())("stabilize-video (requires ffmpeg)", () => {
     expect(v).toBeDefined();
   }, 120_000);
 
+  it("produces a faststart mp4 with the moov atom before mdat", async () => {
+    const res = await runTool({});
+    const { downloadPayload } = await resolveResult(res);
+
+    const moov = downloadPayload.indexOf("moov");
+    const mdat = downloadPayload.indexOf("mdat");
+    expect(moov).toBeGreaterThanOrEqual(0);
+    expect(mdat).toBeGreaterThanOrEqual(0);
+    // Without -movflags +faststart the moov atom lands after mdat, so browsers
+    // and mobile players cannot start progressive playback and report the file
+    // as broken until it is fully downloaded (issue #588).
+    expect(moov).toBeLessThan(mdat);
+  }, 120_000);
+
+  it("keeps the audio stream intact through stabilization", async () => {
+    const res = await runTool({});
+    const { downloadPayload } = await resolveResult(res);
+
+    const tmpDir = mkdtempSync(join(tmpdir(), "stab-audio-"));
+    const probeFile = join(tmpDir, "stabilized.mp4");
+    writeFileSync(probeFile, downloadPayload);
+    const info = await probeMedia(probeFile);
+    // The tiny fixture carries an audio track; a mux mismatch would drop it.
+    expect(info.streams.some((s) => s.type === "audio")).toBe(true);
+  }, 120_000);
+
   it("rejects smoothing out of range with 400", async () => {
     const res = await runTool({ smoothing: 100 });
     expect(res.statusCode).toBe(400);