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/routes/attachments.ts

@@ -4,9 +4,10 @@
  *
  * - `POST /api/attachments` — signed in. Stores an image (multipart `file`, at
  *   most 5 MB) and answers its id.
- * - `GET /api/attachments/:attachmentId?token=` — public, but an image in a
- *   private dump or playlist, or in a comment on a private dump, needs its
- *   owner's media `token`. Serves the image.
+ * - `GET /api/attachments/:attachmentId?w=&token=` — public, but an image in
+ *   a private dump or playlist, or in a comment on a private dump, needs its
+ *   owner's media `token`. Serves the image, scaled down to `w`
+ *   (`shared/image.ts`) when it names one.
  *
  * @module
  */

api/routes/avatars.ts

@@ -1,14 +1,14 @@
 /**
  * Stores and serves the users' avatars. The profile page uploads the avatar,
- * and the client's `Avatar` component loads it, with the user's `updatedAt` as
- * a cache-busting version.
+ * and the client's `Avatar` component loads it at the size it shows, with the
+ * user's `updatedAt` as a cache-busting version.
  *
  * - `PUT /api/me/avatar` — signed in. Replaces the caller's avatar (multipart
  *   `file`, at most 5 MB), sends `user_updated` to everyone, and answers the
  *   caller's user. 400 for an account from another instance, whose avatar
  *   comes from there. The instances the caller signed in to are told.
- * - `GET /api/users/:key/avatar` — public. Serves a user's avatar; 404 without
- *   one.
+ * - `GET /api/users/:key/avatar?w=` — public. Serves a user's avatar, scaled
+ *   down to `w` (`shared/image.ts`) when it names one; 404 without one.
  *
  * @module
  */

api/routes/playlists.ts

@@ -26,9 +26,9 @@
  *   or with `playlist:moderate`. Removes a dump.
  * - `PUT /api/playlists/:playlistId/cover` — signed in, as its owner or with
  *   `playlist:moderate`. Replaces its cover (multipart `file`, at most 5 MB).
- * - `GET /api/playlists/:playlistId/cover?token=` — public, but a private
- *   playlist's cover needs its owner's media `token`. Serves its cover, or 404s
- *   without one.
+ * - `GET /api/playlists/:playlistId/cover?w=&token=` — public, but a private
+ *   playlist's cover needs its owner's media `token`. Serves its cover, scaled
+ *   down to `w` (`shared/image.ts`) when it names one, or 404s without one.
  * - `PUT /api/playlists/:playlistId/order` — signed in, as its owner or with
  *   `playlist:moderate`. Reorders the dumps the caller can see in it.
  *

api/routes/remote.ts

@@ -6,9 +6,9 @@
  *
  * - `GET /api/remote/preview?url=` — signed in. Answers the preview of a link,
  *   and whether its page could be reached.
- * - `GET /api/remote/image?url=` — public. Serves a remote raster image
- *   through this site; 400 when it isn't one, 502 when its host can't be
- *   reached.
+ * - `GET /api/remote/image?url=&w=` — public. Serves a remote raster image
+ *   through this site, scaled down to `w` (`shared/image.ts`) when it names
+ *   one; 400 when it isn't an image, 502 when its host can't be reached.
  * - `GET /api/remote/bandcamp?url=&force=` — public. Answers a Bandcamp
  *   page's tracks and their stream URLs, for the native player; `force=1`
  *   skips the server's cache.
@@ -19,6 +19,7 @@
  */
 
 import { Router } from "@oak/oak";
+import { parseImageWidth } from "../../shared/image.ts";
 import { isValidHttpUrl } from "../remote/fetch.ts";
 import { fetchProxiedImage } from "../remote/image-proxy.ts";
 import { resolveBandcamp } from "../remote/bandcamp-streams.ts";
