v4: every image the API serves comes scaled to the size it is shown at — a first visit to the feed loaded 4.8 MB of images out of 5.1 MB in all: an avatar shown at 32 pixels was the upload itself, a 1.4 MB GIF among them, and so were a cover, a custom thumbnail, an attachment and a proxied image, only an image dump having a preview, 960 pixels wide. Every route that answers an image now takes ?w= and sends a WebP copy at most that wide, of the widths shared/image.ts lists, 128, 320, 640 and 960, a width between two taking the one above, and never wider than the image; without it the upload goes out as before, a dump's thumbnail alone being scaled to the widest by default, the custom ones included. serveImage (lib/upload.ts) is where they all end, and the image proxy scales what it fetched the same way, keeping each width in its cache. lib/ffmpeg.ts makes the copies as it made the previews, which they replace: on first request, under uploads/scaled/ at the upload's own path, each given its upload's date and made again when the two differ, so a new avatar or cover needs nobody to delete the old ones. WebP keeps a PNG's transparency and a GIF's animation. A JPEG is turned by its EXIF orientation here, ffmpeg's own rotation of images depending on its version. An animated WebP, which ffmpeg can't read, and an image it fails on go out as they are, a failure being remembered until the upload changes. ?f=compat asks for the copy as a JPEG, or a PNG for what may be transparent: the digest's emails take their thumbnails that way, at 640 pixels, not every mail client reading WebP. On the client, imageProps (utils/shared/urls.ts) gives an image its srcset of those copies and the width it is laid out at, which config/imageSizes.ts states for each place from App.css: Avatar, Thumbnail, which scales an API image and leaves another site's as that site sends it, and the playlists' covers use it. The images of notes and comments still load as uploaded. The copies go with the dump, the custom thumbnail or the attachment they were made from, and generatedMediaSweepJob, a minute after the start then daily, takes those whose upload is gone, the previews under their former name and the temporary files a generation left unfinished.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/test/routes/avatars.test.ts

@@ -1,4 +1,14 @@
-import { createUser, formWithFile, get, PNG, put, test } from "../helpers.ts";
+import {
+  createUser,
+  formWithFile,
+  get,
+  hasFfmpeg,
+  makeImage,
+  PNG,
+  put,
+  test,
+  webpWidth,
+} from "../helpers.ts";
 import type { SelfUser } from "../../../shared/user.ts";
 import { assertEquals, assertFalse } from "@std/assert";
 
@@ -27,3 +37,35 @@ test("avatars: upload, serve, and 404 when there is none", async () => {
     400,
   );
 });
+
+test("avatars: `?w=` answers a scaled copy, made again from a new avatar", async () => {
+  if (!await hasFfmpeg()) return;
+  const user = await createUser();
+  const red = await makeImage(600, 400, "red");
+  await put("/api/me/avatar", { auth: user.auth, form: formWithFile(red) });
+
+  const small = await get(`/api/users/${user.id}/avatar?w=128`);
+  assertEquals(small.status, 200);
+  assertEquals(small.headers.get("content-type"), "image/webp");
+  assertEquals(small.headers.get("cache-control"), "public, max-age=3600");
+  assertEquals(webpWidth(small.bytes), 128);
+  // Never wider than the upload itself.
+  assertEquals(
+    webpWidth((await get(`/api/users/${user.id}/avatar?w=960`)).bytes),
+    600,
+  );
+  // Without a width, or with one that isn't a number, the upload goes out.
+  assertEquals((await get(`/api/users/${user.id}/avatar`)).bytes, red);
+  assertEquals((await get(`/api/users/${user.id}/avatar?w=big`)).bytes, red);
+
+  await put("/api/me/avatar", {
+    auth: user.auth,
+    form: formWithFile(await makeImage(600, 400, "blue")),
+  });
+  const again = await get(`/api/users/${user.id}/avatar?w=128`);
+  assertEquals(webpWidth(again.bytes), 128);
+  assertFalse(
+    again.bytes.length === small.bytes.length &&
+      again.bytes.every((b, i) => b === small.bytes[i]),
+  );
+});

api/test/routes/dumps.test.ts

