ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height,r_frame_rate,duration -of json source_media.webm

ffmpeg -i source_media.webm -c:v libx265 -preset medium -crf 23 -c:a aac -b:a 128k -movflags +faststart processed_output.mp4

ffmpeg -i source_media.webm -c:v libx265 -crf 28 -preset fast -c:a aac -b:a 96k -threads 4 compressed_variant.mp4

ffmpeg -i source_media.webm -vf "scale=1280:-2" -c:v libx265 -crf 23 -c:a copy resized_feed.mp4

ale=1280:-2forces width to 1280px while auto-calculating height, ensuring the result is divisible by 2. The-2suffix is non-negotiable for hardware encoders and many software decoders.-c:a copypreserves the original audio track without re-encoding, saving compute cycles. When extracting audio only, replace-vfwith-vnand specify-c:a libmp3lame -q:a 2`.

5. Precision Trimming

Trimming is frequently implemented incorrectly, causing desync or excessive processing time. The seek position dictates performance.

ffmpeg -ss 00:01:15 -i source_media.webm -to 00:01:45 -c copy trimmed_segment.mp4

Why placement matters: -ss before -i enables fast seeking by jumping to the nearest keyframe. -to specifies the absolute end timestamp, which is more predictable than -t (duration) when chaining operations. -c copy avoids re-encoding entirely. If frame-accurate trimming is required, move -ss after -i and accept the performance penalty, or use the trim and setpts filters for sample-accurate cuts.

Pitfall Guide

1. The Overwrite Prompt Trap

Explanation: FFmpeg prompts interactively before overwriting existing output files. In automated pipelines, this causes the process to hang indefinitely, consuming a worker thread until timeout. Fix: Always append -y to force silent overwrites. For safety-critical systems, implement a pre-check that verifies file existence and rotates output names using UUIDs or timestamps.

2. The Seek Position Anti-Pattern

Explanation: Placing -ss after -i forces FFmpeg to decode and discard frames until reaching the target timestamp. On large files, this can increase processing time by 10-50x. Fix: Position -ss before -i for fast keyframe seeking. Reserve post-input -ss only when sample-accurate cuts are mandatory, and pair it with -c copy only if the target aligns with a keyframe.

3. Extension vs Codec Assumption

Explanation: File extensions are container labels, not codec declarations. An .mp4 file may contain H.264, H.265, VP9, or AV1 video streams. Blindly applying codec-specific filters causes silent failures or corrupted output. Fix: Run ffprobe first. Validate codec_name against your pipeline requirements. Implement a codec whitelist/blacklist in your application logic before invoking FFmpeg.

4. Silent Failure Propagation

Explanation: FFmpeg returns non-zero exit codes on failure, but many wrapper scripts ignore them. Corrupt or incomplete files propagate downstream, causing playback errors or storage bloat. Fix: Always check $? in shell scripts or process.exitCode in Node.js. Implement retry logic with exponential backoff for transient I/O errors, and route permanent failures to a dead-letter queue for manual inspection.

5. Pixel Format Mismatch

Explanation: H.264 encoders default to yuv420p. If the input uses yuv444p or rgb24, the encoder may fail or produce incompatible output for web players. Fix: Explicitly set -pix_fmt yuv420p in your command chain. This forces a software conversion that guarantees broad decoder compatibility, especially for mobile and legacy browsers.

6. Thread Contention in Containers

Explanation: FFmpeg auto-detects CPU cores and spawns threads accordingly. In containerized environments with CPU limits, this causes context switching overhead and throttling. Fix: Pass -threads N where N matches your container's allocated vCPUs. For Kubernetes, derive this value from $(nproc) or environment variables injected by the orchestrator.

7. Audio/Video Desync in Concat Operations

Explanation: Concatenating files with mismatched timestamps, sample rates, or codec parameters causes drift, especially when using the concat demuxer. Fix: Normalize all inputs to identical codecs, sample rates (-ar 48000), and frame rates before concatenation. Use the concat filter (-filter_complex concat) instead of the concat protocol when precise synchronization is required.

Production Bundle

Action Checklist

• Validate input metadata with ffprobe before invoking ffmpeg
• Enforce -y flag in all automated scripts to prevent interactive hangs
• Position -ss before -i for fast seeking; use -to for absolute end times
• Explicitly set -pix_fmt yuv420p for H.264/H.265 web delivery
• Cap thread count with -threads to match container CPU limits
• Verify exit codes and route failures to monitoring/alerting pipelines
• Use -c copy whenever re-encoding is unnecessary to preserve compute budget
• Implement output rotation with unique identifiers to prevent accidental overwrites

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
User uploads require format normalization	Local CLI with -c copy + container repackaging	Zero re-encode overhead, instant processing	Storage I/O only
Adaptive bitrate streaming generation	Local CLI with multi-pass CRF encoding	Consistent quality across resolutions	CPU hours scale linearly with variants
High-volume user uploads (>10k/day)	Managed API or dedicated media cluster	Auto-scaling, no infra management	Per-minute billing vs fixed server costs
Frame-accurate clip extraction	Local CLI with post-input -ss + filter graph	Sample precision required for editing	10-50x latency increase, CPU bound
Legacy browser compatibility	Local CLI with libx264 + yuv420p	Maximum decoder support across devices	Moderate CPU, optimal storage size

Configuration Template

A production-ready TypeScript wrapper using child_process.spawn with stream piping, error handling, and timeout management:

import { spawn } from 'child_process';
import { createWriteStream } from 'fs';
import { promisify } from 'util';

interface MediaProcessConfig {
  inputPath: string;
  outputPath: string;
  args: string[];
  timeoutMs?: number;
  maxRetries?: number;
}

export async function executeMediaPipeline(config: MediaProcessConfig): Promise<void> {
  const { inputPath, outputPath, args, timeoutMs = 300000, maxRetries = 2 } = config;
  
  const commandArgs = [
    '-y',
    '-i', inputPath,
    ...args,
    outputPath
  ];

  const ffmpeg = spawn('ffmpeg', commandArgs);
  const outputWriter = createWriteStream(outputPath);

  return new Promise((resolve, reject) => {
    let timedOut = false;
    const timer = setTimeout(() => {
      timedOut = true;
      ffmpeg.kill('SIGTERM');
      reject(new Error(`Media pipeline timed out after ${timeoutMs}ms`));
    }, timeoutMs);

    ffmpeg.stderr.on('data', (chunk) => {
      // Pipe stderr to logger in production; suppress for clean output
      console.debug(`[FFmpeg] ${chunk.toString().trim()}`);
    });

    ffmpeg.on('close', (code) => {
      clearTimeout(timer);
      if (timedOut) return;
      
      if (code === 0) {
        resolve();
      } else {
        reject(new Error(`FFmpeg exited with code ${code}`));
      }
    });

    ffmpeg.on('error', (err) => {
      clearTimeout(timer);
      reject(err);
    });
  });
}

// Usage example: Compress with adaptive CRF
await executeMediaPipeline({
  inputPath: '/tmp/uploads/source_media.webm',
  outputPath: '/tmp/processed/compressed_variant.mp4',
  args: [
    '-c:v', 'libx265',
    '-crf', '28',
    '-preset', 'fast',
    '-c:a', 'aac',
    '-b:a', '96k',
    '-threads', '4',
    '-pix_fmt', 'yuv420p'
  ],
  timeoutMs: 180000
});

Quick Start Guide

1. Install FFmpeg: Use your system package manager (apt install ffmpeg, brew install ffmpeg, or official binaries). Verify with ffmpeg -version.
2. Inspect Your Media: Run ffprobe -v error -show_format -show_streams input.webm -of json to extract codec, resolution, and duration metadata.
3. Execute a Safe Transcode: Use the template above with -c copy first to verify pipeline connectivity, then swap to -crf 28 for compression.
4. Validate Output: Run ffprobe on the generated file. Confirm codec names, pixel format, and duration match expectations.
5. Integrate Monitoring: Log exit codes, processing duration, and file size deltas. Alert on non-zero exits or output files exceeding 150% of input size.

Media processing at scale is not about memorizing flags. It's about enforcing constraints, validating assumptions, and selecting the right execution boundary for your workload. Master the inspection-to-execution pipeline, respect stream boundaries, and let infrastructure scale handle the rest.