const { spawn } = require('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) => {
  console.log(`FFmpeg: ${data}`);
});

ffmpeg.on('close', (code) => {
  console.log(`FFmpeg exited with code ${code}`);
});

s. Wrap in a queue system (e.g., BullMQ) to limit concurrent child processes and protect the event loop.

2. Fluent-FFmpeg Wrapper

Ideal for teams migrating from CLI-heavy workflows to a chainable Node.js API without rewriting infrastructure.

const ffmpeg = require('fluent-ffmpeg');

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

Architecture Decision: Treat as a convenience layer, not a replacement for native binary management. Pin fluent-ffmpeg versions in package.json due to infrequent upstream maintenance. Implement explicit codec fallbacks and validate ffmpeg -codecs at startup.

3. WebAssembly Runtime (ffmpeg.wasm)

Suitable for client-side or edge environments where native binary installation is impossible, and file sizes remain small.

const { FFmpeg } = require('@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');

Architecture Decision: Enforce strict file size limits (<100MB). Disable hardware acceleration expectations. Use SharedArrayBuffer and Web Workers to isolate WASM execution from the main thread. Not recommended for server-side transcoding pipelines.

4. Cloud API Integration (Zero Install)

Optimal for serverless deployments, multi-tenant SaaS, or teams prioritizing operational simplicity and auto-scaling.

const response = await fetch('https://api.ffmpeg-micro.com/v1/transcodes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputs: [{ url: 'https://example.com/input.mp4' }],
    outputFormat: 'mp4',
    preset: { quality: 'high', resolution: '1080p' }
  })
});

const job = await response.json();
console.log(`Job ${job.id} queued, status: ${job.status}`);

For advanced codec control, pass raw FFmpeg options:

const response = await fetch('https://api.ffmpeg-micro.com/v1/transcodes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputs: [{ url: 'https://example.com/input.mp4' }],
    outputFormat: 'webm',
    options: [
      { option: '-c:v', argument: 'libvpx-vp9' },
      { option: '-crf', argument: '30' },
      { option: '-b:v', argument: '0' }
    ]
  })
});

Architecture Decision: Implement idempotent job polling with exponential backoff. Store job IDs in a database for async state tracking. Use webhooks for completion notifications to avoid polling overhead. Offload all codec management, scaling, and storage to the provider.

Pitfall Guide

1. Binary Not Found / PATH Misconfiguration: FFmpeg binaries are rarely pre-installed in minimal Docker images or serverless runtimes. Always verify binary availability at startup using which ffmpeg or spawnSync('ffmpeg', ['-version']). In Docker, use multi-stage builds with official FFmpeg base images (jrottenberg/ffmpeg or linuxserver/ffmpeg) to guarantee PATH consistency.
2. Memory Spikes & OOM on Large Files: Node.js buffers stdout/stderr by default, causing heap exhaustion when processing multi-gigabyte videos. Always stream output directly to disk or cloud storage using pipe() or createWriteStream(). Tune highWaterMark (default 64KB) based on your I/O throughput, and avoid .toString() or .join() on FFmpeg streams.
3. Codec Availability Mismatches: Precompiled FFmpeg binaries vary by distribution. A codec available locally (libx265, libsvtav1) may be missing in production. Run ffmpeg -codecs during deployment health checks. Pin Docker image digests instead of latest tags to prevent silent codec drift across environments.
4. Silent Failures via Stderr Misrouting: FFmpeg writes progress, warnings, and errors to stderr, not stdout. Ignoring stderr or only listening to stdout masks critical failures. Always attach a stderr.on('data') listener, parse FFmpeg's timecode/progress lines, and implement structured logging with severity levels.
5. Event Loop Blocking & Concurrency Limits: Spawning multiple FFmpeg processes synchronously or without concurrency limits starves the V8 event loop, causing API timeouts. Use a job queue (BullMQ, Agenda, or AWS SQS) with a worker pool. Limit concurrent spawn() calls to os.cpus().length - 1 to preserve system responsiveness.
6. WASM Memory Caps & Codec Gaps: ffmpeg.wasm runs in a sandboxed heap with strict memory limits (typically 2GB in browsers, configurable in Node.js). Large files trigger RangeError: Maximum call stack size exceeded or silent truncation. Additionally, WASM builds lack hardware acceleration and certain proprietary codecs. Enforce client-side file size validation and implement fallback to native/cloud processing for heavy workloads.

Deliverables

📘 FFmpeg Integration Blueprint A decision matrix mapping deployment environments (Docker, AWS Lambda, Vercel, On-Prem) to the optimal FFmpeg integration pattern, including concurrency limits, stream backpressure configurations, and monitoring hooks.

✅ Pre-Deployment Verification Checklist

• Verify FFmpeg binary exists and matches expected version (ffmpeg -version)
• Audit available codecs against pipeline requirements (ffmpeg -codecs)
• Configure stream highWaterMark and pipe destinations (disk/S3)
• Attach stderr listeners with structured error parsing
• Implement concurrency limits or job queue integration
• Validate environment parity (dev/staging/prod Docker base images)
• Add health check endpoint reporting FFmpeg status and queue depth

⚙️ Configuration Templates

• Dockerfile (Multi-Stage FFmpeg): Production-ready image with pinned FFmpeg version, non-root user, and optimized layer caching for Node.js + FFmpeg workloads.
• Node.js Stream Wrapper: Reusable spawnFFmpeg() utility with backpressure handling, timeout guards, stderr parsing, and Promise-based resolution.
• Cloud API Integration Config: TypeScript types for request/response payloads, retry logic with exponential backoff, and webhook signature verification template.