DEV Community: haowen sun

Building a Frame-Aware GIF Face Swap Pipeline with Next.js and Replicate

haowen sun — Tue, 21 Jul 2026 15:11:44 +0000

I built a browser-based gif face swap tool that accepts an animated GIF plus a face image and returns a new GIF.

The difficult part wasn’t starting the AI model. It was handling a long-running media job without blocking the request or losing its state.

Stack

Next.js and TypeScript
Replicate for AI inference
Supabase for job and credit records
FFmpeg WASM for browser-side GIF utilities
Animated WebP for lightweight previews

Async generation

Instead of waiting for inference inside one HTTP request, I create a Replicate prediction and receive the result through a webhook:

export async function createPrediction(
  targetGifUrl: string,
  faceImageUrl: string,
) {
  const replicate = createReplicateClient();
  const webhook = replicateWebhookUrl();

  return replicate.predictions.create({
    version: REPLICATE_MODEL_VERSION,
    input: replicateInput(targetGifUrl, faceImageUrl),
    webhook,
    webhook_events_filter: webhook ? ["completed"] : undefined,
  });
}

Each Supabase job stores its prediction ID and one of five states:

type JobStatus =
  | "queued"
  | "processing"
  | "succeeded"
  | "failed"
  | "expired";

The frontend polls the job endpoint, while the webhook updates the final result. This also lets users refresh the page without losing an active generation.

Keeping the site fast

Original GIFs stay available for processing, but template previews are converted to animated WebP:

pnpm asset:gif-to-webp input.gif preview.webp

This keeps the UI lighter without modifying the source animation sent to the face-swap pipeline.

The main lesson: with AI media tools, inference is only half the work. Job state, webhooks, file handling, and failure recovery are what make the demo feel like a real product.

Building a Privacy-First Comment Image Generator with Next.js, SVG, and Canvas

haowen sun — Tue, 21 Jul 2026 14:18:52 +0000

Creators often need a comment visual as part of a video edit: a compact reply sticker for a hook, or a complete vertical thread for a mockup. The obvious implementation is to render some HTML and take a screenshot. I chose a different architecture for Comment Studio, a browser-based TikTok comment generator: React owns a structured scene, SVG provides the live preview, and Canvas performs the final PNG export.

This post explains why that pipeline works well, where it can fail, and how keeping the entire workflow in the browser improves both privacy and product simplicity.

Start with a scene model, not pixels

A comment image looks simple until every visual state becomes editable. Each row can have a username, avatar, message, timestamp, like count, verified state, pinned label, creator label, viewer-liked heart, liked-by-creator label, hidden reply count, and a nested creator reply.

Treating the preview as the source of truth quickly becomes fragile. Instead, I keep one typed scene object in React state:

type PreviewMode = "reply-sticker" | "comment-section";
type PreviewTheme = "transparent" | "light" | "dark";

type CommentItem = {
  id: string;
  identity: {
    username: string;
    avatarDataUrl: string;
    verified: boolean;
    isCreator: boolean;
  };
  comment: {
    message: string;
    time: string;
    likes: string;
    pinned: boolean;
    viewerLiked: boolean;
    likedByCreator: boolean;
  };
  reply?: {
    username: string;
    message: string;
    time: string;
    likes: string;
  };
};

type CommentScene = {
  mode: PreviewMode;
  theme: PreviewTheme;
  selectedId: string;
  comments: CommentItem[];
};

The production model has a few more details, but this shows the important boundary: the editor changes data, and the renderer turns that data into pixels. The same scene can drive a compact sticker or a 1080 × 1920 comment section without maintaining two unrelated editors.

One state object also makes actions such as duplicate, remove, select, and apply preset predictable. A preset is simply another valid scene rather than a bundle of imperative DOM changes.

Why SVG is the useful middle layer

The preview needs to solve two different jobs:

It must remain interactive in the browser.
It must export at a deterministic resolution.

SVG fits both. Text, avatars, icons, reply connectors, labels, and backgrounds remain regular inspectable elements. A comment group can receive a click handler for selection, while the root viewBox defines the coordinate system used during export.

This avoids coupling export size to the CSS size of the editor. The preview might be 360 pixels wide on a phone, but the scene can still describe a 1080 × 1920 output. For a reply sticker, the same vector scene can be exported at 1×, 2×, or 3× without redrawing every element manually on Canvas.

There is also a practical benefit: SVG makes transparent output straightforward. The clear sticker theme simply omits an opaque background before rasterization.

