DEV Community: nareshipme

Fixing yt-dlp in Docker: n-challenge EJS scripts, Deno 2.x, and the player_client=ios cookie trap

nareshipme — Thu, 09 Apr 2026 19:08:29 +0000

If you run a video processing worker that downloads YouTube content with yt-dlp, you've probably hit the n-challenge wall: downloads stall or fail with a Sign in to confirm you're not a bot error, or the n-parameter isn't being decoded correctly, leaving you with throttled or broken streams. After a few rounds of debugging our Railway-hosted worker, here's everything we fixed and why.

Background: what is the n-challenge?

YouTube applies a per-request throttling parameter called n to video URLs. yt-dlp has to solve a JavaScript challenge (embedded in the YouTube player) to decode this parameter into a valid token. If the challenge isn't solved, requests are throttled to ~50 KB/s or rejected outright.

The solver is written in JavaScript, and yt-dlp ships with multiple backends for running it: a pure-Python fallback, and native JS runtimes (Node.js, Deno, PhantomJS). The JS path is dramatically faster and more reliable — but only if the runtime is actually available and the yt-dlp installation includes the EJS scripts that invoke it.

We had three separate bugs causing failures. Here's each one.

Bug 1: Installing yt-dlp as a curl binary skips the EJS scripts

The most common Docker pattern for yt-dlp is to grab the standalone binary from GitHub releases:

RUN curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp \
    -o /usr/local/bin/yt-dlp \
    && chmod a+rx /usr/local/bin/yt-dlp

This works for basic downloads, but the standalone binary bundles only a subset of yt-dlp's assets. The EJS (Embedded JavaScript) scripts that yt-dlp uses to run the n-challenge solver in an external JS runtime are not included in the single-file binary. They live in the yt_dlp/ package directory and are only present when you install via pip.

The fix is to install with pip using the [default] extra, which pulls in all optional dependencies including the JS solver scripts:

RUN pip3 install --break-system-packages "yt-dlp[default]"

The --break-system-packages flag is required on Debian/Ubuntu images that use externally-managed Python environments (PEP 668). Without it, pip refuses to install into the system Python on newer base images. This flag is safe here because we're in a container — there's no system package manager conflict to worry about.

Why [default] and not just yt-dlp? The [default] extra includes:

brotli — for brotli-compressed responses
certifi — updated CA bundle
mutagen — audio metadata writing
pycryptodomex — AES decryption for some streams
websockets — live stream support

None of these are strictly required for n-challenge solving, but they prevent silent fallbacks to slower code paths.

Bug 2: No JS runtime available for the n-challenge solver

Once the EJS scripts are present, yt-dlp needs a JS runtime to execute them. Our base image (node:20-slim) has Node.js, but we wanted a second option that's more isolated and doesn't require the full Node module resolution chain.

We added Deno 2.x as the JS runtime:

RUN curl -fsSL https://deno.land/install.sh \
    | DENO_INSTALL=/usr/local sh \
    && deno --version

Setting DENO_INSTALL=/usr/local puts the deno binary at /usr/local/bin/deno, which is already on PATH. No .deno/bin in PATH needed.

yt-dlp auto-detects available JS runtimes at runtime in this priority order: deno, node, phantomjs. With Deno present, it takes priority. Deno's V8 sandbox also means the n-challenge JS executes with no filesystem or network access by default — a minor but real security improvement over running arbitrary YouTube JS in Node.

The full updated system deps block:

