How to Use FFmpeg with TypeScript (No Installation Required)

Originally published at ffmpeg-micro.com

You need to process video in your TypeScript project. Maybe you're building a Next.js app that generates thumbnails, a Bun server that transcodes user uploads, or an Express API that automates video workflows. You search for "ffmpeg typescript" and find a mess of untyped wrappers, broken binaries, and workarounds.

TypeScript developers deserve type-safe video processing. But most approaches to FFmpeg in the Node.js ecosystem were built for JavaScript first, and the TypeScript experience is an afterthought. There are several paths, each with real tradeoffs.

Using child_process with TypeScript

The lowest-level approach. Install FFmpeg on your system and call it via Node's child_process:

import { spawn } from 'child_process';

const ffmpeg = spawn('ffmpeg', [
  '-i', 'input.mp4',
  '-c:v', 'libx264',
  '-crf', '23',
  '-preset', 'medium',
  '-c:a', 'aac',
  '-b:a', '192k',
  'output.mp4'
]);

ffmpeg.stderr.on('data', (data: Buffer) => {
  console.log(`FFmpeg: ${data.toString()}`);
});

ffmpeg.on('close', (code: number | null) => {
  if (code !== 0) {
    throw new Error(`FFmpeg exited with code ${code}`);
  }
  console.log('Transcoding complete');
});

TypeScript's type annotations give you Buffer and number | null on the callbacks. But that's where the type safety ends. The FFmpeg arguments are just strings. Typo in -c:v? TypeScript won't catch it. Wrong codec name? You'll find out at runtime. And you still need FFmpeg installed on every machine that runs your code.

Using fluent-ffmpeg with TypeScript

fluent-ffmpeg has community-maintained type definitions via @types/fluent-ffmpeg:

import ffmpeg from 'fluent-ffmpeg';

ffmpeg('input.mp4')
  .videoCodec('libx264')
  .audioCodec('aac')
  .size('1280x720')
  .on('end', () => console.log('Done'))
  .on('error', (err: Error) => console.error(err.message))
  .save('output.mp4');

The types cover the chainable API, so you get autocomplete for methods like .videoCodec() and .size(). But the types are community-maintained and frequently lag behind the library. You'll hit any types in edge cases, especially around filters and complex operations. And fluent-ffmpeg still requires a local FFmpeg binary. In Docker deployments, that adds 80-200MB to your image.

ffmpeg.wasm for Browser-Side TypeScript

ffmpeg.wasm compiles FFmpeg to WebAssembly and ships with its own TypeScript types:

import { FFmpeg } from '@ffmpeg/ffmpeg';

const ffmpeg = new FFmpeg();
await ffmpeg.load();
await ffmpeg.writeFile('input.mp4', inputData);
await ffmpeg.exec(['-i', 'input.mp4', '-c:v', 'libx264', 'output.mp4']);
const data = await ffmpeg.readFile('output.mp4');

No binary installation. Runs in the browser or Node.js. But processing is 10-20x slower than native FFmpeg, memory is limited to what the browser tab can allocate, and not all codecs are available in the WASM build. Fine for trimming a 30-second clip. Don't try transcoding a 1GB file.

Cloud API: Type-Safe FFmpeg Without Installing Anything

If you don't want to manage FFmpeg binaries, deal with platform-specific builds, or add hundreds of megabytes to your Docker image, a cloud API is the cleanest path for TypeScript developers.

FFmpeg Micro is a cloud API that lets you process video with a single HTTP call. No FFmpeg installation, no server management, no binary dependencies. And because it's just HTTP, it works with TypeScript's type system naturally.

Here's a fully typed example:

interface TranscodeInput {
  url: string;
}

interface TranscodeRequest {
  inputs: TranscodeInput[];
  outputFormat: string;
  preset?: {
    quality: 'low' | 'medium' | 'high';
    resolution?: '480p' | '720p' | '1080p' | '4k';
  };
  options?: {
    option: string;
    argument: string;
  }[];
}

interface TranscodeResponse {
  id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
  outputUrl?: string;
  billableMinutes?: number;
}