The SVG-to-PNG pipeline

The export path has five steps:

Read the base dimensions from the SVG viewBox.
Clone the SVG so export cleanup does not mutate the live preview.
Remove controls or selection hints marked as preview-only.
Serialize and decode the cloned SVG as an image.
Draw it to a scaled Canvas and encode a PNG blob.

Here is a reduced version of the renderer:

export async function renderSvgToPng(
  svg: SVGSVGElement,
  scale: number,
) {
  const { width: baseWidth, height: baseHeight } = svg.viewBox.baseVal;

  if (!baseWidth || !baseHeight) {
    throw new Error("The preview has no export dimensions.");
  }

  const clone = svg.cloneNode(true) as SVGSVGElement;
  clone
    .querySelectorAll("[data-preview-only]")
    .forEach((element) => element.remove());

  clone.setAttribute("xmlns", "http://www.w3.org/2000/svg");
  clone.setAttribute("width", String(baseWidth));
  clone.setAttribute("height", String(baseHeight));

  const source = new XMLSerializer().serializeToString(clone);
  const svgBlob = new Blob([source], {
    type: "image/svg+xml;charset=utf-8",
  });
  const objectUrl = URL.createObjectURL(svgBlob);

  try {
    const image = await loadImage(objectUrl);
    const width = Math.round(baseWidth * scale);
    const height = Math.round(baseHeight * scale);
    const canvas = document.createElement("canvas");

    canvas.width = width;
    canvas.height = height;

    const context = canvas.getContext("2d");
    if (!context) throw new Error("Canvas is unavailable.");

    context.imageSmoothingEnabled = true;
    context.imageSmoothingQuality = "high";
    context.drawImage(image, 0, 0, width, height);

    const png = await new Promise<Blob>((resolve, reject) => {
      canvas.toBlob(
        (result) => result ? resolve(result) : reject(new Error("PNG encoding failed.")),
        "image/png",
      );
    });

    return { blob: png, width, height };
  } finally {
    URL.revokeObjectURL(objectUrl);
  }
}

The production implementation revokes the temporary SVG URL as soon as the image finishes decoding. The downloadable PNG receives its own object URL, which is also revoked shortly after the temporary anchor is clicked. Explicit cleanup matters because repeated exports can otherwise leave unnecessary blobs alive for the rest of the session.

Keep uploaded avatars local

An avatar does not need a server upload just to appear in a generated image. The editor accepts PNG, JPEG, and WebP files, rejects unsupported types and files over 5 MB, then reads an approved file with FileReader:

const reader = new FileReader();

reader.onload = () => {
  updateIdentity({ avatarDataUrl: String(reader.result ?? "") });
};

reader.onerror = () => {
  setStatus("The avatar could not be read.");
};

reader.readAsDataURL(file);

The data URL becomes the SVG image source and is embedded in the exported PNG. It is never necessary to send the avatar, filename, username, or comment copy to an application server. Refreshing or closing the page clears the current scene.

This is more than a privacy feature. It removes an entire backend workflow: no upload endpoint, object storage, cleanup job, account system, or temporary-file retention policy is required.

Analytics should describe the workflow, not the content

A local editor can still answer product questions such as:

Which output mode is used more often?
Do people export at 1×, 2×, or 3×?
Which theme is selected?
Did an export succeed or fail?

It does not need the content of the scene to answer them. I use an event allowlist so each event accepts only coarse parameters such as mode, scale, theme, viewport group, broad browser group, duration bucket, or file-size bucket.

Free-form comment text, usernames, avatar data, filenames, and full user-agent strings are excluded. The architectural rule is simple: analytics can record what part of the workflow ran, never what the user created.

Where Next.js fits

The generator workspace is a client component because it depends on React state, file input, SVG references, Canvas, and download APIs. The rest of the site does not need to inherit that constraint.

Next.js App Router still handles the public page shell, metadata, structured data, blog routes, legal pages, and optimized static assets. Keeping the browser editor behind a clear client boundary lets the content pages retain a simpler rendering model while the interactive workspace uses browser-only APIs.

This separation is especially useful for a tool whose landing page must explain what it does before JavaScript interaction begins.

Lessons from the build

The main lessons are reusable beyond comment graphics:

Model editable visuals as structured data before thinking about export.
Use SVG when the preview must be both interactive and resolution-independent.
Clone and sanitize the export tree instead of modifying the live preview.
Revoke every object URL you create.
Keep private user content out of analytics by enforcing an allowlist in code.
Ask whether a local browser API can replace a backend workflow.