@@ -5,6 +5,7 @@ import {
   del,
   formWithFile,
   get,
+  hasFfmpeg,
   html,
   insertCategory,
   insertComment,
@@ -767,16 +768,27 @@ test("custom thumbnails: set, served, removed", async () => {
   });
   assertEquals(set.status, 200);
   assertEquals(set.data.thumbnailMime, "image/png");
+  // A scaled copy by default, as for an upload's own thumbnail; the image
+  // itself where no copy can be made.
   const thumb = await get(`/api/dumps/${id}/thumbnail`);
   assertEquals(thumb.status, 200);
-  assertEquals(thumb.headers.get("content-type"), "image/png");
-  assertEquals(thumb.bytes, PNG);
+  if (await hasFfmpeg()) {
+    assertEquals(thumb.headers.get("content-type"), "image/webp");
+    assertEquals(
+      readFile(`scaled/thumbnails/${id}-custom.w960.webp`) !== null,
+      true,
+    );
+  } else {
+    assertEquals(thumb.headers.get("content-type"), "image/png");
+    assertEquals(thumb.bytes, PNG);
+  }
 
   const removed = await del<Dump>(`/api/dumps/${id}/thumbnail`, {
     auth: owner.auth,
   });
   assertEquals(removed.data.thumbnailMime, undefined);
   assertEquals(readFile(`thumbnails/${id}-custom`), null);
+  assertEquals(readFile(`scaled/thumbnails/${id}-custom.w960.webp`), null);
   // A URL dump without its own thumbnail has none to serve.
   assertEquals((await get(`/api/dumps/${id}/thumbnail`)).status, 404);
 });

api/test/routes/remote.test.ts

@@ -1,4 +1,12 @@
-import { get, html, PNG, stubNetwork } from "../helpers.ts";
+import {
+  get,
+  hasFfmpeg,
+  html,
+  makeImage,
+  PNG,
+  stubNetwork,
+  webpWidth,
+} from "../helpers.ts";
 import { assertEquals, assertFalse } from "@std/assert";
 import type { Tralbum, YouTubePlaylist } from "../../../shared/player.ts";
 
@@ -29,6 +37,25 @@ Deno.test("GET /api/remote/image: rasters only, fetched once for everyone", asyn
   assertEquals(svg.status, 400);
 });
 