RUN apt-get update && apt-get install -y \
    ffmpeg python3 python3-pip curl ca-certificates unzip \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/* \
    && pip3 install --break-system-packages "yt-dlp[default]" \
    && yt-dlp --version \
    && curl -fsSL https://deno.land/install.sh | DENO_INSTALL=/usr/local sh \
    && deno --version

Note unzip is required by the Deno installer.

Bug 3: player_client=ios silently drops cookies

This one was subtle. Our yt-dlp invocation was passing --extractor-args youtube:player_client=ios to use the iOS player client, which historically bypassed some bot detection. But it has a critical flaw: the iOS client ignores cookies.

YouTube's iOS API endpoint doesn't use browser cookie authentication — it uses OAuth tokens. When you pass --cookies with a Netscape-format cookies file (the kind you export from a browser), the iOS client simply ignores it. For age-restricted videos, private videos, or accounts that have verified status, this means your cookies are silently dropped and you get a public-access response (or a rejection).

The fix is to switch to clients that actually honor cookies:

// Before
"--extractor-args",
"youtube:player_client=ios",

// After
"--extractor-args",
"youtube:player_client=web,mweb,android",

The web client is the standard browser client — fully compatible with cookie authentication. mweb is the mobile web client, useful as a fallback. android is the Android app client, which is good for bypassing some rate limits while still respecting cookies.

yt-dlp tries them in order and uses the first one that succeeds. In practice, web handles the vast majority of cases, and mweb/android serve as automatic fallbacks without any extra code.

Keeping yt-dlp current without rebuilding

YouTube frequently updates the player JS, which changes the n-challenge algorithm. A yt-dlp binary that was current two weeks ago may fail today. We handle this by self-updating on every container start:

CMD ["sh", "-c", "yt-dlp -U && node --max-old-space-size=200 dist/server.js"]

yt-dlp -U checks for a newer pip release and upgrades in place if one exists. This adds ~2-3 seconds to cold start but means you never need to rebuild the image just to fix a YouTube extractor bug.

Summary of changes

What	Before	After
yt-dlp install	`curl` binary from GitHub	`pip install yt-dlp[default]`
JS runtime	None (Python fallback)	Deno 2.x + Node.js
player_client	`ios`	`web,mweb,android`
Cookie support	Silently broken	Working
EJS scripts	Missing	Included via pip package

If you're running yt-dlp in Docker and seeing mysterious throttling, bot-detection failures, or cookies that seem to be ignored, this combination of fixes is likely what you need. The pip install + Deno runtime is especially easy to overlook when the standalone binary appears to work fine for public videos.

Debugging a Silent Failure: Presigned R2 Uploads and the Inngest Job That Never Ran

nareshipme — Thu, 09 Apr 2026 18:34:45 +0000

We shipped a file upload feature for ClipCrafter — paste a video URL or upload a file — and it looked like everything was working. The S3-compatible PUT request to Cloudflare R2 returned a 200. No errors in the console. No red Vercel logs.

Yet every uploaded video sat in limbo, never processed. Here's the bug, the fix, and what we learned.

The Architecture in 30 Seconds

ClipCrafter processes videos using Inngest background functions. The flow looks like this:

User uploads a file → we generate a presigned R2 URL via a /api/upload route
Client does a direct PUT to that presigned URL (R2 / Cloudflare)
Client calls /api/projects/[id] to update the project with metadata
A separate action triggers inngest.send({ name: "video/process", data: { projectId } })
Inngest picks up the event and runs the process-video function

Simple enough. So what broke?

The Bug: A Missing `PATCH`

After a successful PUT to R2, our frontend was calling the project PATCH route — but only to save the video title. We never sent the r2_key back.

// ❌ BEFORE — only patching the title
await fetch(`/api/projects/${projectId}`, {
  method: "PATCH",
  body: JSON.stringify({ title: fileName }),
});

Meanwhile, in our Inngest process-video function:

const project = await supabase
  .from("projects")
  .select("r2_key, source_url")
  .eq("id", event.data.projectId)
  .single();

if (!project.data?.r2_key && !project.data?.source_url) {
  throw new Error("No video source found"); // 💥 always hit for uploads
}

The job failed on the very first step, every single time. And because Inngest retries silently in the background, nothing surfaced as an obvious user-facing error — we just never saw the video get processed.

The Fix: Extend the PATCH Route and Send the Key

Two small changes:

1. Extend /api/projects/[id]/route.ts to accept r2_key:

// ✅ AFTER
const { title, r2_key } = await req.json();
const updatePayload: Record<string, string> = {};
if (title) updatePayload.title = title;
if (r2_key) updatePayload.r2_key = r2_key;

await supabase.from("projects").update(updatePayload).eq("id", projectId);

2. Send r2_key from the client after the PUT succeeds:

// ✅ AFTER — send both title and r2_key
const r2Key = `uploads/${projectId}/${fileName}`;

// Direct PUT to presigned URL
await fetch(presignedUrl, {
  method: "PUT",
  body: file,
  headers: { "Content-Type": file.type },
});

// Save the key back to the project row
await fetch(`/api/projects/${projectId}`, {
  method: "PATCH",
  body: JSON.stringify({ title: fileName, r2_key: r2Key }),
});

That's it. One missing field. One extra line in the payload. Everything downstream just works.

The Lesson: Presigned URLs Create Invisible Gaps

With direct-upload patterns (presigned S3/R2 URLs), your backend is deliberately out of the loop during the actual transfer. That's the point — it offloads bandwidth from your API server. But it also means:

Your API never sees the bytes
Your API never confirms the upload succeeded
Your API's database row stays stale until you explicitly update it

If any step between "PUT succeeds" and "database updated" fails silently, you end up with orphaned uploads. The file is in R2. The DB says it isn't. Downstream jobs trust the DB.

A defensive pattern we're now adopting: after the presigned PUT, always PATCH back a upload_completed_at timestamp alongside the key. If that timestamp is null when the Inngest job runs, skip or surface an error with a meaningful message instead of throwing cryptically.

What Else Landed: Billing Scaffolding (Not Live Yet)

Alongside this fix, we scaffolded the billing layer for ClipCrafter — Stripe + Razorpay support, Supabase subscriptions and usage tables, plan limits enforced inside the Inngest pipeline itself:

// Inside process-video Inngest function
await step.run("check-usage", async () => {
  const allowed = await isUsageAllowed(projectOwnerId);
  if (!allowed) throw new NonRetriableError("Usage limit reached");
});

// ... process video ...

await step.run("increment-usage", async () => {
  await incrementUsage(projectOwnerId);
});

Putting the usage gate inside Inngest rather than at the API layer means even background retries respect plan limits. More on the full billing design in a future post.

If you're building a video tool and want to see this pipeline in action, give ClipCrafter a try — paste a YouTube link or upload a file and get shareable clips in minutes.

Have you been burned by a presigned URL silent-failure bug? Drop a comment — I'd love to compare notes.

How We Made Waiting Fun: Whimsical Loading States and Stepped Progress in Next.js

nareshipme — Wed, 08 Apr 2026 15:43:20 +0000

Long-running background jobs are a fact of life in video processing. When a user uploads a 30-minute video, your AI pipeline might need two or three minutes to download, transcribe, and clip it. The worst thing you can do is show a spinner and leave people wondering if something broke.

In ClipCrafter — an AI-powered tool that turns long videos into short, shareable clips — we recently overhauled our processing UX. Here's how we did it with React, TypeScript, and a little personality.

The problem

Our original processing screen was a single progress bar with a generic "Processing…" label. Users had no idea which stage the pipeline was in, how long it would take, or whether the page was even still working. Support messages spiked every time processing took longer than 90 seconds.

Solution 1 — Rotating whimsical messages

We created a dedicated module — loadingMessages.ts — that maps each pipeline stage to an array of light-hearted messages:

// src/lib/loadingMessages.ts
const stageMessages: Record<ProcessingStage, string[]> = {
  downloading: [
    "Summoning your video from the internet…",
    "Convincing the server to share…",
    "Downloading at the speed of vibes…",
  ],
  transcribing: [
    "Eavesdropping scientifically…",
    "Teaching the AI to listen…",
    "Turning sound waves into words…",
  ],
  analyzing: [
    "Asking the AI what slaps…",
    "Finding the best moments…",
    "Separating signal from filler…",
  ],
  // ... more stages
};

A useEffect hook cycles through the array for the current stage every three seconds, giving the interface a living, breathing feel:

useEffect(() => {
  const messages = stageMessages[currentStage];
  const interval = setInterval(() => {
    setMessageIndex((i) => (i + 1) % messages.length);
  }, 3000);
  return () => clearInterval(interval);
}, [currentStage]);

The psychological impact is real — users see movement and humour, which makes the wait feel shorter.

Solution 2 — A stepped progress indicator

Instead of one bar, we render five dots connected by lines — one per pipeline stage. The active dot pulses; completed dots turn green. The component is pure CSS and state:

const stages = ["download", "transcribe", "analyze", "clip", "export"];

{stages.map((stage, i) => (
  <div key={stage} className="flex items-center">
    <div className={cn(
      "h-3 w-3 rounded-full",
      i < currentIndex ? "bg-green-500" :
      i === currentIndex ? "bg-blue-500 animate-pulse" :
      "bg-zinc-700"
    )} />
    {i < stages.length - 1 && (
      <div className={cn(
        "h-0.5 w-8",
        i < currentIndex ? "bg-green-500" : "bg-zinc-700"
      )} />
    )}
  </div>
))}

Paired with a time estimate — "Usually 2–3 min for a 30 min video" — users know exactly where they are and roughly when to expect results.

Bonus — Fixing the clip drag glitch

While we were in the code, we fixed a nasty drag interaction bug. Our clip timeline let users drag handles to adjust start and end times, but every pixel of movement triggered a React state update and a database PATCH. The video player jumped erratically and the UI felt laggy.

The fix was ref-based tracking:

const dragValueRef = useRef(currentTime);

const onMouseMove = (e: MouseEvent) => {
  dragValueRef.current = pixelToTime(e.clientX);
  debouncedSeek(dragValueRef.current);
};

const onMouseUp = () => {
  setClipTime(dragValueRef.current);
  updateClipOnServer(dragValueRef.current);
};

By keeping the drag value in a ref and only committing on mouseup, we eliminated re-renders during the drag and reduced API calls from dozens to exactly one.

Takeaways

Loading copy matters. Whimsical, rotating messages humanize the wait and reduce perceived latency.
Show progress structure, not just a bar. Stepped indicators give users a mental model of where they are in the pipeline.
Use refs for drag interactions. React state during mousemove is a performance trap — keep the hot loop in a ref and sync state on commit.

If you're building a video or media processing tool and want to skip straight to the fun part, give ClipCrafter a try — drop in a YouTube link and get clips in minutes.

Built with Next.js, TypeScript, Inngest, and Tailwind CSS.

Teaching an AI Agent to Do TDD (And Actually Mean It)

nareshipme — Tue, 07 Apr 2026 16:32:50 +0000

One of the more interesting problems I've been sitting with lately is this: how do you make an AI coding agent disciplined?

Not capable — that part is mostly solved. But disciplined. The kind of discipline that stops a developer from writing five tests at once before any of them are green. The kind that insists every acceptance criterion has a named test before you call the story done. That's the hard part.

The Problem With "Just Tell It"

My first instinct was to write a rule: "follow TDD." Simple enough. But vague instructions produce vague compliance. The agent would write a test, write all the implementation, then nod along when you asked if it did TDD. Technically yes. Practically no.

The fix was to get specific about the atomic unit. Not "write tests first" but "write exactly one failing test, make it pass, commit — then and only then write the next test." That single constraint changes the whole rhythm. It forces small commits, it surfaces design issues early, and crucially, it's checkable. Either the commit history shows alternating test/impl commits or it doesn't.

Vertical Slices as Test Scenarios

The other shift was in how stories are broken down into tasks. Instead of horizontal layers — "write the DB migration, then the service layer, then the controller, then the UI" — I moved to vertical slices expressed as BDD scenarios. Each task looks like:

Given [starting state]
When [user or system action]
Then [observable outcome]
Hint: [which layer to touch and roughly how]

This matters because it keeps the agent (or any developer, really) anchored to user-observable behavior rather than implementation shape. The hint gives just enough technical direction without over-constraining the solution. And because the scenario doubles as a test case, there's no gap between "task complete" and "test written."

Traceability Before You Merge

The last piece was AC traceability. Before a PR gets created, the agent now has to produce an explicit mapping: Acceptance Criterion → test(s) that cover it. If a criterion has no test, the story isn't done. Full stop.

This sounds obvious but it's surprisingly easy to skip when you're moving fast. Making it a gate — not a suggestion — changes the default. The PR description ends up with a little table that reviewers can actually use.

Takeaway

The pattern here applies beyond AI agents. Codifying your team's development discipline as explicit, checkable constraints — rather than cultural norms — makes it stick. Norms drift. Checklists don't.

If you're working with AI coding assistants, the investment in tight agent configuration pays back fast. The more precise the rules, the less you spend reviewing slop.

How We Replaced Polling With Server-Sent Events for Real-Time Video Processing Updates

nareshipme — Mon, 06 Apr 2026 15:42:22 +0000

When you are building a video editing SaaS, one of the trickiest UX problems is keeping users informed about long-running server-side tasks. Transcoding a clip, generating thumbnails, running AI-based scene detection — these jobs can take anywhere from a few seconds to several minutes. Early on at ClipCrafter, we leaned on the simplest approach: polling.

The Polling Problem

Our first implementation looked something like this:

// hooks/useJobStatus.ts — the naive version
export function useJobStatus(jobId: string) {
  const [status, setStatus] = useState<JobStatus>("pending");

  useEffect(() => {
    const interval = setInterval(async () => {
      const res = await fetch(`/api/jobs/${jobId}`);
      const data = await res.json();
      setStatus(data.status);
      if (data.status === "complete" || data.status === "failed") {
        clearInterval(interval);
      }
    }, 2000);
    return () => clearInterval(interval);
  }, [jobId]);

  return status;
}

This worked, but it came with real costs. Every two seconds, every user with an active job was hammering our API. During peak hours we were seeing thousands of unnecessary requests per minute. Our database was fielding repetitive SELECT queries for jobs that had not changed since the last poll. Latency was also mediocre — users could wait up to two seconds after a job finished before the UI updated.

Why We Chose Server-Sent Events Over WebSockets

We evaluated two alternatives: WebSockets and Server-Sent Events (SSE). WebSockets are powerful, but they introduce bidirectional complexity we did not need. Our updates flow in one direction: server to client. SSE gave us exactly that with a simpler protocol, automatic reconnection built into the browser EventSource API, and straightforward compatibility with our Next.js API routes.

The SSE Implementation

On the server side, we created a Next.js Route Handler that streams job updates:

// app/api/jobs/[jobId]/stream/route.ts
import { NextRequest } from "next/server";
import { getJobUpdates } from "@/lib/job-events";

export async function GET(
  req: NextRequest,
  { params }: { params: { jobId: string } }
) {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      const send = (data: Record<string, unknown>) => {
        controller.enqueue(
          encoder.encode(`data: ${JSON.stringify(data)}\n\n`)
        );
      };

      // Send current state immediately
      const current = await getJobUpdates(params.jobId);
      send(current);

      // Subscribe to future updates
      const unsubscribe = onJobUpdate(params.jobId, (update) => {
        send(update);
        if (update.status === "complete" || update.status === "failed") {
          controller.close();
        }
      });

      req.signal.addEventListener("abort", () => {
        unsubscribe();
        controller.close();
      });
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

The onJobUpdate function subscribes to a lightweight Redis Pub/Sub channel. When our background worker finishes a processing step, it publishes an event and every connected client receives the update within milliseconds.

On the client side, the hook became cleaner and more responsive:

// hooks/useJobStatus.ts — SSE version
export function useJobStatus(jobId: string) {
  const [status, setStatus] = useState<JobStatus>("pending");
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const source = new EventSource(`/api/jobs/${jobId}/stream`);

    source.onmessage = (event) => {
      const data = JSON.parse(event.data);
      setStatus(data.status);
      setProgress(data.progress ?? 0);
      if (data.status === "complete" || data.status === "failed") {
        source.close();
      }
    };

    source.onerror = () => {
      // EventSource reconnects automatically on transient errors.
      // We only close on terminal failures.
      console.warn("SSE connection interrupted — retrying");
    };

    return () => source.close();
  }, [jobId]);

  return { status, progress };
}

Results After the Switch

The numbers spoke for themselves. API requests related to job status dropped by over 90 percent. Average time-to-UI-update went from around one second down to under 100 milliseconds. Server CPU utilization on our API tier dropped noticeably during peak processing windows, and users started commenting that processing felt faster even though the actual transcoding time had not changed.

Lessons Learned

A few things we picked up along the way. First, always send the current state as the first event in the stream. If a client connects after a job has already progressed, they should not have to wait for the next update to see where things stand. Second, set a reasonable server-side timeout so you do not hold connections open indefinitely for abandoned tabs. We close idle streams after five minutes. Third, use Redis Pub/Sub or a similar lightweight broker rather than polling the database from inside your SSE handler — otherwise you have just moved the polling problem from client to server.

Try It Yourself

If you are building any kind of async processing pipeline in a Next.js app, SSE is a pragmatic middle ground between polling and full WebSocket infrastructure. It took us about a day to migrate and the payoff was immediate.

Want to see this in action? ClipCrafter uses this pattern across all of our video processing workflows. Give it a spin and watch your progress bars update in real time.

Have questions about SSE patterns in Next.js? Drop a comment — happy to dig into edge cases.

framewebworker: Browser-Native Video Rendering with OffscreenCanvas, Web Workers, and ffmpeg.wasm

nareshipme — Mon, 06 Apr 2026 14:57:28 +0000

Server-side video rendering is expensive, operationally painful, and doesn't scale well. You need GPU instances, media processing queues, temp storage, CDN delivery pipelines — a whole infrastructure just to clip a video. We hit every one of those walls building ClipCrafter, and eventually asked: what if the browser just did it?

The result is framewebworker — an open-source library that runs video export entirely in the browser using OffscreenCanvas, Web Workers, and ffmpeg.wasm. No server. No queue. No infra.

The Problem with Server-Side Video Rendering

Traditional video rendering pipelines: user selects clips → API queues job → worker spins up ffmpeg → uploads to S3 → returns signed URL. This works, but every concurrent render ties up server resources. Peak usage means queuing delays. Cold starts on serverless are brutal for long-running ffmpeg processes.

The browser is now powerful enough to do this locally. For most use cases — trimming, merging, exporting clips — it's a better fit.

Introducing framewebworker

npm install framewebworker

GitHub: https://github.com/nareshipme/framewebworker | npm: https://www.npmjs.com/package/framewebworker

Core API

exportClips(videoUrl, segments[])

import { exportClips } from 'framewebworker';

const results = await exportClips('https://example.com/video.mp4', [
  { start: 0,  end: 10, label: 'intro' },
  { start: 45, end: 60, label: 'highlight' },
]);

results.forEach(({ blob, label, metrics }) => {
  console.log(label + ': ' + metrics.totalMs + 'ms @ ' + metrics.framesPerSecond + 'fps');
});

mergeClips(clips[])

import { mergeClips } from 'framewebworker';

const merged = await mergeClips([
  'https://example.com/clip-a.mp4',
  'https://example.com/clip-b.mp4',
]);
console.log('Merged in', merged.metrics.totalMs, 'ms');

useExportClips() — React hook

import { useExportClips } from 'framewebworker';

function ExportButton({ videoUrl, segments }) {
  const { exportClips, progress, results, isExporting } = useExportClips();
  return (
    <button onClick={() => exportClips(videoUrl, segments)} disabled={isExporting}>
      {isExporting ? 'Exporting... ' + progress + '%' : 'Export Clips'}
    </button>
  );
}

Architecture

Workers are spawned based on navigator.hardwareConcurrency (capped at 4). Each segment dispatches to the next available worker — multi-clip exports run in parallel. Each worker uses OffscreenCanvas for frame extraction and ffmpeg.wasm for encoding.

RenderMetrics

interface RenderMetrics {
  extractionMs: number;    // Frame extraction time
  encodingMs: number;      // ffmpeg encoding time  
  totalMs: number;         // End-to-end wall clock
  framesPerSecond: number; // Effective fps
}

COOP/COEP Headers Required

ffmpeg.wasm needs SharedArrayBuffer, which requires cross-origin isolation:

// next.config.js
module.exports = {
  async headers() {
    return [{
      source: '/(.*)',
      headers: [
        { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
        { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
      ],
    }];
  },
};

Note: these headers can break cross-origin iframes and some OAuth popups. Audit your third-party dependencies before shipping.

Bundle Size

ffmpeg.wasm is ~30MB but loaded lazily — only triggered when the user initiates their first export. Initial page load is completely unaffected. First-export cold start is ~2-3s. After that, rendering is fast and stays in memory for the session.

When to Use framewebworker

Good fit: Web apps where users clip/trim/merge short videos, products eliminating backend rendering infra, controlled deployments where you can set COOP/COEP headers.

Not ideal: Very long videos (>30min), environments where you can't control response headers, apps with heavy third-party embeds that break under cross-origin isolation.

Get Started

npm install framewebworker

GitHub: https://github.com/nareshipme/framewebworker
npm: https://www.npmjs.com/package/framewebworker
Production deep-dive: How We Ditched Backend Rendering and Went Full Client-Side with framewebworker

PRs, issues, and stars welcome. Multi-track audio mixing and subtitle burn-in are next on the roadmap.

How We Ditched Backend Rendering and Went Full Client-Side with framewebworker

nareshipme — Sun, 05 Apr 2026 19:20:28 +0000

The Problem with Server-Side Video Rendering

If you've ever built a video editing app, you know the pain: users create clips, hit "render," and then... wait. The video gets shipped to a server, processed with ffmpeg or Remotion, and eventually comes back. It's slow, expensive, and creates a terrible user experience.

At ClipCrafter, we lived with this architecture for months. Our rendering pipeline involved Inngest background functions, six dedicated API routes, a beefy Docker image with Chromium and Remotion dependencies, and a Deno runtime layer. Every render meant a round-trip to the server, and our infrastructure costs were climbing.

Last week, we ripped it all out.

Enter framewebworker

The key insight was simple: modern browsers are powerful enough to handle video rendering directly. We replaced our entire backend rendering stack with framewebworker, a lightweight library that processes video frames in a Web Worker.

The migration touched almost every layer of the app. Here's what changed in our biggest PR of the quarter (#214):

What We Deleted

All Inngest background render functions
Six API routes dedicated to render orchestration
Remotion bundler and renderer packages
Chromium and system-level dependencies from our Docker image
Deno runtime from the worker container
Render-related database columns via a new migration

That last point is worth emphasizing. We didn't just swap libraries — we removed an entire category of server state. No more tracking render jobs, polling for completion, or handling failed renders on the backend.

What We Added

The replacement is a single React hook: useClientStitch. It calls framewebworker's API directly in the browser, passing video segments with caption overlays and timing data. The rendering happens in a Web Worker, so the main thread stays responsive.

// Before: complex server orchestration
const response = await fetch('/api/render', {
  method: 'POST',
  body: JSON.stringify({ clipIds, options })
});
// Then poll for completion...

// After: direct client-side rendering
const { render } = useClipRender();
await render(segments, {
  onProgress: (progress) => updateUI(progress)
});

The difference in developer experience is night and day.

The Follow-Up: Rich Progress UI

Once rendering moved client-side, we could do something that was nearly impossible before: show real, granular progress. In the server model, the best we could offer was "processing..." with maybe a percentage that updated every few seconds.

With framewebworker running locally, we built a RenderStatusPanel (PR #216) that shows per-clip progress with spinner and check icons, an overall progress bar with calculated ETA based on elapsed time, and real RichProgress data with per-clip metrics.

We went from a vague loading spinner to a detailed breakdown of exactly what's happening and when it will finish.

Iterating on the API

The migration wasn't a single PR. After the initial swap, we refined the integration across several follow-up changes.

PR #217 bumped framewebworker to v0.1.1 and wired up the real RichProgress types, removing our local progress simulation. Then PR #218 migrated from the stitch() API to a new render() function that loads a single video once instead of re-loading per segment. This introduced buildVideoSegments() to map clips to framewebworker segments with captions and timing.

Results

Docker Image Size

Removing Chromium, Remotion, and Deno shaved roughly 200 MB off our worker Docker image (PR #215). Faster deploys, lower storage costs.

Infrastructure

Six API routes and all background job infrastructure: gone. Our server is simpler, cheaper to run, and has fewer failure modes.

User Experience

Renders start instantly — no upload, no queue, no polling. Users see exactly what's happening with per-clip status and a real ETA.

Takeaways for Your Projects

If you're building a media processing app, consider whether the browser can handle more than you think. Web Workers and modern APIs like OffscreenCanvas and WebCodecs are closing the gap with server-side processing for many use cases.

The key questions to ask: Does every user need to render, or just a few? (If most users render, client-side saves massive server costs.) Are your renders CPU-bound or GPU-bound? (Browsers have GPU access.) Can you tolerate slightly longer render times in exchange for zero infrastructure?

For ClipCrafter, the answer to all three made client-side rendering a clear win.

ClipCrafter is an open-source video clipping tool. Check out the repo at github.com/clipcrafterapp/clipcrafter-app and give it a star if this kind of engineering interests you.

How We Moved Video Rendering From the Server to the Browser

nareshipme — Sun, 05 Apr 2026 19:17:22 +0000

The Problem With Server-Side Video Rendering

If you have ever built a video editing tool, you know the pain of server-side rendering. Heavy FFmpeg processes, GPU provisioning, cold starts, job queues, and infrastructure costs that scale linearly with every export. For ClipCrafter -- an open-source app that turns long videos into short, captioned clips -- this was becoming unsustainable.

Our previous architecture relied on Remotion running inside a Docker container on Railway. Every time a user exported a clip, a serverless function would spin up, pull in Chromium, render frames, and stitch them with FFmpeg. It worked, but it was slow, expensive, and fragile.

So we ripped it all out.

Enter framewebworker

In PR #214, we replaced the entire backend rendering pipeline with framewebworker -- a library that renders video frames directly in the browser using Web Workers and the WebCodecs API.

The idea is simple: instead of shipping video data to a server, encode it right where the user already has the video loaded. Modern browsers have surprisingly capable media encoding APIs, and framewebworker wraps them into a clean, composable interface.

What We Removed

The migration was as much about deleting code as writing it. Here is what got removed:

6 API routes related to render jobs, status polling, and artifact downloads
Inngest render functions that orchestrated async server-side renders
Remotion configuration including the composition, bundle, and all server rendering utilities
Chromium and FFmpeg from the Docker image, cutting roughly 200 MB from the container
Database columns tracking server-side export state via a new migration

The Dockerfile went on a diet too -- no more chromium, libgbm, or Remotion-specific system packages.

What We Added

The new rendering flow lives entirely in a React hook called useClipRender. Under the hood, it calls framewebworker's render function with a set of video segments built by a new buildVideoSegments helper.

Each segment maps a clip's time range to the source video and overlays caption data with precise timing. The render function handles frame extraction, caption compositing, encoding, and muxing -- all in a Web Worker so the main thread stays responsive.

// Simplified example of the new render flow
const segments = buildVideoSegments(clips, transcript);
const blob = await render({
  source: videoUrl,
  segments,
  format: 'mp4',
  onProgress: (p) => setProgress(p),
});

The result is an MP4 blob that we hand directly to the browser's download API. No round-trips, no polling, no artifact storage.

Real Progress Reporting

One immediate benefit was progress tracking. Server-side renders gave us almost no useful progress data -- we were literally faking it with a simulated progress bar.

With framewebworker, we get genuine RichProgress events that include overall percentage, per-clip status, and phase information. We built a new RenderStatusPanel component that shows each clip's progress with spinner icons and a dynamic ETA that activates once rendering passes 2 percent.

Performance and Cost Impact

Early benchmarks are promising. For a typical 60-second clip with captions:

Server render: 45-90 seconds depending on cold start and queue depth
Browser render: 15-30 seconds on a mid-range laptop

The cost difference is even more dramatic. Server rendering required a persistent or on-demand container with enough CPU and memory to run Chromium. Browser rendering requires the user's existing browser tab. Our infrastructure bill for rendering dropped to zero.

Trade-offs

This approach is not without downsides. Browser rendering depends on the user's hardware -- a low-end Chromebook will be slower than our server was. The WebCodecs API is not available in all browsers yet, and Safari support is still catching up. Very long videos can hit memory limits.

For our use case -- short clips typically under 3 minutes -- the trade-offs are well worth it. We added a browser compatibility check that warns users if their browser does not support WebCodecs and falls back gracefully.

What This Means for Open Source Video Tools

This migration shows that browser-based video rendering is production-ready for many use cases. If you are building a video tool and dreading the infrastructure complexity of server-side rendering, consider whether your encoding work can happen client-side.

The key enablers are Web Workers for off-main-thread processing, WebCodecs for hardware-accelerated encoding, and libraries like framewebworker that abstract the complexity.

ClipCrafter is fully open source at github.com/clipcrafterapp/clipcrafter-app. Check out the PR and let us know what you think.

This post is part of our series on building ClipCrafter in the open. Follow along for more deep dives into real-world Next.js, video processing, and open-source development.

Why Your Browser Video Export Has No Audio (And the Fix Using AudioContext + Gain Node)

nareshipme — Sat, 04 Apr 2026 15:41:09 +0000

When we built client-side video clip export using Canvas + MediaRecorder, everything looked great — the video rendered correctly with captions, progress worked, files downloaded. But every exported clip was completely silent.

Here's the bug and how we fixed it.

The Setup

The pipeline works like this:

Create a hidden <video> element and seek to the clip start
Draw each frame onto an <canvas> via requestAnimationFrame
Capture the canvas as a MediaStream via canvas.captureStream(30)
Tap audio from the video element via AudioContext.createMediaElementSource()
Merge video + audio tracks into MediaRecorder
On stop, combine chunks into a Blob and trigger download

Step 4 is where things went wrong.

The Bug: Capturing from a Muted Element

We started the video element as muted (correct — we don't want the user to hear the export render playing back):

const video = document.createElement('video');
video.src = videoUrl;
video.muted = true; // so the user doesn't hear it

Then later, we wired up the AudioContext:

// ❌ Bug: video is still muted — this source captures silence
const audioCtx = new AudioContext();
const source = audioCtx.createMediaElementSource(video);
const dest = audioCtx.createMediaStreamDestination();
source.connect(dest);

The problem: createMediaElementSource captures the decoded PCM audio from the element, but video.muted = true zeros out the audio before it reaches the Web Audio graph. So you get a valid-looking MediaStream with an audio track that is entirely silent.

This is a surprisingly subtle footgun — the MediaStreamDestination node reports it has an audio track, MediaRecorder picks it up, and the resulting file has an audio stream with no content.

The Fix: Unmute, Then Silence the Output Yourself

The correct approach is to unmute the video element so AudioContext gets real PCM data, but silence the output through a GainNode so the user's speakers stay quiet:

function setupAudio(video: HTMLVideoElement): { audioCtx: AudioContext; stream: MediaStream } {
  // Unmute so AudioContext can tap PCM data;
  // route output through gain=0 so speakers stay silent.
  video.muted = false;
  const audioCtx = new AudioContext();
  const source = audioCtx.createMediaElementSource(video);

  // Silent path to speakers (gain=0 keeps speakers muted)
  const silencer = audioCtx.createGain();
  silencer.gain.value = 0;
  source.connect(silencer);
  silencer.connect(audioCtx.destination);

  // Live path to recorder (full volume)
  const dest = audioCtx.createMediaStreamDestination();
  source.connect(dest);

  return { audioCtx, stream: dest.stream };
}

Key insight: the source node can have multiple connections. We connect it to both:

A GainNode with gain.value = 0 → audioCtx.destination (speakers hear silence)
A MediaStreamDestination → recorder (recorder gets full-volume audio)

This is the Web Audio graph equivalent of tee-ing a stream.

Why Not Just Use `createMediaStreamSource`?

You might think: "can't I just grab the stream from the video and pipe it to the recorder?"

// ⚠️ Doesn't work reliably
const stream = video.captureStream();
const audioTrack = stream.getAudioTracks()[0];

HTMLVideoElement.captureStream() is non-standard and inconsistently implemented. In our testing it worked on Chrome but not in all contexts. createMediaElementSource via Web Audio is the standard path.

Bonus: The Hidden Timing Issue

We also discovered that the video element should start muted, and only be unmuted right before createMediaElementSource is called — not before. If you unmute it too early (e.g., in the constructor), some browsers may flag it as an autoplay policy violation before the AudioContext is created by user gesture.

So the initialization order matters:

// 1. Create video element muted (autoplay-policy safe)
const video = document.createElement('video');
video.muted = true;
video.src = url;

// 2. Wait for user interaction or button click to trigger export...

// 3. Then, right before setting up AudioContext:
video.muted = false; // ← unmute just in time
const audioCtx = new AudioContext(); // ← must be created in user gesture context
const source = audioCtx.createMediaElementSource(video);

The Takeaway

If you're building browser-side video export with Canvas + MediaRecorder + AudioContext:

Start the video element muted to comply with autoplay policy
Unmute before calling createMediaElementSource — otherwise you capture silence
Use a gain=0 node to silence speakers without muting the audio source
Connect one source to multiple destinations to split recording vs playback paths

The Web Audio graph model is powerful once you understand that nodes can fan out — same source, multiple outputs, each with independent gain.

Full pipeline code available in ClipCrafter.

How to Reuse Your Canvas 2D Rendering Pipeline for Live Video Preview (No Duplicate Code)

nareshipme — Sat, 04 Apr 2026 15:37:53 +0000

When you build a browser-based video export pipeline with Canvas 2D + MediaRecorder, you'll quickly hit a problem: you also need a live preview — playing the video with captions overlaid in real time, so users can verify what the export will look like before it starts.

The naive solution is to write the caption-drawing code twice: once for the export loop and once for the preview loop. But there's a much better way — expose your draw functions and share them.

The Setup: Shared Draw Functions

The key is to export your rendering primitives from a single module that both the export pipeline and the preview component can import:

// useClientExport.ts — your export hook

export function drawVideoFrame(
  ctx: CanvasRenderingContext2D,
  video: HTMLVideoElement,
  cw: number,
  ch: number
): void {
  // cover-fit the video frame to the canvas
  const vAspect = video.videoWidth / video.videoHeight;
  const cAspect = cw / ch;
  let sx = 0, sy = 0, sw = video.videoWidth, sh = video.videoHeight;
  if (vAspect > cAspect) {
    sw = video.videoHeight * cAspect;
    sx = (video.videoWidth - sw) / 2;
  } else {
    sh = video.videoWidth / cAspect;
    sy = (video.videoHeight - sh) / 2;
  }
  ctx.drawImage(video, sx, sy, sw, sh, 0, 0, cw, ch);
}

export function drawCaptions({
  ctx, captions, currentTime, captionStyle, cw, ch,
}: DrawCaptionsOptions): void {
  const active = captions.find(
    (c) => currentTime >= c.startInSeconds && currentTime < c.endInSeconds
  );
  if (!active) return;
  // ... measure, wrap, draw background box, draw text
}

export function getDimensions(aspectRatio: string): { w: number; h: number } {
  // ...
}

These three functions are pure — they take a canvas context and data, and they draw. No component state, no hooks. That's the secret to sharing them.

The Export Loop (MediaRecorder)

Your actual export captures canvas frames using captureStream() and MediaRecorder:

const stream = canvas.captureStream(30);
const recorder = new MediaRecorder(stream, { mimeType: "video/webm;codecs=vp9" });

let rafId: number;
function frame() {
  if (video.currentTime >= endSec) {
    recorder.stop();
    return;
  }
  drawVideoFrame(ctx, video, cw, ch);
  drawCaptions({ ctx, captions, currentTime: video.currentTime - startSec, ... });
  rafId = requestAnimationFrame(frame);
}
recorder.start();
video.play();
rafId = requestAnimationFrame(frame);

The Preview Loop (No Recording)

The preview modal is structurally identical — same canvas, same draw calls — minus the MediaRecorder:

// ClipPreviewModal.tsx

import { drawVideoFrame, drawCaptions, getDimensions } from "@/hooks/useClientExport";

function usePreviewCanvas(vRef, cRef, clip, captions) {
  const rafRef = useRef<number>(0);

  const startLoop = useCallback(() => {
    const v = vRef.current;
    const c = cRef.current;
    if (!v || !c) return;
    const ctx = c.getContext("2d")!;
    const { w: cw, h: ch } = getDimensions(clip.aspect_ratio);

    function frame() {
      if (!v || v.paused || v.ended) return;
      drawVideoFrame(ctx, v, cw, ch);
      drawCaptions({
        ctx,
        captions,
        currentTime: v.currentTime - clip.start_sec,
        captionStyle: clip.caption_style,
        cw,
        ch,
      });
      if (v.currentTime >= clip.end_sec) {
        v.pause();
        return;
      }
      rafRef.current = requestAnimationFrame(frame);
    }
    rafRef.current = requestAnimationFrame(frame);
  }, [vRef, cRef, clip, captions]);

  const stopLoop = useCallback(
    () => cancelAnimationFrame(rafRef.current),
    []
  );

  return { startLoop, stopLoop };
}

The preview loop drives off requestAnimationFrame — just like the export — but it never calls recorder.start(). The canvas renders at 60fps while the video plays, and users see captions exactly as the exporter would apply them.

The `textBaseline = "top"` Detail

One subtle thing: when you're drawing a background box behind text, set ctx.textBaseline = "top" before measuring and before drawing the fill rect. It makes box sizing consistent across fonts:

ctx.textBaseline = "top";
const lines = wrapText(ctx, text, maxTextWidth);
const totalH = lines.length * lineHeight - (lineHeight - fontSize);
const boxH = totalH + padV * 2;
// Now fill and draw text — the box will fit exactly

With alphabetic (the default), the y-coordinate is the baseline, so the box extends above where you think it starts. top anchors to the top of the em square, which is what you want when computing bounding boxes.

Cross-Browser `roundRect`

ctx.roundRect() isn't available in all browsers yet. Roll your own using quadraticCurveTo:

function roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, r: number) {
  ctx.beginPath();
  ctx.moveTo(x + r, y);
  ctx.lineTo(x + w - r, y);
  ctx.quadraticCurveTo(x + w, y, x + w, y + r);
  ctx.lineTo(x + w, y + h - r);
  ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
  ctx.lineTo(x + r, y + h);
  ctx.quadraticCurveTo(x, y + h, x, y + h - r);
  ctx.lineTo(x, y + r);
  ctx.quadraticCurveTo(x, y, x + r, y);
  ctx.closePath();
}

Scaling Font Sizes from a Reference Resolution

Don't hardcode pixel values. Pick a reference resolution (1080p is a natural choice) and scale everything else:

const scale = ch / 1080;
const fontSize = Math.round(cfg.fontSize * scale);   // e.g., 42px at 1080p → 19px at 480p
const padH = Math.round(cfg.boxPadH * scale);
const radius = Math.round(cfg.boxRadius * scale);

This means your caption configs stay as readable 1080p values (30px, 44px, 52px…) and the renderer handles the rest.

Why This Pattern Pays Off

Zero drift: The preview is byte-for-byte the same rendering logic as the export. What you see is literally what you get.
One place to fix bugs: Update drawCaptions, and both preview and export get the fix.
Testable: You can unit-test drawCaptions by passing a mock CanvasRenderingContext2D — no component needed.

If you're building any kind of browser-based video editor or export tool, getting your draw functions into a pure, importable module early is one of the highest-leverage architectural decisions you can make.

Two Subtle Bugs That Broke Our Remotion Vercel Sandbox (And How We Fixed Them)

nareshipme — Fri, 03 Apr 2026 15:42:00 +0000

We use Remotion to render video clips server-side, and we pre-build a Vercel Sandbox snapshot at deploy time so renders can restore it for fast cold starts instead of bundling from scratch on every request.

The flow looks like this:

next build compiles the Next.js app
node scripts/create-snapshot.mjs bundles the Remotion project, uploads it to a sandbox, takes a snapshot, and stores the snapshot ID in Vercel Blob
Render workers restore the snapshot instead of re-bundling

Last week, two separate bugs caused this to silently break in production. Here's what happened and what we changed.

Bug 1: Relative path passed to `addBundleToSandbox`

The @remotion/vercel package's addBundleToSandbox function uploads every file in the bundle directory to the sandbox. Under the hood it reads the directory, creates each file path in the sandbox, and streams the content.

The bug: we were passing a relative path:

const BUNDLE_DIR = ".remotion";
// ...
await addBundleToSandbox({ sandbox, bundleDir: BUNDLE_DIR });

This works fine when Node.js's CWD happens to be the project root — which it is locally and in most CI setups. But in certain Vercel build environments, the CWD at script execution time drifts from what you'd expect, and the relative path resolves to the wrong directory. The upload silently succeeds with zero or wrong files, and the snapshot is empty.

The fix is one line — resolve to an absolute path from the script's own __dirname:

import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const BUNDLE_DIR = ".remotion";

// Before (fragile):
await addBundleToSandbox({ sandbox, bundleDir: BUNDLE_DIR });

// After (always correct):
const bundleDir = path.resolve(__dirname, `../${BUNDLE_DIR}`);
await addBundleToSandbox({ sandbox, bundleDir });

Lesson: never trust relative paths in build scripts. Scripts can be invoked from anywhere. Always anchor to __dirname (or import.meta.url in ESM).

Bug 2: `addBundleToSandbox` chokes on subdirectories

Once we fixed the path, we hit a second failure: addBundleToSandbox was erroring when the bundle output contained a public/ subdirectory.

Remotion's bundler copies your project's public/ folder into the output by default. The sandbox API's internal mkDir call doesn't create parent directories recursively — it expects a flat structure. So any nested path like public/fonts/Inter.woff2 triggers an error because public/ wasn't created first.

There are two ways to fix this:

Option A: Pass publicDir: null to bundle() to skip copying the public folder entirely (works if your compositions don't depend on static assets from public/):

await bundle({
  entryPoint,
  outDir: bundleDir,
  enableCaching: true,
  publicDir: null, // don't copy public/ into the bundle
});

Option B: Let bundle() copy it, then delete it before uploading:

import { rm } from "fs/promises";

await bundle({ entryPoint, outDir: bundleDir, enableCaching: true });

// Remove public/ before upload — addBundleToSandbox can't handle subdirs
const publicDir = path.join(bundleDir, "public");
await rm(publicDir, { recursive: true, force: true });

await addBundleToSandbox({ sandbox, bundleDir });

We went with both: publicDir: null in bundle() plus the defensive rm as a belt-and-suspenders guard:

await bundle({
  entryPoint,
  outDir: bundleDir,
  enableCaching: true,
  publicDir: null,
});

// Defensive cleanup in case future Remotion versions change the default
const publicDir = path.join(bundleDir, "public");
await rm(publicDir, { recursive: true, force: true });

Bug 3 (Bonus): The snapshot failure was non-fatal

Both bugs above caused the snapshot script to error — but we had the error suppressed:

// package.json (before)
"vercel-build": "next build && node scripts/create-snapshot.mjs || echo '[create-snapshot] Skipped (non-fatal)'"

The || echo fallback was added during initial development so a missing BLOB_READ_WRITE_TOKEN wouldn't break staging deploys. But it meant snapshot failures in production were completely silent — the build succeeded, workers tried to restore a snapshot that didn't exist, and renders fell back to a full re-bundle (slow, and occasionally OOM).

The fix: remove the fallback. Let it fail the build loud:

// package.json (after)
"vercel-build": "next build && node scripts/create-snapshot.mjs"

If the snapshot step fails, the deployment fails. That's the right behavior — you find out immediately instead of running degraded for days.

Takeaways

Always use absolute paths in build scripts. CWD is an environment variable, not a constant.
Know your tool's flat-file assumptions. The Remotion Vercel sandbox API expects a flat bundle — no subdirectories. The bundler doesn't tell you this.
Don't swallow errors in build steps. The || echo pattern is fine for truly optional steps. If a step is required for production correctness, let it fail the build.

All three changes shipped in one small commit. The snapshot build is now fast, reliable, and loud when something goes wrong.

How We Fixed ESM-Only Package Crashes in a CJS Node.js Worker (Without Rewriting Everything)

nareshipme — Thu, 02 Apr 2026 17:08:01 +0000

When you mix a CommonJS Node.js worker with modern ESM-only packages, you get a crash that looks harmless but is actually an architectural problem. Here's how we hit it, diagnosed it, and fixed it without converting our entire codebase.

The Setup

Our stack:

A Next.js 15 app on Vercel (supports ESM natively)
A Railway worker — a separate Express + Inngest process compiled with tsc targeting CommonJS
Both share the same source, with the worker having its own tsconfig.json pointing to worker/src/

We recently migrated Remotion video rendering to Vercel Sandbox VMs. That meant importing @remotion/vercel, @vercel/blob, and @vercel/sandbox in our render pipeline.

All three packages are ESM-only. They ship no CJS bundle. If you require() them — directly or via TypeScript's static import compiled to CJS — Node.js throws:

Error [ERR_REQUIRE_ESM]: require() of ES Module
  node_modules/@remotion/vercel/dist/index.js not supported.
  Instead change the require of index.js to a dynamic import()

Our Railway worker was CJS. So the moment we added those imports at the top of the file, it crashed at startup — before handling a single job.

Why Static Imports Break CJS

TypeScript compiles import { createSandbox } from "@remotion/vercel" to:

// compiled output (CJS)
const remotion_vercel_1 = require("@remotion/vercel");

Node.js evaluates this synchronously at module load time. Since @remotion/vercel is ESM, the synchronous require() fails immediately.

This happens even if the code path that actually calls createSandbox is never reached in the Railway worker. The crash is at import time, not call time.

Fix: Dynamic `import()` at Call Site

The fix is to replace top-level static imports with dynamic import() calls inside the functions that actually need them. Dynamic imports are asynchronous and work in both CJS and ESM environments.

Before (crashes on Railway):

import { del } from "@vercel/blob";
import {
  addBundleToSandbox,
  createSandbox,
  renderMediaOnVercel,
  uploadToVercelBlob,
} from "@remotion/vercel";
import { restoreSnapshot } from "./restore-snapshot";

export async function renderWithRemotion(opts: RenderOpts) {
  // ...
  const sandbox = await createSandbox({ ... });
}

After (works in both CJS and ESM):

// No top-level ESM imports

export async function renderWithRemotion(opts: RenderOpts) {
  // Dynamic imports — @remotion/vercel and @vercel/blob are ESM-only packages.
  // Using dynamic import() avoids CJS require() failures on Railway worker.
  const { addBundleToSandbox, createSandbox, renderMediaOnVercel, uploadToVercelBlob } =
    await import("@remotion/vercel");
  const { del } = await import("@vercel/blob");
  const { restoreSnapshot } = await import("./restore-snapshot");

  // ...
  const sandbox = await createSandbox({ ... });
}

Same for restore-snapshot.ts which uses @vercel/blob and @vercel/sandbox:

// Before: static imports at top
import { get } from "@vercel/blob";
import { Sandbox } from "@vercel/sandbox";

export async function restoreSnapshot() {
  const blob = await get(snapshotBlobKey, { ... });
  return Sandbox.create({ ... });
}

// After: dynamic imports inside the function
export async function restoreSnapshot() {
  const { get } = await import("@vercel/blob");
  const { Sandbox } = await import("@vercel/sandbox");

  const blob = await get(snapshotBlobKey, { ... });
  return Sandbox.create({ ... });
}

But Railway Still Couldn't Call @remotion/vercel Directly

The dynamic import fix let the worker start without crashing. But we realized Railway couldn't actually render using @remotion/vercel even with dynamic imports — for a different reason.

@remotion/vercel internally uses @rspack/binding, a native Node.js addon. Vercel Sandbox VMs have the right environment for this. A Railway Docker container does not. The binding isn't available there.

So we split the responsibility:

Railway Inngest worker receives the render job, makes a POST /api/render HTTP call to Vercel
Vercel API route (/api/render) runs inside a proper Vercel environment, creates the Sandbox, renders, uploads to Vercel Blob, returns the URL
Railway worker downloads the rendered video from Blob, uploads to R2, cleans up

// worker/src/inngest-lib/render-clip.ts
export async function renderWithRemotion(opts: RenderOpts): Promise<void> {
  // Call the Vercel render API — Railway can't run @remotion/vercel natively
  const renderApiUrl = process.env.RENDER_API_URL || "https://yourapp.vercel.app/api/render";
  const renderApiSecret = process.env.RENDER_API_SECRET;

  const res = await fetch(renderApiUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${renderApiSecret}`,
    },
    body: JSON.stringify(inputProps),
    signal: AbortSignal.timeout(10 * 60 * 1000), // 10 min
  });

  const { url: blobUrl } = await res.json();

  // Download from Vercel Blob, write to disk
  const videoRes = await fetch(blobUrl);
  await fs.writeFile(outputPath, Buffer.from(await videoRes.arrayBuffer()));

  // Clean up temp blob (non-fatal if it fails — will expire)
  try {
    const { del } = await import("@vercel/blob");
    await del(blobUrl, { token: process.env.BLOB_READ_WRITE_TOKEN });
  } catch {
    console.warn("[remotion] Failed to delete temp blob, will expire");
  }
}

The TypeScript Typing Gotcha

One side effect of dynamic imports: you lose the inferred return type of restoreSnapshot(). Before, it was Promise<InstanceType<typeof Sandbox>>. After, TypeScript infers Promise<any> because the Sandbox type isn't visible at the top level.

The pragmatic fix: drop the explicit return type annotation and let TypeScript widen it. The callers don't inspect the sandbox object directly — they pass it to @remotion/vercel functions that accept any anyway.

If you need the type, you can import it separately as a type-only import (these are erased at compile time and don't trigger the CJS issue):

import type { Sandbox } from "@vercel/sandbox"; // type-only, safe in CJS

export async function restoreSnapshot(): Promise<Sandbox> {
  const { Sandbox: SandboxClass } = await import("@vercel/sandbox"); // runtime import
  return SandboxClass.create({ ... });
}

Takeaways

ESM-only packages crash CJS workers at startup, not at call time. If your worker is compiled to CJS, any top-level import of an ESM-only package will fail immediately.
import() is the escape hatch. Dynamic imports work in both CJS and ESM. Move ESM-only imports inside the functions that need them.
Dynamic imports don't fix native binary requirements. If a package needs a platform-specific native addon (like @rspack/binding), you need to run it in the right environment regardless of import style. In that case, HTTP delegation — having the worker call a Vercel API route that runs in the correct environment — is a clean solution.
import type is safe anywhere. Type-only imports are erased by TypeScript and never reach the Node.js module loader. You can use them freely in CJS code.

The full pattern — CJS worker → HTTP call → ESM-native Vercel route — let us keep Railway for job orchestration (where it excels: long-running workers, native binaries, Docker) and Vercel for rendering (where it excels: Sandbox VMs, ESM-native environment, Remotion integration).

DEV Community: nareshipme

Fixing yt-dlp in Docker: n-challenge EJS scripts, Deno 2.x, and the player_client=ios cookie trap

Background: what is the n-challenge?

Bug 1: Installing yt-dlp as a curl binary skips the EJS scripts

Bug 2: No JS runtime available for the n-challenge solver

Bug 3: player_client=ios silently drops cookies

Keeping yt-dlp current without rebuilding

Summary of changes

Debugging a Silent Failure: Presigned R2 Uploads and the Inngest Job That Never Ran

The Architecture in 30 Seconds

The Bug: A Missing PATCH

The Fix: Extend the PATCH Route and Send the Key

The Lesson: Presigned URLs Create Invisible Gaps

What Else Landed: Billing Scaffolding (Not Live Yet)

How We Made Waiting Fun: Whimsical Loading States and Stepped Progress in Next.js

The problem

Solution 1 — Rotating whimsical messages

Solution 2 — A stepped progress indicator

Bonus — Fixing the clip drag glitch

Takeaways

Teaching an AI Agent to Do TDD (And Actually Mean It)

The Problem With "Just Tell It"

Vertical Slices as Test Scenarios

Traceability Before You Merge

Takeaway

How We Replaced Polling With Server-Sent Events for Real-Time Video Processing Updates

The Polling Problem

Why We Chose Server-Sent Events Over WebSockets

The SSE Implementation

Results After the Switch

Lessons Learned

Try It Yourself

framewebworker: Browser-Native Video Rendering with OffscreenCanvas, Web Workers, and ffmpeg.wasm

The Problem with Server-Side Video Rendering

Introducing framewebworker

Core API

exportClips(videoUrl, segments[])

mergeClips(clips[])

useExportClips() — React hook

Architecture

RenderMetrics

COOP/COEP Headers Required

Bundle Size

When to Use framewebworker

Get Started

How We Ditched Backend Rendering and Went Full Client-Side with framewebworker

The Problem with Server-Side Video Rendering

Enter framewebworker

What We Deleted

What We Added

The Follow-Up: Rich Progress UI

Iterating on the API

Results

Docker Image Size

Infrastructure

User Experience

Takeaways for Your Projects

How We Moved Video Rendering From the Server to the Browser

The Problem With Server-Side Video Rendering

Enter framewebworker

What We Removed

What We Added

Real Progress Reporting

Performance and Cost Impact

Trade-offs

What This Means for Open Source Video Tools

Why Your Browser Video Export Has No Audio (And the Fix Using AudioContext + Gain Node)

The Setup

The Bug: Capturing from a Muted Element

The Fix: Unmute, Then Silence the Output Yourself

Why Not Just Use createMediaStreamSource?

Bonus: The Hidden Timing Issue

The Takeaway

How to Reuse Your Canvas 2D Rendering Pipeline for Live Video Preview (No Duplicate Code)

The Setup: Shared Draw Functions

The Export Loop (MediaRecorder)

The Preview Loop (No Recording)

The textBaseline = "top" Detail

Cross-Browser roundRect

Scaling Font Sizes from a Reference Resolution

The Bug: A Missing `PATCH`

Why Not Just Use `createMediaStreamSource`?

The `textBaseline = "top"` Detail

Cross-Browser `roundRect`

Bug 1: Relative path passed to `addBundleToSandbox`

Bug 2: `addBundleToSandbox` chokes on subdirectories

Fix: Dynamic `import()` at Call Site