Add optimized tutorial cover images

server/_core/index.ts

@@ -11,6 +11,7 @@ import { registerMediaProxy } from "./mediaProxy";
 import { serveStatic } from "./static";
 import { createBackgroundTask, getAdminUserId, hasRecentBackgroundTaskOfType, seedAchievementDefinitions, seedAppSettings, seedTutorials, seedVisionReferenceImages } from "../db";
 import { nanoid } from "nanoid";
+import { syncTutorialImages } from "../tutorialImages";
 
 async function scheduleDailyNtrpRefresh() {
   const now = new Date();
@@ -64,6 +65,7 @@ async function findAvailablePort(startPort: number = 3000): Promise<number> {
 
 async function startServer() {
   await seedTutorials();
+  await syncTutorialImages();
   await seedVisionReferenceImages();
   await seedAchievementDefinitions();
   await seedAppSettings();

server/tutorialImageCatalog.ts

@@ -0,0 +1,69 @@
+export type TutorialImageSpec = {
+  imageUrl: string;
+  sourcePageUrl: string;
+  sourceLabel: string;
+};
+
+export const TUTORIAL_IMAGE_LIBRARY = {
+  forehand: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/0/00/Ray_Dunlop_forehand.jpg",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Ray_Dunlop_forehand.jpg",
+    sourceLabel: "Wikimedia Commons",
+  },
+  backhand: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/8/8c/Backhand_Federer.jpg",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Backhand_Federer.jpg",
+    sourceLabel: "Wikimedia Commons",
+  },
+  serve: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/8/85/Serena_Williams_Serves.JPG",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Serena_Williams_Serves.JPG",
+    sourceLabel: "Wikimedia Commons",
+  },
+  volley: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/a/af/Ernest_w._lewis%2C_volleying.jpg",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Ernest_w._lewis,_volleying.jpg",
+    sourceLabel: "Wikimedia Commons",
+  },
+  action: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/3/34/Frances_Tiafoe_Backhand.jpg",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Frances_Tiafoe_Backhand.jpg",
+    sourceLabel: "Wikimedia Commons",
+  },
+  wall: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/2/2c/Tennis_wall.jpg",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Tennis_wall.jpg",
+    sourceLabel: "Wikimedia Commons",
+  },
+  strategy: {
+    imageUrl: "https://upload.wikimedia.org/wikipedia/commons/f/f3/Court_plan.png",
+    sourcePageUrl: "https://commons.wikimedia.org/wiki/File:Court_plan.png",
+    sourceLabel: "Wikimedia Commons",
+  },
+} satisfies Record<string, TutorialImageSpec>;
+
+const CATEGORY_TO_IMAGE: Record<string, keyof typeof TUTORIAL_IMAGE_LIBRARY> = {
+  forehand: "forehand",
+  backhand: "backhand",
+  serve: "serve",
+  volley: "volley",
+  footwork: "action",
+  shadow: "forehand",
+  wall: "wall",
+  fitness: "action",
+  strategy: "strategy",
+};
+
+export function buildTutorialImageKey(slug: string) {
+  return `tutorials/${slug}.webp`;
+}
+
+export function buildTutorialImageUrl(slug: string) {
+  return `/uploads/${buildTutorialImageKey(slug)}`;
+}
+
+export function getTutorialImageSpec(category: string): TutorialImageSpec | null {
+  const imageKey = CATEGORY_TO_IMAGE[category];
+  if (!imageKey) return null;
+  return TUTORIAL_IMAGE_LIBRARY[imageKey];
+}

server/tutorialImages.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildTutorialImageFfmpegArgs,
+  buildTutorialImageKey,
+  buildTutorialImageUrl,
+  getTutorialImageSpec,
+} from "./tutorialImages";
+
+describe("tutorialImages", () => {
+  it("maps tennis categories to image specs", () => {
+    expect(getTutorialImageSpec("forehand")?.sourcePageUrl).toContain("Ray_Dunlop_forehand");
+    expect(getTutorialImageSpec("backhand")?.sourcePageUrl).toContain("Backhand_Federer");
+    expect(getTutorialImageSpec("serve")?.sourcePageUrl).toContain("Serena_Williams_Serves");
+    expect(getTutorialImageSpec("wall")?.sourcePageUrl).toContain("Tennis_wall");
+    expect(getTutorialImageSpec("unknown")).toBeNull();
+  });
+
+  it("builds stable storage keys and public URLs", () => {
+    expect(buildTutorialImageKey("forehand-fundamentals")).toBe("tutorials/forehand-fundamentals.webp");
+    expect(buildTutorialImageUrl("forehand-fundamentals")).toBe("/uploads/tutorials/forehand-fundamentals.webp");
+  });
+
+  it("uses a fixed compression pipeline for tutorial images", () => {
+    const args = buildTutorialImageFfmpegArgs("/tmp/input.jpg", "/tmp/output.webp");
+
+    expect(args).toEqual([
+      "-y",
+      "-i",
+      "/tmp/input.jpg",
+      "-vf",
+      "scale=1200:675:force_original_aspect_ratio=increase,crop=1200:675",
+      "-frames:v",
+      "1",
+      "-c:v",
+      "libwebp",
+      "-quality",
+      "78",
+      "-compression_level",
+      "6",
+      "/tmp/output.webp",
+    ]);
+  });
+});

server/tutorialImages.ts

