feat(noise-removal): SOTA noise removal with 4 quality tiers (#57)

* feat(noise-removal): register tool in shared constants and i18n

* feat(noise-removal): add SCUNet and NAFNet model architectures

* feat(noise-removal): add Python denoising engine with 4 quality tiers

* feat(noise-removal): add TypeScript bridge for Python sidecar

* feat(noise-removal): add frontend settings with 4-tier selector

* feat(noise-removal): register in tool registry and pipeline

* feat(noise-removal): add Fastify API route with Zod validation

* feat(noise-removal): add SCUNet and NAFNet model downloads to Docker build

* test(noise-removal): add to e2e tool page rendering tests

* test(noise-removal): add integration tests for API endpoint

* style: fix biome formatting and import ordering

* fix(noise-removal): use correct model download URLs

NAFNet model is hosted on HuggingFace, not GitHub releases.
Also align SCUNet URL to use the KAIR releases (same as Docker build).

* fix(noise-removal): remove emojis from tier selector, simplify labels

Drop emoji icons from Quick/Balanced/Quality/Maximum buttons. Replace
technical algorithm names with plain descriptions users can understand.

---------

Co-authored-by: stirling-image <stirling-image@users.noreply.github.com>

apps/api/src/routes/tools/index.ts

@@ -24,6 +24,7 @@ import { registerGifTools } from "./gif-tools.js";
 import { registerImageEnhancement } from "./image-enhancement.js";
 import { registerImageToPdf } from "./image-to-pdf.js";
 import { registerInfo } from "./info.js";
+import { registerNoiseRemoval } from "./noise-removal.js";
 import { registerOcr } from "./ocr.js";
 import { registerPdfToImage } from "./pdf-to-image.js";
 import { registerQrGenerate } from "./qr-generate.js";
@@ -132,6 +133,7 @@ export async function registerToolRoutes(app: FastifyInstance): Promise<void> {
     { id: "image-enhancement", register: registerImageEnhancement },
     { id: "content-aware-resize", register: registerContentAwareResize },
     { id: "colorize", register: registerColorize },
+    { id: "noise-removal", register: registerNoiseRemoval },
   ];
 
   let skipped = 0;

apps/api/src/routes/tools/noise-removal.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { noiseRemoval } from "@stirling-image/ai";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import { autoOrient } from "../../lib/auto-orient.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
+import { decodeHeic } from "../../lib/heic-converter.js";
+import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
+import { registerToolProcessFn } from "../tool-factory.js";
+
+const settingsSchema = z.object({
+  tier: z.enum(["quick", "balanced", "quality", "maximum"]).default("balanced"),
+  strength: z.union([z.number(), z.string()]).transform(Number).default(50),
+  detailPreservation: z.union([z.number(), z.string()]).transform(Number).default(50),
+  colorNoise: z.union([z.number(), z.string()]).transform(Number).default(30),
+  format: z.enum(["original", "png", "jpeg", "webp"]).default("original"),
+  quality: z.union([z.number(), z.string()]).transform(Number).default(90),
+});
+
+/**
+ * AI noise removal route.
+ * Uses the Python sidecar for multi-tier denoising.
+ */
+export function registerNoiseRemoval(app: FastifyInstance) {
+  app.post("/api/v1/tools/noise-removal", async (request: FastifyRequest, reply: FastifyReply) => {
+    let fileBuffer: Buffer | null = null;
+    let filename = "image";
+    let settingsRaw: string | null = null;
+    let clientJobId: string | null = null;
+
+    try {
+      const parts = request.parts();
+      for await (const part of parts) {
+        if (part.type === "file") {
+          const chunks: Buffer[] = [];
+          for await (const chunk of part.file) {
+            chunks.push(chunk);
+          }
+          fileBuffer = Buffer.concat(chunks);
+          filename = part.filename ?? "image";
+        } else if (part.fieldname === "settings") {
+          settingsRaw = part.value as string;
+        } else if (part.fieldname === "clientJobId") {
+          clientJobId = part.value as string;
+        }
+      }
+    } catch (err) {
+      return reply.status(400).send({
+        error: "Failed to parse multipart request",
+        details: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    if (!fileBuffer || fileBuffer.length === 0) {
+      return reply.status(400).send({ error: "No image file provided" });
+    }
+
+    const validation = await validateImageBuffer(fileBuffer);
+    if (!validation.valid) {
+      return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+    }
+
+    try {
+      const parsed = settingsSchema.parse(settingsRaw ? JSON.parse(settingsRaw) : {});
+      request.log.info(
+        { toolId: "noise-removal", imageSize: fileBuffer.length, tier: parsed.tier },
+        "Starting noise removal",
+      );
+
+      // Decode HEIC/HEIF input via system decoder
+      if (validation.format === "heif") {
+        fileBuffer = await decodeHeic(fileBuffer);
+      }
+
+      // Auto-orient to fix EXIF rotation before processing
+      fileBuffer = await autoOrient(fileBuffer);
+
+      const jobId = randomUUID();
+      const workspacePath = await createWorkspace(jobId);
+
+      // Progress callback
+      const jobIdForProgress = clientJobId;
+      const onProgress = jobIdForProgress
+        ? (percent: number, stage: string) => {
+            updateSingleFileProgress({
+              jobId: jobIdForProgress,
+              phase: "processing",
+              stage,
+              percent,
+            });
+          }
+        : undefined;
+
+      const result = await noiseRemoval(
+        fileBuffer,
+        join(workspacePath, "output"),
+        {
+          tier: parsed.tier,
+          strength: parsed.strength,
+          detailPreservation: parsed.detailPreservation,
+          colorNoise: parsed.colorNoise,
+          format: parsed.format,
+          quality: parsed.quality,
+        },
+        onProgress,
+      );
+
+      if (clientJobId) {
+        updateSingleFileProgress({
+          jobId: clientJobId,
+          phase: "complete",
+          percent: 100,
+        });
+      }
+
+      const CONTENT_TYPES: Record<string, string> = {
+        png: "image/png",
+        jpeg: "image/jpeg",
+        jpg: "image/jpeg",
+        webp: "image/webp",
+      };
+      const contentType = CONTENT_TYPES[result.format] || "image/png";
+      const ext = result.format === "jpeg" ? "jpg" : result.format;
+      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_denoised.${ext}`;
+
+      return reply
+        .header("Content-Type", contentType)
+        .header("Content-Disposition", `attachment; filename="${outputFilename}"`)
+        .header("X-Image-Width", String(result.width))
+        .header("X-Image-Height", String(result.height))
+        .send(result.buffer);
+    } catch (err) {
+      request.log.error({ err, toolId: "noise-removal" }, "Noise removal failed");
+      return reply.status(422).send({
+        error: "Noise removal failed",
+        details: err instanceof Error ? err.message : "Unknown error",
+      });
+    }
+  });
+
+  // Register in the pipeline/batch registry so this tool can be used
+  // as a step in automation pipelines (without progress callbacks).
+  registerToolProcessFn({
+    toolId: "noise-removal",
+    settingsSchema: z.object({
+      tier: z.enum(["quick", "balanced", "quality", "maximum"]).default("balanced"),
+      strength: z.union([z.number(), z.string()]).transform(Number).default(50),
+      detailPreservation: z.union([z.number(), z.string()]).transform(Number).default(50),
+      colorNoise: z.union([z.number(), z.string()]).transform(Number).default(30),
+      format: z.enum(["original", "png", "jpeg", "webp"]).default("original"),
+      quality: z.union([z.number(), z.string()]).transform(Number).default(90),
+    }),
+    process: async (inputBuffer, settings, filename) => {
+      const s = settings as z.infer<typeof settingsSchema>;
+      const orientedBuffer = await autoOrient(inputBuffer);
+      const jobId = randomUUID();
+      const workspacePath = await createWorkspace(jobId);
+      const result = await noiseRemoval(orientedBuffer, join(workspacePath, "output"), {
+        tier: s.tier,
+        strength: s.strength,
+        detailPreservation: s.detailPreservation,
+        colorNoise: s.colorNoise,
+        format: s.format,
+        quality: s.quality,
+      });
+      const ext = result.format === "jpeg" ? "jpg" : result.format;
+      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_denoised.${ext}`;
+      const CONTENT_TYPES: Record<string, string> = {
+        png: "image/png",
+        jpeg: "image/jpeg",
+        jpg: "image/jpeg",
+        webp: "image/webp",
+      };
+      return {
+        buffer: result.buffer,
+        filename: outputFilename,
+        contentType: CONTENT_TYPES[result.format] || "image/png",
+      };
+    },
+  });
+}

apps/web/src/components/tools/noise-removal-settings.tsx

@@ -0,0 +1,290 @@
+import { Download } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { ProgressCard } from "@/components/common/progress-card";
+import { useToolProcessor } from "@/hooks/use-tool-processor";
+import { useFileStore } from "@/stores/file-store";
+
+type Tier = "quick" | "balanced" | "quality" | "maximum";
+
+const TIERS: { id: Tier; label: string; desc: string }[] = [
+  { id: "quick", label: "Quick", desc: "Fast, lightweight" },
+  { id: "balanced", label: "Balanced", desc: "Good quality, moderate speed" },
+  { id: "quality", label: "Quality", desc: "AI-powered, slow" },
+  { id: "maximum", label: "Maximum", desc: "Best AI model, slowest" },
+];
+
+const LOSSY_FORMATS = new Set(["jpeg", "webp"]);
+
+export interface NoiseRemovalControlsProps {
+  settings?: Record<string, unknown>;
+  onChange?: (settings: Record<string, unknown>) => void;
+}
+
+export function NoiseRemovalControls({
+  settings: initialSettings,
+  onChange,
+}: NoiseRemovalControlsProps) {
+  const [tier, setTier] = useState<Tier>("balanced");
+  const [strength, setStrength] = useState(50);
+  const [detailPreservation, setDetailPreservation] = useState(50);
+  const [colorNoise, setColorNoise] = useState(30);
+  const [outputFormat, setOutputFormat] = useState<"original" | "png" | "jpeg" | "webp">(
+    "original",
+  );
+  const [quality, setQuality] = useState(90);
+
+  // One-time init from pipeline settings
+  const initializedRef = useRef(false);
+  useEffect(() => {
+    if (!initialSettings || initializedRef.current) return;
+    initializedRef.current = true;
+    if (initialSettings.tier != null) setTier(initialSettings.tier as Tier);
+    if (initialSettings.strength != null) setStrength(Number(initialSettings.strength));
+    if (initialSettings.detailPreservation != null)
+      setDetailPreservation(Number(initialSettings.detailPreservation));
+    if (initialSettings.colorNoise != null) setColorNoise(Number(initialSettings.colorNoise));
+    if (initialSettings.format != null)
+      setOutputFormat(initialSettings.format as "original" | "png" | "jpeg" | "webp");
+    if (initialSettings.quality != null) setQuality(Number(initialSettings.quality));
+  }, [initialSettings]);
+
+  // Emit settings on change
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+
+  useEffect(() => {
+    onChangeRef.current?.({
+      tier,
+      strength,
+      detailPreservation,
+      colorNoise,
+      format: outputFormat,
+      quality,
+    });
+  }, [tier, strength, detailPreservation, colorNoise, outputFormat, quality]);
+
+  const tabClass = (active: boolean) =>
+    `flex-1 text-xs py-1.5 rounded ${active ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground hover:bg-muted/80"}`;
+
+  const activeTier = TIERS.find((t) => t.id === tier);
+
+  return (
+    <div className="space-y-4">
+      {/* Tier selector */}
+      <div>
+        <p className="text-xs text-muted-foreground mb-1">Denoising Tier</p>
+        <div className="grid grid-cols-4 gap-1">
+          {TIERS.map((t) => (
+            <button
+              key={t.id}
+              type="button"
+              onClick={() => setTier(t.id)}
+              className={`flex flex-col items-center gap-0.5 text-xs py-2 rounded transition-colors ${
+                tier === t.id
+                  ? "bg-primary text-primary-foreground"
+                  : "bg-muted text-muted-foreground hover:bg-muted/80"
+              }`}
+            >
+              {t.label}
+            </button>
+          ))}
+        </div>
+        {activeTier && <p className="text-[10px] text-muted-foreground mt-1">{activeTier.desc}</p>}
+      </div>
+
+      <div className="border-t border-border pt-3" />
+
+      {/* Strength slider */}
+      <div>
+        <div className="flex justify-between items-center">
+          <p className="text-sm font-medium text-muted-foreground">Strength</p>
+          <span className="text-sm font-mono tabular-nums font-medium">{strength}</span>
+        </div>
+        <input
+          type="range"
+          min={0}
+          max={100}
+          step={1}
+          value={strength}
+          onChange={(e) => setStrength(Number(e.target.value))}
+          className="w-full h-1.5 rounded-full appearance-none bg-muted accent-primary"
+        />
+        <div className="flex justify-between text-[10px] text-muted-foreground mt-0.5">
+          <span>Subtle</span>
+          <span>Aggressive</span>
+        </div>
+      </div>
+
+      {/* Detail Preservation slider */}
+      <div>
+        <div className="flex justify-between items-center">
+          <p className="text-sm font-medium text-muted-foreground">Detail Preservation</p>
+          <span className="text-sm font-mono tabular-nums font-medium">{detailPreservation}</span>
+        </div>
+        <input
+          type="range"
+          min={0}
+          max={100}
+          step={1}
+          value={detailPreservation}
+          onChange={(e) => setDetailPreservation(Number(e.target.value))}
+          className="w-full h-1.5 rounded-full appearance-none bg-muted accent-primary"
+        />
+        <div className="flex justify-between text-[10px] text-muted-foreground mt-0.5">
+          <span>Smooth</span>
+          <span>Sharp</span>
+        </div>
+      </div>
+
+      {/* Color Noise slider */}
+      <div>
+        <div className="flex justify-between items-center">
+          <p className="text-sm font-medium text-muted-foreground">Color Noise</p>
+          <span className="text-sm font-mono tabular-nums font-medium">{colorNoise}</span>
+        </div>
+        <input
+          type="range"
+          min={0}
+          max={100}
+          step={1}
+          value={colorNoise}
+          onChange={(e) => setColorNoise(Number(e.target.value))}
+          className="w-full h-1.5 rounded-full appearance-none bg-muted accent-primary"
+        />
+        <div className="flex justify-between text-[10px] text-muted-foreground mt-0.5">
+          <span>Off</span>
+          <span>Heavy</span>
+        </div>
+      </div>
+
+      <div className="border-t border-border pt-3" />
+
+      {/* Output format */}
+      <div>
+        <p className="text-xs text-muted-foreground mb-1">Output Format</p>
+        <div className="grid grid-cols-4 gap-1">
+          {(["original", "png", "jpeg", "webp"] as const).map((f) => (
+            <button
+              key={f}
+              type="button"
+              onClick={() => setOutputFormat(f)}
+              className={tabClass(outputFormat === f)}
+            >
+              {f === "original" ? "Original" : f.toUpperCase()}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Quality slider (lossy formats only) */}
+      {LOSSY_FORMATS.has(outputFormat) && (
+        <div>
+          <div className="flex justify-between items-center">
+            <p className="text-sm font-medium text-muted-foreground">Quality</p>
+            <span className="text-sm font-mono tabular-nums font-medium">{quality}</span>
+          </div>
+          <input
+            type="range"
+            min={1}
+            max={100}
+            step={1}
+            value={quality}
+            onChange={(e) => setQuality(Number(e.target.value))}
+            className="w-full h-1.5 rounded-full appearance-none bg-muted accent-primary"
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function NoiseRemovalSettings() {
+  const { files, entries } = useFileStore();
+  const {
+    processFiles,
+    processAllFiles,
+    processing,
+    error,
+    downloadUrl,
+    originalSize,
+    processedSize,
+    progress,
+  } = useToolProcessor("noise-removal");
+  const [settings, setSettings] = useState<Record<string, unknown>>({});
+
+  const handleProcess = () => {
+    if (files.length > 1) {
+      processAllFiles(files, settings);
+    } else {
+      processFiles(files, settings);
+    }
+  };
+
+  const hasFile = files.length > 0;
+  const hasMultiple = files.length > 1;
+
+  // Warn about GIF + AI tiers
+  const isGif = entries.some((e) => e.file.type === "image/gif");
+  const isAiTier = settings.tier === "quality" || settings.tier === "maximum";
+
+  return (
+    <div className="space-y-4">
+      <NoiseRemovalControls onChange={setSettings} />
+
+      {/* GIF + AI tier warning */}
+      {isGif && isAiTier && (
+        <p className="text-xs text-amber-500">
+          AI denoising on GIF files processes only the first frame. For animated GIFs, use the Quick
+          or Balanced tier.
+        </p>
+      )}
+
+      {/* Error */}
+      {error && <p className="text-xs text-red-500">{error}</p>}
+
+      {/* Size info */}
+      {originalSize != null && processedSize != null && (
+        <div className="text-xs text-muted-foreground space-y-0.5">
+          <p>Original: {(originalSize / 1024).toFixed(1)} KB</p>
+          <p>Denoised: {(processedSize / 1024).toFixed(1)} KB</p>
+        </div>
+      )}
+
+      {/* Process button / progress */}
+      {processing ? (
+        <ProgressCard
+          active={processing}
+          phase={progress.phase === "idle" ? "uploading" : progress.phase}
+          label={hasMultiple ? `Removing noise from ${files.length} images` : "Removing noise"}
+          percent={progress.percent}
+          elapsed={progress.elapsed}
+        />
+      ) : (
+        <button
+          type="button"
+          data-testid="noise-removal-submit"
+          onClick={handleProcess}
+          disabled={!hasFile || processing}
+          className="w-full py-2.5 rounded-lg bg-primary text-primary-foreground font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+        >
+          {hasMultiple ? `Remove Noise (${files.length} files)` : "Remove Noise"}
+        </button>
+      )}
+
+      {/* Download (single file - batch uses Download All ZIP in tool-page) */}
+      {!hasMultiple && downloadUrl && (
+        <a
+          href={downloadUrl}
+          download
+          data-testid="noise-removal-download"
+          className="w-full py-2.5 rounded-lg border border-primary text-primary font-medium flex items-center justify-center gap-2 hover:bg-primary/5"
+        >
+          <Download className="h-4 w-4" />
+          Download
+        </a>
+      )}
+    </div>
+  );
+}

apps/web/src/components/tools/pipeline-step-settings.tsx

@@ -5,6 +5,7 @@ import { CompressControls } from "./compress-settings";
 import { ConvertControls } from "./convert-settings";
 import { CropControls } from "./crop-settings";
 import { GifToolsControls } from "./gif-tools-settings";
+import { NoiseRemovalControls } from "./noise-removal-settings";
 import { RemoveBgControls } from "./remove-bg-settings";
 import { ReplaceColorControls } from "./replace-color-settings";
 import { ResizeControls } from "./resize-settings";
@@ -44,6 +45,8 @@ export function PipelineStepSettings({ toolId, settings, onChange }: PipelineSte
   if (toolId === "blur-faces") return <BlurFacesControls settings={settings} onChange={onChange} />;
   if (toolId === "remove-background")
     return <RemoveBgControls settings={settings} onChange={onChange} />;
+  if (toolId === "noise-removal")
+    return <NoiseRemovalControls settings={settings} onChange={onChange} />;
   if (COLOR_TOOL_IDS.has(toolId))
     return <ColorControls toolId={toolId} settings={settings} onChange={onChange} />;
 

apps/web/src/lib/tool-registry.tsx

@@ -249,6 +249,11 @@ const ColorizeSettings = lazy(() =>
     default: m.ColorizeSettings,
   })),
 );
+const NoiseRemovalSettings = lazy(() =>
+  import("@/components/tools/noise-removal-settings").then((m) => ({
+    default: m.NoiseRemovalSettings,
+  })),
+);
 
 // ── Color tool wrapper ─────────────────────────────────────────────
 // Color tools share a single component but differ by toolId.
@@ -378,6 +383,7 @@ export const toolRegistry = new Map<string, ToolRegistryEntry>([
     },
   ],
   ["colorize", { displayMode: "before-after", Settings: ColorizeSettings }],
+  ["noise-removal", { displayMode: "before-after", Settings: NoiseRemovalSettings }],
 ]);
 
 export function getToolRegistryEntry(toolId: string): ToolRegistryEntry | undefined {