async function transcodeVideo(
  request: TranscodeRequest
): Promise<TranscodeResponse> {
  const response = await fetch(
    'https://api.ffmpeg-micro.com/v1/transcodes',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.FFMPEG_MICRO_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(request),
    }
  );

  if (!response.ok) {
    throw new Error(`Transcode failed: ${response.statusText}`);
  }

  return response.json();
}

Now you can call it with full type safety:

const result = await transcodeVideo({
  inputs: [{ url: 'https://example.com/video.mp4' }],
  outputFormat: 'mp4',
  preset: { quality: 'high', resolution: '1080p' },
});

console.log(`Job ${result.id} status: ${result.status}`);

The TypeScript compiler catches bad property names, wrong types, and invalid enum values at build time. No runtime surprises from typo'd FFmpeg flags.

Polling for Job Completion

Transcode jobs are async. Here's a type-safe polling function:

async function waitForTranscode(
  jobId: string,
  maxWaitMs = 300000
): Promise<TranscodeResponse> {
  const start = Date.now();

  while (Date.now() - start < maxWaitMs) {
    const response = await fetch(
      `https://api.ffmpeg-micro.com/v1/transcodes/${jobId}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.FFMPEG_MICRO_API_KEY}`,
        },
      }
    );

    const job: TranscodeResponse = await response.json();

    if (job.status === 'completed' || job.status === 'failed') {
      return job;
    }

    await new Promise((r) => setTimeout(r, 2000));
  }

  throw new Error(`Timed out waiting for job ${jobId}`);
}

Use it after creating a transcode:

const job = await transcodeVideo({
  inputs: [{ url: 'https://example.com/raw-upload.mov' }],
  outputFormat: 'mp4',
  preset: { quality: 'medium' },
});

const completed = await waitForTranscode(job.id);
console.log(`Output ready: ${completed.outputUrl}`);

Advanced: Custom FFmpeg Options with Type Safety

For operations beyond presets (specific codecs, filters, bitrate control), use the options array:

const result = await transcodeVideo({
  inputs: [{ url: 'https://example.com/video.mp4' }],
  outputFormat: 'webm',
  options: [
    { option: '-c:v', argument: 'libvpx-vp9' },
    { option: '-crf', argument: '30' },
    { option: '-b:v', argument: '0' },
    { option: '-c:a', argument: 'libopus' },
  ],
});

The options array accepts any valid FFmpeg flag. You get the full power of FFmpeg's CLI without managing the binary.

Which Approach Should You Use?

It depends on your constraints:

For most TypeScript projects shipping to production, the cloud API approach gives you the best developer experience. No binary to install. No Docker image bloat. No platform-specific builds breaking in CI. Just typed HTTP calls that work the same everywhere your TypeScript runs.

FAQ

Can I use FFmpeg with Deno or Bun in TypeScript?

Yes. Since the cloud API approach uses standard fetch, it works in any TypeScript runtime: Node.js, Deno, Bun, Cloudflare Workers, or even the browser. No runtime-specific dependencies.

Does FFmpeg Micro have an official TypeScript SDK?

Not yet. But since the API is simple REST (POST to create a job, GET to check status), the typed fetch wrapper shown above covers every operation. The OpenAPI spec is available at ffmpeg-micro.com/docs if you want to generate types from it.

How much does cloud video processing cost vs. running FFmpeg locally?

FFmpeg Micro charges per minute of video processed, starting with a free tier. For production workloads, this is typically cheaper than maintaining your own FFmpeg infrastructure when you factor in server costs, DevOps time, and scaling. A 1-minute video transcode takes about 3 seconds via the API.

Can I use FFmpeg Micro with Next.js API routes?

Yes. API routes in Next.js run on the server. Use the typed fetch wrapper from a route handler or server action. No binary installation needed since the processing happens in the cloud, not on your server.

What video formats does the FFmpeg Micro API support?

The API supports all formats FFmpeg supports as input. For output, specify the format in the outputFormat field: mp4, webm, avi, mov, mkv, gif, mp3, wav, and more. See the full docs at ffmpeg-micro.com/docs.