@@ -0,0 +1,178 @@
+import { execFile } from "node:child_process";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { and, asc, eq } from "drizzle-orm";
+import { tutorialVideos } from "../drizzle/schema";
+import { getDb } from "./db";
+import { ENV } from "./_core/env";
+import { storagePut } from "./storage";
+import {
+  buildTutorialImageKey,
+  buildTutorialImageUrl,
+  getTutorialImageSpec,
+  type TutorialImageSpec,
+} from "./tutorialImageCatalog";
+
+export { buildTutorialImageKey, buildTutorialImageUrl, getTutorialImageSpec } from "./tutorialImageCatalog";
+
+const execFileAsync = promisify(execFile);
+
+const OUTPUT_WIDTH = 1200;
+const OUTPUT_HEIGHT = 675;
+const OUTPUT_QUALITY = 78;
+const OUTPUT_COMPRESSION_LEVEL = 6;
+
+type TutorialRow = {
+  id: number;
+  slug: string | null;
+  category: string;
+  title: string;
+  thumbnailUrl: string | null;
+  externalUrl: string | null;
+  sourcePlatform: string | null;
+};
+
+function normalizeSlug(slug: string | null, tutorialId: number) {
+  return slug?.trim() ? slug.trim() : `tutorial-${tutorialId}`;
+}
+
+export function buildTutorialImageFfmpegArgs(inputPath: string, outputPath: string) {
+  return [
+    "-y",
+    "-i",
+    inputPath,
+    "-vf",
+    `scale=${OUTPUT_WIDTH}:${OUTPUT_HEIGHT}:force_original_aspect_ratio=increase,crop=${OUTPUT_WIDTH}:${OUTPUT_HEIGHT}`,
+    "-frames:v",
+    "1",
+    "-c:v",
+    "libwebp",
+    "-quality",
+    `${OUTPUT_QUALITY}`,
+    "-compression_level",
+    `${OUTPUT_COMPRESSION_LEVEL}`,
+    outputPath,
+  ];
+}
+
+function isTutorialImageCurrent(tutorial: TutorialRow, spec: TutorialImageSpec, expectedUrl: string) {
+  return tutorial.thumbnailUrl === expectedUrl
+    && tutorial.externalUrl === spec.sourcePageUrl
+    && tutorial.sourcePlatform === "wikimedia";
+}
+
+function canUseRemoteStorage() {
+  return Boolean(ENV.forgeApiUrl && ENV.forgeApiKey);
+}
+
+async function localAssetExists(slug: string) {
+  const filePath = path.join(ENV.localStorageDir, buildTutorialImageKey(slug));
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function downloadSourceImage(url: string) {
+  const response = await fetch(url, {
+    headers: {
+      "accept": "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+      "user-agent": "tennis-training-hub/1.0 (+https://te.hao.work/)",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Image download failed (${response.status}): ${url}`);
+  }
+
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.startsWith("image/")) {
+    throw new Error(`Unexpected image content-type: ${contentType || "unknown"}`);
+  }
+
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function normalizeTutorialImage(buffer: Buffer) {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "tutorial-image-"));
+  const inputPath = path.join(tempDir, "source.input");
+  const outputPath = path.join(tempDir, "tutorial.webp");
+
+  try {
+    await writeFile(inputPath, buffer);
+    await execFileAsync("ffmpeg", buildTutorialImageFfmpegArgs(inputPath, outputPath), {
+      timeout: 30_000,
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    return await readFile(outputPath);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function syncTutorialImages() {
+  const db = await getDb();
+  if (!db) return { updated: 0, skipped: 0, failed: 0 };
+
+  const tutorials = await db.select({
+    id: tutorialVideos.id,
+    slug: tutorialVideos.slug,
+    category: tutorialVideos.category,
+    title: tutorialVideos.title,
+    thumbnailUrl: tutorialVideos.thumbnailUrl,
+    externalUrl: tutorialVideos.externalUrl,
+    sourcePlatform: tutorialVideos.sourcePlatform,
+  }).from(tutorialVideos)
+    .where(and(eq(tutorialVideos.topicArea, "tennis_skill"), eq(tutorialVideos.isPublished, 1)))
+    .orderBy(asc(tutorialVideos.sortOrder), asc(tutorialVideos.id));
+
+  let updated = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const tutorial of tutorials) {
+    const spec = getTutorialImageSpec(tutorial.category);
+    if (!spec) {
+      skipped += 1;
+      continue;
+    }
+
+    const slug = normalizeSlug(tutorial.slug, tutorial.id);
+    const expectedUrl = buildTutorialImageUrl(slug);
+    const assetExists = await localAssetExists(slug);
+
+    if (canUseRemoteStorage() && tutorial.thumbnailUrl && tutorial.externalUrl === spec.sourcePageUrl && tutorial.sourcePlatform === "wikimedia") {
+      skipped += 1;
+      continue;
+    }
+
+    if (assetExists && isTutorialImageCurrent(tutorial, spec, expectedUrl)) {
+      skipped += 1;
+      continue;
+    }
+
+    try {
+      const sourceBuffer = await downloadSourceImage(spec.imageUrl);
+      const webpBuffer = await normalizeTutorialImage(sourceBuffer);
+      const stored = await storagePut(buildTutorialImageKey(slug), webpBuffer, "image/webp");
+
+      await db.update(tutorialVideos).set({
+        thumbnailUrl: stored.url,
+        externalUrl: spec.sourcePageUrl,
+        sourcePlatform: "wikimedia",
+      }).where(eq(tutorialVideos.id, tutorial.id));
+
+      updated += 1;
+    } catch (error) {
+      failed += 1;
+      console.error(`[TutorialImages] Failed to sync ${tutorial.title}:`, error);
+    }
+  }
+
+  console.log(`[TutorialImages] sync complete: updated=${updated} skipped=${skipped} failed=${failed}`);
+  return { updated, skipped, failed };
+}