feat: download separated stems as ZIP (#60)

Co-authored-by: hi-ogawa-agent <266689927+hi-ogawa-agent@users.noreply.github.com>

Author: hi-ogawa-agent

README.md

@@ -81,6 +81,8 @@ pnpm dev
 
 Open `http://localhost:5173`, choose a local audio file and the required model files from `data/onnx-lean/`, then run separation. Audio and models stay in the browser.
 
+When separation finishes, the app automatically downloads all generated stems as a source-named archive such as `song_wav.stems.zip`. Individual stem previews and WAV downloads remain available in the results.
+
 Build the static app with:
 
 ```bash

packages/app/e2e/separate.spec.ts

@@ -20,6 +20,7 @@ test("separates a clip fully client-side", async ({ page }) => {
   await page.setInputFiles("#file", FIXTURE);
   await expect(page.locator("#audio-status")).toContainText("Decoded: 2.00s");
 
+  const downloadPromise = page.waitForEvent("download");
   await page.click("#run");
   await expect(
     page.getByRole("progressbar", { name: "Overall separation progress" }),
@@ -31,6 +32,8 @@ test("separates a clip fully client-side", async ({ page }) => {
     timeout: 300_000,
   });
   await expect(page.getByTestId("timing-summary")).toContainText("Inference");
+  const download = await downloadPromise;
+  expect(download.suggestedFilename()).toBe("sine-2s_wav.stems.zip");
 
   const stems = page.locator("#stems > div");
   await expect(stems).toHaveCount(4);
@@ -39,4 +42,7 @@ test("separates a clip fully client-side", async ({ page }) => {
   }
   await expect(page.locator("#stems audio")).toHaveCount(4);
   await expect(page.locator("#stems a")).toHaveCount(4);
+  await expect(
+    page.getByRole("link", { name: "Download ZIP" }),
+  ).toHaveAttribute("download", "sine-2s_wav.stems.zip");
 });

packages/app/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.101.2",
+    "jszip": "^3.10.1",
     "lucide-react": "^0.562.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

packages/app/src/app.tsx

@@ -12,6 +12,11 @@ import {
   type ModelSource,
 } from "./lib/audio/models";
 import type { SeparateRequest } from "./lib/audio/separate";
+import {
+  createStemArchive,
+  downloadBlob,
+  toStemArchiveFilename,
+} from "./lib/audio/stem-archive";
 import { encodeWavF32 } from "./lib/audio/wav";
 import { separateInWorker } from "./lib/audio/worker-client";
 import { loadPreferences, savePreferences } from "./lib/preferences";
@@ -104,14 +109,9 @@ export function App() {
         : "";
 
   const handleAudioFileMutation = useMutation({
-    mutationFn: async (file: File | undefined) => {
-      if (file) {
-        return decodeAudioFile(file);
-      }
-      return null;
-    },
+    mutationFn: decodeAudioFile,
   });
-  const decodedAudio = handleAudioFileMutation.data ?? null;
+  const decodedAudio = handleAudioFileMutation.data;
 
   const [runProgress, setRunProgress] = useState<RunProgress | null>(null);
 
@@ -156,12 +156,22 @@ export function App() {
           [output.left, output.right],
           AUDIO_SAMPLE_RATE,
         );
-        return { ...output, url: URL.createObjectURL(blob) };
+        return { ...output, blob, url: URL.createObjectURL(blob) };
       });
       outputCleanupRef.current = nextOutputs.map(
         (output) => () => URL.revokeObjectURL(output.url),
       );
-      return { outputs: nextOutputs, durationMs: performance.now() - started };
+      const durationMs = performance.now() - started;
+      const archiveBlob = await createStemArchive(nextOutputs);
+      const archive = {
+        name: toStemArchiveFilename(decodedAudio.name),
+        url: URL.createObjectURL(archiveBlob),
+      };
+      outputCleanupRef.current.push(() => URL.revokeObjectURL(archive.url));
+      return { outputs: nextOutputs, archive, durationMs };
+    },
+    onSuccess: ({ archive }) => {
+      downloadBlob(archive.url, archive.name);
     },
     onSettled: (_data, error) => {
       if (error) {
@@ -218,9 +228,12 @@ export function App() {
                 type="file"
                 id="file"
                 accept="audio/*"
-                onChange={(event) =>
-                  handleAudioFileMutation.mutate(event.target.files?.[0])
-                }
+                onChange={(event) => {
+                  const file = event.target.files?.[0];
+                  if (file) {
+                    handleAudioFileMutation.mutate(file);
+                  }
+                }}
               />
               {audioFileStatusText && (
                 <p className="text-muted mt-3.5 text-sm" id="audio-status">
@@ -304,10 +317,10 @@ export function App() {
                     }
                   >
                     <option value="">off</option>
+                    <option>vocals</option>
                     <option>drums</option>
                     <option>bass</option>
                     <option>other</option>
-                    <option>vocals</option>
                   </select>
                 </div>
                 <div className="grid gap-2">
@@ -441,16 +454,25 @@ export function App() {
             className="bg-surface shadow-card min-w-0 rounded-lg border px-5 py-6 sm:p-9"
             aria-labelledby="results-title"
           >
-            <div className="mb-7">
-              <p className="text-primary-strong mb-2.5 text-xs font-extrabold tracking-[0.14em] uppercase">
-                Separation complete
-              </p>
-              <h2
-                className="text-3xl font-semibold tracking-[-0.025em]"
-                id="results-title"
+            <div className="mb-7 flex items-end justify-between gap-4">
+              <div>
+                <p className="text-primary-strong mb-2.5 text-xs font-extrabold tracking-[0.14em] uppercase">
+                  Separation complete
+                </p>
+                <h2
+                  className="text-3xl font-semibold tracking-[-0.025em]"
+                  id="results-title"
+                >
+                  Your stems
+                </h2>
+              </div>
+              <a
+                className="text-primary hover:text-accent shrink-0 text-sm font-semibold underline underline-offset-3"
+                href={handleRunMutation.data?.archive.url}
+                download={handleRunMutation.data?.archive.name}
               >
-                Your stems
-              </h2>
+                Download ZIP
+              </a>
             </div>
             <div className="grid gap-3.5" id="stems">
               {outputs.map((output) => (

packages/app/src/lib/audio/decode.ts

@@ -1,6 +1,7 @@
 import { AUDIO_SAMPLE_RATE } from "./constants";
 
 export interface DecodedAudio {
+  name: string;
   left: Float32Array;
   right: Float32Array;
   duration: number;
@@ -19,6 +20,7 @@ export async function decodeAudioFile(file: File): Promise<DecodedAudio> {
   const right = buffer.numberOfChannels > 1 ? buffer.getChannelData(1) : left;
 
   return {
+    name: file.name,
     left,
     right,
     duration: buffer.duration,

packages/app/src/lib/audio/separate.ts

@@ -11,7 +11,6 @@ import {
   MODEL_INPUT_LENGTH,
   MODEL_OUTPUT_LENGTH,
   MODEL_SEGMENT,
-  SOURCES,
 } from "./constants";
 import { readModelFile, type ModelFilename, type ModelSource } from "./models";
 
@@ -151,10 +150,18 @@ export async function separate(
     req.right,
     host,
   );
-  const names = req.twoStems
-    ? [req.twoStems.source, `no_${req.twoStems.source}`]
-    : SOURCES;
-  return names.map((name, index) => ({
+  const stemOrder: { name: string; index: number }[] = req.twoStems
+    ? [
+        { name: `no_${req.twoStems.source}`, index: 1 },
+        { name: req.twoStems.source, index: 0 },
+      ]
+    : [
+        { name: "vocals", index: 3 },
+        { name: "drums", index: 0 },
+        { name: "bass", index: 1 },
+        { name: "other", index: 2 },
+      ];
+  return stemOrder.map(({ name, index }) => ({
     name,
     left: tracks[2 * index],
     right: tracks[2 * index + 1],

packages/app/src/lib/audio/stem-archive.ts

@@ -0,0 +1,28 @@
+import JSZip from "jszip";
+
+export interface StemFile {
+  name: string;
+  blob: Blob;
+}
+
+export function toStemArchiveFilename(inputFilename: string): string {
+  const basename = inputFilename.replaceAll(".", "_");
+  return `${basename || "demucs"}.stems.zip`;
+}
+
+export async function createStemArchive(stems: StemFile[]): Promise<Blob> {
+  const zip = new JSZip();
+  for (const stem of stems) {
+    zip.file(`${stem.name}.wav`, stem.blob, { compression: "STORE" });
+  }
+  return zip.generateAsync({ type: "blob", compression: "STORE" });
+}
+
+export function downloadBlob(url: string, filename: string): void {
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  document.body.append(link);
+  link.click();
+  link.remove();
+}