DEV Community: mengyuxuan

Three things that broke when I moved video compression into the browser

mengyuxuan — Wed, 19 Aug 2026 02:41:10 +0000

I run a video compressor that works entirely in the browser.
No upload, no server, nothing leaves the machine. Two of the three bugs below
only showed up when I stopped reading code and started timing things, so I want
to write them down while the numbers are still in front of me.

The pipeline has three paths. If the file already meets the target, copy the
encoded samples and encode nothing. If the browser can decode the container,
transcode with WebCodecs. Otherwise fall back to ffmpeg.wasm, which is roughly
an order of magnitude slower. mediabunny handles the demux and remux.

AVI to Matroska with -c copy produces a 1151 byte file

The fast path needs mediabunny to be able to read the container. It cannot read
AVI, but plenty of AVI files carry H.264 inside, so the plan was to rewrap
losslessly and stay on the fast path:

ffmpeg -i in.avi -map 0:v:0 -map 0:a? -c copy \
       -avoid_negative_ts make_zero out.mkv

That fails. Not slowly, not subtly:

[matroska] Timestamps are unset in a packet for stream 0
[matroska] Can't write packet with unknown timestamp
[out#0/matroska] Error muxing a packet

AVI has no per-packet timestamps. It stores a fixed frame rate plus an index and
lets the demuxer work them out. Matroska requires timestamps on every block, so
the copy has nothing to write. What comes out is a 1151 byte header with zero
clusters, which is a valid Matroska file containing no media.

-avoid_negative_ts does not help, and it took me longer than it should have to
see why: the timestamps are not negative, they are absent. Two different
problems that produce similar looking errors.

The fix is one flag on the input side:

ffmpeg -fflags +genpts -i in.avi -map 0:v:0 -map 0:a? -c copy \
       -avoid_negative_ts make_zero out.mkv

+genpts synthesises presentation timestamps from the stream's frame rate.
Output went from 1151 bytes to 55.8 MB on a 20 second 1080p30 clip, all 600
frames decoding cleanly.

Then I measured it against a control. Same geometry, same duration, same target,
but Xvid instead of H.264 so it takes the ffmpeg path:

H.264 AVI, rewrap then WebCodecs   7.5 s    53.3 MB to 12.3 MB
Xvid AVI, ffmpeg.wasm             53.4 s    48.2 MB to 12.5 MB

Output sizes within 2 percent, wall clock 7x apart. Both numbers come from
headless Chromium with software encoding, so a real machine with a hardware
encoder should do better than this.

One more thing worth doing: ffmpeg.wasm resolves with the exit code instead of
rejecting, and a muxer that dies mid run still leaves a readable file behind. A
truncated remux looks exactly like a complete one unless you check.

Every AAC track defeats mediabunny's copy path, by design

The passthrough case is supposed to touch nothing. Give mediabunny an empty
video config and it copies encoded samples straight through, since
forceTranscode defaults to false.

It worked for video and not for audio. A 3.3 MB source came back at 3.6 MB, so
I parsed the output boxes:

source   moov 33,948   mdat 3,432,287
output   moov 17,879   mdat 3,788,908

The moov got smaller. The growth was all in mdat. Per track:

avc1   900 samples   3,071,520 bytes
mp4a  1295 samples     717,380 bytes

Video was byte identical to the source. Audio was double: 717 KB against the
source's 360 KB, about 191 kbps from a 96 kbps original.

The reason is in mediabunny's copy conditions. The fast path requires, among
other things, !needsTrimming, where needsTrimming is
firstTimestamp < startTimestamp. I asked the library what it saw:

video codec: avc   firstTimestamp: 0
audio codec: aac   firstTimestamp: -0.023219954648526078

Negative. And 0.0232 seconds at 44100 Hz is 1024 samples, which is exactly one
AAC frame. That is encoder priming delay, and every AAC track produced by any
normal encoder has it. So the audio copy path is not occasionally unavailable,
it is never available.

You cannot fix this from the outside. Passing a bitrate to keep the size down
forces a transcode by itself, because !trackOptions.bitrate is one of the
copy conditions. Passing nothing lets the library re-encode at its own default.

I went with a floor instead: if a passthrough would return more bytes than it
received, and the source is already MP4, hand back the source untouched.
Verified byte exact, 3,466,275 in and 3,466,275 out where it used to be
3,806,815. For a file that was already close to optimal, "nothing needed doing"
is a more honest answer than a 10 percent larger file.

The multithreaded ffmpeg core costs you your ad revenue

@ffmpeg/core-mt is 4 to 8 times faster than the single threaded core. It needs
SharedArrayBuffer, which needs cross origin isolation, which means sending
COOP and COEP headers.

COEP: require-corp breaks third party embeds that do not opt in. On a site
funded by AdSense that is not a technical tradeoff, it is a revenue decision.
I stayed single threaded and put the effort into not reaching for ffmpeg at all,
which is what the rewrap path above is for.

What I would take away from this

Both real bugs were invisible to code review and to unit tests. The AVI failure
had a passing test suite and a plausible looking implementation sitting on top
of it. What found it was dragging an actual AVI file into an actual browser and
noticing that a 54 MB input had produced 1151 bytes.

If you want to try it on something awkward, the two cases I get asked about most
have their own pages: compress video for Discord
if you are fighting the 10 MB free tier limit, and
compress video to 10 MB if the
cap is the whole problem. Both run on your own machine.

I built a video compressor with zero backend — your files never leave the tab

mengyuxuan — Wed, 22 Jul 2026 08:07:50 +0000

Drop a 200 MB screen recording into most "free video compressor" sites and here's what actually happens: the file uploads to someone's server, gets transcoded there, and you download the result. Your video sat on a stranger's disk. The site paid for bandwidth and CPU, so it pays that back with aggressive ads or a paywall at 3 files a day.

I wanted the opposite: the compression runs in your browser tab, the file never leaves your machine, and because there's no server doing the work, the whole thing is genuinely free to run.

That's videocompress.dev. This post is how it works under the hood.

The core constraint: no upload, ever

The entire architecture falls out of one rule — the video bytes stay client-side. That immediately kills the "rent a beefy transcoding server" design and forces the work into the browser. Two APIs can do it:

WebCodecs — a low-level browser API that talks to the OS's hardware video encoder/decoder. Fast, uses almost no CPU, native-quality H.264.
ffmpeg.wasm — the full FFmpeg compiled to WebAssembly. Works literally everywhere, but it's a software encoder running in a WASM sandbox, so it's slower.

WebCodecs is the better experience when it's available. It isn't always. So the app probes the browser and picks.

Picking an engine at runtime

The selection logic is deliberately boring — a pure function that's trivial to unit test:

export type CompressionEngine = "webcodecs" | "ffmpeg";

export interface EngineCaps {
  hasWebCodecsApi: boolean;   // VideoEncoder + VideoDecoder exist
  inputReadable: boolean;     // we can actually demux + decode this file
  canEncodeTarget: boolean;   // the target H.264 config is encodable here
}

export function decideEngine(caps: EngineCaps): CompressionEngine {
  return caps.hasWebCodecsApi && caps.inputReadable && caps.canEncodeTarget
    ? "webcodecs"
    : "ffmpeg";
}

The important detail is the third capability. Having the WebCodecs API isn't enough — the browser also has to be able to demux the specific container you dropped in and encode the target config. So before committing, the app asks mediabunny whether it can read the input's primary video track and whether VideoEncoder.isConfigSupported() accepts the output config.

Any false, anything unprobed, anything that throws → fall back to ffmpeg.wasm. WebCodecs is the fast path you earn by passing every check; ffmpeg is the floor that always catches you. Users on the happy path get hardware speed; everyone else still gets a working compressor. Nobody gets a broken page.

The actual "compression": it's bitrate math

"Compress this to 25 MB for email" sounds like a quality knob, but under the hood it's arithmetic. A video file's size is roughly bitrate × duration. If you know the target size and the duration, you can solve for the bitrate:

export const AUDIO_KBPS = 128;
export const TARGET_SIZE_SAFETY = 0.94; // aim slightly under so we don't overshoot

export function computeTargetVideoKbps({
  targetSizeMB,
  durationSec,
  removeAudio,
}: {
  targetSizeMB: number;
  durationSec: number;
  removeAudio: boolean;
}): number {
  const audioKbps = removeAudio ? 0 : AUDIO_KBPS;
  const safeTargetMB = targetSizeMB * TARGET_SIZE_SAFETY;
  const videoKbps = (safeTargetMB * 8192) / Math.max(durationSec, 1) - audioKbps;
  return Math.max(Math.round(videoKbps), 100);
}

Two things I learned the hard way and baked in:

The 6% safety margin (0.94). Encoders don't hit a bitrate target exactly; they hover around it. If you aim for exactly 25 MB you'll ship 26 and blow the email limit. Aiming for ~23.5 lands under it reliably.
Subtract the audio budget first. The size cap is for the whole file. Spend 128 kbps on audio and the video has to fit in what's left — otherwise your "target size" mode quietly ignores the audio track and overshoots.

The other mode is quality-based, which maps straight to H.264's CRF (constant rate factor):

const QUALITY_CRF = { high: 20, balanced: 23, small: 28 };

Lower CRF = better quality + bigger file. 23 is a genuinely good default for most footage; 28 is where you go when "smaller" matters more than "pristine."

Why "no server" changes the whole economics

This is the part I think other devs will appreciate. Because the transcode happens in the tab:

Hosting is basically free. The app is 100% static — it's just HTML, JS, and a WASM blob on a CDN. No transcoding boxes, no per-video cost, no scaling worries. A traffic spike costs bandwidth on static assets, nothing more.
Privacy is architectural, not a promise. Plenty of sites say "we delete your files." Here there's nothing to delete because nothing was ever sent. Open DevTools → Network tab and compress a file: zero upload requests.
It works offline once the page and core are cached.

The one gotcha: @ffmpeg/core-mt (the multithreaded build) needs SharedArrayBuffer, which needs cross-origin isolation (COOP/COEP headers), which breaks a lot of third-party embeds. I chose the single-thread @ffmpeg/core on purpose — slightly slower, but no header gymnastics and full compatibility with everything else on the page. Know your tradeoff before you reach for the MT build.

The stack

Nothing exotic, deliberately:

Next.js 16 (App Router) + React 19 + TypeScript
Tailwind CSS 4
@ffmpeg/ffmpeg 0.12 for the fallback path, mediabunny for WebCodecs demux/probing
Static export — every page is SSG, deployable to Vercel / Cloudflare Pages / Netlify free tiers

The compression parameter functions (the bitrate/CRF math above) are pure and covered by node --test unit tests. When the thing that matters is "did we compute the right bitrate," you want that logic testable without spinning up a browser or a real encoder.

Try it / read it

The tool: videocompress.dev — drop a file in, pick a target size or quality, download. No account, no upload, no watermark.
If you're building something similar, the WebCodecs-with-ffmpeg-fallback pattern and the bitrate math are the two pieces worth stealing.

If you end up shipping in-browser media processing, I'd genuinely like to hear how you handled the engine-selection edge cases — the "API exists but can't encode this" gap is where most of the real bugs live. Drop a comment.