+Deno.test("GET /api/remote/image: `?w=` scales the image, fetched once for every width", async () => {
+  if (!await hasFfmpeg()) return;
+  const wide = await makeImage(800, 200);
+  using net = stubNetwork(() =>
+    new Response(wide, { headers: { "content-type": "image/png" } })
+  );
+  const path = `/api/remote/image?url=${
+    encodeURIComponent("https://cdn.example.com/wide.png")
+  }`;
+  const small = await get(`${path}&w=128`);
+  assertEquals(small.status, 200);
+  assertEquals(small.headers.get("content-type"), "image/webp");
+  assertEquals(webpWidth(small.bytes), 128);
+  assertEquals(webpWidth((await get(`${path}&w=320`)).bytes), 320);
+  assertEquals((await get(`${path}&w=128`)).bytes, small.bytes);
+  assertEquals((await get(path)).bytes, wide);
+  assertEquals(net.calls.length, 1);
+});
+
 Deno.test("GET /api/remote/image: an error answer is never served nor cached", async () => {
   let failing = true;
   using net = stubNetwork(() =>

api/test/routes/thumbnails.test.ts

@@ -1,34 +1,24 @@
 import {
   createUser,
   db,
+  del,
   get,
+  hasFfmpeg,
   insertDump,
+  makeImage,
   PNG,
   test,
   TEST_DIR,
+  webpWidth,
 } from "../helpers.ts";
 import { assertEquals } from "@std/assert";
 
-const BYTES = new TextEncoder().encode("0123456789");
-
 function createdAtOf(id: string): string {
   return (db.prepare(`SELECT created_at FROM dumps WHERE id = ?;`).get(id) as {
     created_at: string;
   }).created_at;
 }
 
-async function hasFfmpeg(): Promise<boolean> {
-  try {
-    return (await new Deno.Command("ffmpeg", {
-      args: ["-version"],
-      stdout: "null",
-      stderr: "null",
-    }).output()).success;
-  } catch {
-    return false;
-  }
-}
-
 function readDir(path: string): string[] {
   try {
     return [...Deno.readDirSync(path)].map((e) => e.name);
@@ -81,54 +71,87 @@ test("GET /api/dumps/:id/thumbnail: serves a cached video still, with privacy",
   assertEquals((await get(`/api/dumps/nope/thumbnail`)).status, 400);
 });
 
-test("GET /api/dumps/:id/thumbnail: an image dump gets a preview, a GIF itself", async () => {
+test("GET /api/dumps/:id/thumbnail: an image dump gets a scaled copy, or itself when none can be made", async () => {
   const owner = await createUser();
+  const scaled = (id: string) =>
+    readDir(`${TEST_DIR}/uploads/scaled/dumps`).filter((n) => n.startsWith(id))
+      .sort();
+
+  // Not an image ffmpeg can read (or no ffmpeg at all): the original goes out.
   const gif = new TextEncoder().encode("GIF89a-not-really");
-  const animated = insertDump({
+  const broken = insertDump({
     userId: owner.id,
     fileName: "a.gif",
     fileMime: "image/gif",
     fileData: gif,
   });
-  const res = await get(`/api/dumps/${animated.id}/thumbnail`);
-  assertEquals(res.status, 200);
-  assertEquals(res.headers.get("content-type"), "image/gif");
-  assertEquals(res.bytes, gif);
+  const fallback = await get(`/api/dumps/${broken.id}/thumbnail`);
+  assertEquals(fallback.status, 200);
+  assertEquals(fallback.headers.get("content-type"), "image/gif");
+  assertEquals(fallback.bytes, gif);
+  assertEquals(scaled(broken.id), []);
 
-  // A real PNG is scaled into a preview, kept beside the video stills.
+  if (!await hasFfmpeg()) {
+    const photo = insertDump({
+      userId: owner.id,
+      fileName: "p.png",
+      fileMime: "image/png",
+      fileData: PNG,
+    });
+    const itself = await get(`/api/dumps/${photo.id}/thumbnail`);
+    assertEquals(itself.headers.get("content-type"), "image/png");
+    assertEquals(itself.bytes, PNG);
+    return;
+  }
+
+  // A real image is scaled to the widest width without `w`, and to the width
+  // asked for with it, each copy kept under the upload's own path.
   const photo = insertDump({
     userId: owner.id,
     fileName: "p.png",
     fileMime: "image/png",
-    fileData: PNG,
+    fileData: await makeImage(1400, 300),
   });
-  const preview = await get(`/api/dumps/${photo.id}/thumbnail`);
-  assertEquals(preview.status, 200);
-  assertEquals(preview.headers.get("content-type"), "image/png");
-  if (await hasFfmpeg()) {
-    assertEquals(
-      readDir(`${TEST_DIR}/uploads/thumbnails`).filter((n) =>
-        n.startsWith(photo.id)
-      ),
-      [`${photo.id}.preview.png`],
-    );
-  }
+  const widest = await get(`/api/dumps/${photo.id}/thumbnail`);
+  assertEquals(widest.status, 200);
+  assertEquals(widest.headers.get("content-type"), "image/webp");
+  assertEquals(webpWidth(widest.bytes), 960);
+  const small = await get(`/api/dumps/${photo.id}/thumbnail?w=128`);
+  assertEquals(small.headers.get("content-type"), "image/webp");
+  assertEquals(webpWidth(small.bytes), 128);
+  // A width between two of the list's takes the one above.
+  const between = await get(`/api/dumps/${photo.id}/thumbnail?w=200`);
+  assertEquals(webpWidth(between.bytes), 320);
+  assertEquals(scaled(photo.id), [
+    `${photo.id}.w128.webp`,
+    `${photo.id}.w320.webp`,
+    `${photo.id}.w960.webp`,
+  ]);
 
-  // Not an image ffmpeg can read (or no ffmpeg at all): the original goes out.
-  const broken = insertDump({
+  // A reader without WebP, as a mail client, asks for a PNG or a JPEG.
+  const compat = await get(`/api/dumps/${photo.id}/thumbnail?w=640&f=compat`);
+  assertEquals(compat.status, 200);
+  assertEquals(compat.headers.get("content-type"), "image/png");
+  // Its header states the width, on four bytes from the sixteenth.
+  assertEquals(new DataView(compat.bytes.buffer).getUint32(16), 640);
+  assertEquals(scaled(photo.id).includes(`${photo.id}.w640.png`), true);
+
+  // An animation keeps its frames.
+  const animated = insertDump({
     userId: owner.id,
-    fileName: "b.png",
-    fileMime: "image/png",
-    fileData: BYTES,
+    fileName: "anim.gif",
+    fileMime: "image/gif",
+    fileData: await makeImage(400, 300, "blue", "gif"),
   });
-  const fallback = await get(`/api/dumps/${broken.id}/thumbnail`);
-  assertEquals(fallback.status, 200);
-  assertEquals(fallback.headers.get("content-type"), "image/png");
-  assertEquals(fallback.bytes, BYTES);
+  const moving = await get(`/api/dumps/${animated.id}/thumbnail?w=128`);
+  assertEquals(moving.headers.get("content-type"), "image/webp");
+  assertEquals(webpWidth(moving.bytes), 128);
+  assertEquals(new TextDecoder().decode(moving.bytes).includes("ANMF"), true);
+
+  // The copies go with the dump.
   assertEquals(
-    readDir(`${TEST_DIR}/uploads/thumbnails`).filter((n) =>
-      n.startsWith(broken.id)
-    ),
-    [],
+    (await del(`/api/dumps/${photo.id}`, { auth: owner.auth })).status,
+    200,
   );
+  assertEquals(scaled(photo.id), []);
 });