The result is a small architecture with a useful property: the same scene the user edits is the scene the browser exports. There is no remote rendering queue and no hidden copy of the conversation on a server.

If you want to inspect the finished workflow from a user’s perspective, try the live generator linked at the beginning of the article. I would be interested to hear how you handle SVG export, font consistency, and local-file privacy in your own browser tools.

I Built a Free Drawing Prompt Generator for Better Sketch Sessions

haowen sun — Tue, 21 Jul 2026 08:14:32 +0000

I built a free Drawing Prompt Generator for anyone who gets stuck wondering what to draw.

Choose a category, difficulty, and 1–30 minute timer to get a structured drawing idea—not just a random word. Prompts can be saved locally or shared with a repeatable link, and AI visual references are optional.

Try it here: https://www.drawingpromptgenerator.com/

Feedback is welcome!

Why GIF Uploads Fail (and How to Validate Them in the Browser)

haowen sun — Sun, 19 Jul 2026 00:59:12 +0000

GIF uploads look deceptively simple: pick a file, show a preview, send it to a server. In practice, animated files are one of the easiest ways to create slow uploads, failed jobs, and confusing error messages.

The reason is that a GIF's file size is only part of the cost. A short animation can contain hundreds of frames, and every frame has pixels that may need to be decoded, inspected, transformed, or sent to a model.

Here is the validation order I use before accepting an animated upload.

1. Treat the file extension as a hint, not proof

file.type is useful for UX, but it comes from the browser and can be missing or misleading. For GIFs, read the first six bytes and check the signature:

async function isGif(file) {
  const header = new Uint8Array(await file.slice(0, 6).arrayBuffer());
  const signature = new TextDecoder().decode(header);
  return signature === "GIF87a" || signature === "GIF89a";
}

This does not prove that every frame is valid, but it catches renamed files before they enter the more expensive path.

2. Set a file-size limit before decoding

Always reject oversized uploads on the client before starting an upload. The limit should be a product decision, not an accidental timeout. For example, a 20 MB limit is reasonable for a lightweight public GIF workflow, but it must match the server's limit too.

const MAX_GIF_BYTES = 20 * 1024 * 1024;

function validateSize(file) {
  if (file.size > MAX_GIF_BYTES) {
    return "Choose a GIF smaller than 20 MB.";
  }
  return null;
}

Client-side validation improves feedback. Server-side validation is still mandatory: the browser is not a trust boundary.

3. Budget for decoded pixels, not just megabytes

The useful rough estimate is:

decoded pixel budget = width × height × frame count

A 1920 × 1080 GIF with 300 frames has more than 622 million frame-pixels to process. Even if compression keeps the file small, decoding it in a browser or a serverless function can be slow and memory-heavy.

After parsing the animation, set guardrails for frame count and total decoded pixels. In one browser-local utility workflow, I reject files with more than 1,000 frames and flag animations whose decoded pixel budget is too high for reliable processing. Your threshold will depend on the device and the operation, but the principle is stable: reject complexity early and explain why.

4. Check whether the file is actually animated

Some GIFs contain one static frame. If your feature promises animation, count frames after parsing and tell the user what happened:

if (metadata.frameCount < 2) {
  return "This file is a static GIF. Choose an animated GIF instead.";
}

This is much better than letting the user wait for a result that looks unchanged.

5. Keep the error message actionable

Avoid generic messages such as “Upload failed.” The user needs to know the next action:

“Choose a GIF or animated WebP.”
“Choose a GIF smaller than 20 MB.”
“This GIF has more than 1,000 frames. Trim it before processing.”
“This GIF is too large or complex for reliable browser processing.”

That wording turns a support ticket into a recoverable workflow.

6. Test with awkward real-world files

Build a small fixture set: a valid short GIF, a renamed non-GIF, a static one-frame GIF, a file with excessive frames, and a large-but-compressed GIF. The last case is especially useful because it reveals why file size alone is not enough.

If you are building a face-swap flow, input quality matters after validation too: a short clip with one visible face and a clear reference photo is substantially easier to process and review. I wrote a separate [step-by-step GIF face swap guide]for that workflow. Disclosure: I work on the product behind that guide.

The takeaway

The fastest GIF upload is the one you decline before it becomes expensive. Validate the signature, file size, frame count, and decoded pixel budget early; mirror the checks on the server; and give the user a clear next step when a file is unsuitable.