@@ -88,7 +89,10 @@ router.get("/image", async (ctx) => {
   }
 
   try {
-    const image = await fetchProxiedImage(url);
+    const image = await fetchProxiedImage(
+      url,
+      parseImageWidth(ctx.request.url.searchParams.get("w")),
+    );
     if (!image) {
       ctx.response.status = 400;
       return;

api/routes/thumbnails.ts

@@ -5,11 +5,12 @@
  * from an upload are generated on first request by lib/ffmpeg.ts, which keeps
  * them.
  *
- * - `GET /api/dumps/:dumpId/thumbnail?v=&token=` — public; a private dump's
- *   thumbnail needs its poster's media `token`. Serves the dump's custom
- *   thumbnail, else one made from its upload: a still of a video, or a
- *   scaled-down copy of an image (the image itself when none can be made); 404
- *   when there is neither.
+ * - `GET /api/dumps/:dumpId/thumbnail?v=&w=&token=` — public; a private
+ *   dump's thumbnail needs its poster's media `token`. Serves the dump's
+ *   custom thumbnail, else one made from its upload: a still of a video, or
+ *   its image. An image comes scaled down to `w` (`shared/image.ts`), or to
+ *   the widest of those widths without one, and as it is when no copy can be
+ *   made; 404 when there is neither.
  * - `PUT /api/dumps/:dumpId/thumbnail` — signed in, as its poster or with
  *   `dump:moderate`. Replaces its custom thumbnail (multipart `file`, at most 5
  *   MB).
@@ -32,18 +33,14 @@ import {
 import { serveFile } from "../lib/serve-file.ts";
 import {
   replaceUploadedFile,
+  serveImage,
   serveUploadedFile,
   validateImageUpload,
 } from "../lib/upload.ts";
 import { DUMPS_DIR } from "../config.ts";
+import { MAX_IMAGE_WIDTH } from "../../shared/image.ts";
 import { resolveMediaDump } from "../lib/dump-media.ts";
-import {
-  ensureGenerated,
-  generatedPaths,
-  imagePreview,
-  PREVIEWABLE_IMAGES,
-  videoStill,
-} from "../lib/ffmpeg.ts";
+import { ensureGenerated, generatedPaths, videoStill } from "../lib/ffmpeg.ts";
 import { can } from "../lib/permissions.ts";
 import { type AuthContext, authMiddleware } from "../middleware/auth.ts";
 
@@ -69,6 +66,7 @@ router.get("/:dumpId/thumbnail", async (ctx) => {
       dump.thumbnailMime,
       0,
       dump.isPrivate,
+      MAX_IMAGE_WIDTH,
     );
     if (served) return;
   }
@@ -92,29 +90,12 @@ router.get("/:dumpId/thumbnail", async (ctx) => {
     ) return;
   }
 
-  if (mime.startsWith("image/")) {
-    // A scaled-down copy for the feed; the original when there's none to make
-    // (a GIF, no ffmpeg, an image ffmpeg can't read).
-    ctx.response.headers.set("X-Content-Type-Options", "nosniff");
-    const ext = PREVIEWABLE_IMAGES[mime];
-    if (ext) {
-      const previewPath = generated.preview[ext];
-      if (
-        await ensureGenerated(
-          previewPath,
-          () => imagePreview(srcPath, previewPath),
-        ) &&
-        await serveFile(ctx, previewPath, {
-          mime: ext === "png" ? "image/png" : "image/jpeg",
-          cacheControl: generatedCache,
-        })
-      ) return;
-    }
-    if (
-      /^image\/(png|jpeg|gif|webp|avif|bmp)$/.test(mime) &&
-      await serveFile(ctx, srcPath, { mime, cacheControl: generatedCache })
-    ) return;
-  }
+  // A scaled-down copy for the feed; the original when there's none to make
+  // (no ffmpeg, an image it can't read).
+  if (
+    /^image\/(png|jpeg|gif|webp|avif|bmp)$/.test(mime) &&
+    await serveImage(ctx, srcPath, mime, generatedCache, MAX_IMAGE_WIDTH)
+  ) return;
 
   throw new APIException(404, "No thumbnail for this dump");
 });