Compress videos in the browser before upload

Install

npm install github:karuha-m/browser-video-compression

Ships as an ES module with TypeScript type definitions and uses mediabunny to read and write media files.

Quick start

Call compressVideo after the user selects a file, then pass result.file to your existing upload code.

import { compressVideo } from 'browser-video-compression';

input.addEventListener('change', async (event) => {
  const original = event.target.files[0];

  const result = await compressVideo(original, {
    maxWidthOrHeight: 1280, // 720p
    skipBelowMB: 10,        // small files are uploaded as they are
    onProgress: (p) => console.log(Math.round(p * 100) + '%'),
  });

  // result.file is the compressed file, or the original when
  // compression was skipped (see result.skipReason)
  const body = new FormData();
  body.append('video', result.file);
  await fetch('/upload', { method: 'POST', body });
});

With an upload library

result.file is a standard File object, so it works with tus, Uppy, S3 presigned URLs, and Mux or Cloudflare Stream direct uploads.

import * as tus from 'tus-js-client';

const { file } = await compressVideo(original);
new tus.Upload(file, { endpoint: '/files/' }).start();

Preflight checks

inspectVideo reads container metadata without decoding the whole file, so you can check duration, resolution and codecs before uploading.

import { inspectVideo } from 'browser-video-compression';

const info = await inspectVideo(file);
// { duration, width, height, videoCodec, audioCodec, bitrate, canDecode, ... }
if (info.duration > 600) alert('Please keep videos under 10 minutes.');

Cancelling

const controller = new AbortController();
cancelButton.onclick = () => controller.abort();

const result = await compressVideo(file, { signal: controller.signal });

Options

The result contains file, compressed, skipReason, originalSize, size, width, height and duration. The promise rejects only when the caller aborts; otherwise, when compressed is false, skipReason explains why the original file was returned:

• already-smallThe file is already below skipBelowMB and within the size limit.
• unsupported-browserThis browser has no usable WebCodecs encoder.
• unsupported-inputThe file has no video track, or this browser cannot decode its video.
• not-smallerThe compressed result was not smaller than the original.
• failedCompression failed; see the error field for details.

Browser Support

Use Cases

To see the compression results first, try VideoKit's online video compressor, which also processes files in the browser.

Frequently Asked Questions