tility extracts codec metadata without decoding the media. This step determines whether remuxing or transcoding is required.

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

interface StreamProfile {
  videoCodec: string;
  audioCodec: string;
  container: string;
}

async function inspectSource(sourceUrl: string): Promise<StreamProfile> {
  const { stdout } = await execAsync(
    `ffprobe -v quiet -print_format json -show_format -show_streams "${sourceUrl}"`
  );
  const probe = JSON.parse(stdout);
  
  const videoStream = probe.streams.find((s: any) => s.codec_type === 'video');
  const audioStream = probe.streams.find((s: any) => s.codec_type === 'audio');
  
  return {
    videoCodec: videoStream?.codec_name || 'unknown',
    audioCodec: audioStream?.codec_name || 'unknown',
    container: probe.format.format_name || 'unknown'
  };
}

Step 2: Strategy Router

The router evaluates target container constraints against source codecs. It returns a configuration object that dictates execution parameters.

type TranscodeStrategy = 'remux' | 'transcode-vp9' | 'transcode-h264';

interface PipelineConfig {
  strategy: TranscodeStrategy;
  videoCodec: string;
  audioCodec: string;
  extraFlags: string[];
}

function resolveStrategy(source: StreamProfile, targetContainer: 'mp4' | 'webm'): PipelineConfig {
  const mp4CompatibleVideo = ['h264', 'hevc', 'av1'];
  const mp4CompatibleAudio = ['aac', 'mp3'];
  const webmCompatibleVideo = ['vp8', 'vp9', 'av1'];
  const webmCompatibleAudio = ['vorbis', 'opus'];

  if (targetContainer === 'mp4') {
    const canRemux = mp4CompatibleVideo.includes(source.videoCodec) && 
                     mp4CompatibleAudio.includes(source.audioCodec);
    return canRemux 
      ? { strategy: 'remux', videoCodec: 'copy', audioCodec: 'copy', extraFlags: ['-movflags', '+faststart'] }
      : { strategy: 'transcode-h264', videoCodec: 'libx264', audioCodec: 'aac', extraFlags: ['-crf', '23', '-movflags', '+faststart'] };
  }

  if (targetContainer === 'webm') {
    const canRemux = webmCompatibleVideo.includes(source.videoCodec) && 
                     webmCompatibleAudio.includes(source.audioCodec);
    return canRemux 
      ? { strategy: 'remux', videoCodec: 'copy', audioCodec: 'copy', extraFlags: [] }
      : { strategy: 'transcode-vp9', videoCodec: 'libvpx-vp9', audioCodec: 'libopus', extraFlags: ['-crf', '30', '-b:v', '0'] };
  }

  throw new Error(`Unsupported target container: ${targetContainer}`);
}

Step 3: Execution Abstraction

The pipeline supports both local execution and cloud API delegation. The cloud path uses asynchronous job submission with polling, preventing event loop saturation.

class TranscodePipeline {
  constructor(private apiKey?: string, private apiEndpoint = 'https://transcode.example.com/v1/jobs') {}

  async execute(sourceUrl: string, targetContainer: 'mp4' | 'webm'): Promise<string> {
    const source = await inspectSource(sourceUrl);
    const config = resolveStrategy(source, targetContainer);

    if (this.apiKey) {
      return this.executeCloud(sourceUrl, targetContainer, config);
    }
    return this.executeLocal(sourceUrl, targetContainer, config);
  }

  private async executeLocal(source: string, target: string, config: PipelineConfig): Promise<string> {
    const output = `output_${Date.now()}.${target}`;
    const flags = [
      '-i', source,
      '-c:v', config.videoCodec,
      '-c:a', config.audioCodec,
      ...config.extraFlags,
      output
    ];
    
    await execAsync(`ffmpeg ${flags.join(' ')}`);
    return output;
  }

  private async executeCloud(source: string, target: string, config: PipelineConfig): Promise<string> {
    const payload = {
      inputs: [{ url: source }],
      outputFormat: target,
      options: [
        { option: '-c:v', argument: config.videoCodec },
        { option: '-c:a', argument: config.audioCodec },
        ...config.extraFlags.map((flag, i) => i % 2 === 0 ? { option: flag, argument: config.extraFlags[i + 1] } : null).filter(Boolean)
      ]
    };

    const res = await fetch(this.apiEndpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    const job = await res.json();
    return this.pollJobStatus(job.id);
  }

  private async pollJobStatus(jobId: string): Promise<string> {
    while (true) {
      const res = await fetch(`${this.apiEndpoint}/${jobId}`, {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      });
      const status = await res.json();
      if (status.status === 'completed') return status.outputUrl;
      if (status.status === 'failed') throw new Error(status.error);
      await new Promise(r => setTimeout(r, 2000));
    }
  }
}

Architecture Rationale

• Stream Inspection First: Decoding media to determine codecs is computationally wasteful. ffprobe reads container headers, delivering accurate codec metadata in milliseconds.
• Strategy Routing Over Hardcoded Commands: Mapping container constraints to strategy objects prevents codec mismatches at runtime. The router enforces WebM's strict codec policy and MP4's faststart requirement automatically.
• Async Job Polling: Cloud transcoding APIs return immediately with a job ID. Blocking the event loop waiting for completion destroys throughput. Exponential backoff polling maintains responsiveness while respecting rate limits.
• Flag Normalization: Converting CLI flags into structured option objects enables consistent API payloads and simplifies testing. The pipeline treats local and cloud execution as interchangeable strategies.

Pitfall Guide

1. Container-Codec Mismatch

Explanation: FFmpeg muxers enforce strict codec whitelists. Wrapping H.264 in WebM or VP9 in MP4 triggers immediate exit code 1 with container-specific rejection messages. Fix: Always validate source codecs against target container specifications before execution. Use the strategy router to enforce compatibility rules programmatically.

2. VP9 CRF Misconfiguration

Explanation: VP9's -crf flag defaults to constrained quality mode when -b:v is omitted. This forces a hidden bitrate ceiling, inflating file sizes by 30–50% without quality improvements. Fix: Pair -crf with -b:v 0 to activate pure constant quality encoding. This removes bitrate constraints and lets the encoder prioritize perceptual quality over size targets.

3. Missing Faststart Optimization

Explanation: MP4 files store metadata (moov atom) at the end of the file by default. Browsers cannot begin playback until the entire file downloads, causing severe UX degradation on slow networks. Fix: Append -movflags +faststart to every MP4 output destined for web delivery. This relocates metadata to the file header, enabling progressive playback.

4. Forced Transcoding on Compatible Streams

Explanation: Re-encoding H.264/AAC content from MKV or MOV to MP4 wastes CPU cycles, introduces generational quality loss, and increases processing time by 200–400%. Fix: Inspect source codecs first. If they match target container requirements, use -c copy to remux. Remuxing is lossless, near-instant, and preserves original quality.

5. Assuming File Extension Equals Codec

Explanation: .mp4 can contain H.264, H.265, or AV1. .webm can contain VP8, VP9, or AV1. Relying on extensions for codec selection leads to unpredictable behavior and compatibility failures. Fix: Never infer codecs from extensions. Always query stream metadata via ffprobe or API response payloads. Explicitly declare codecs in pipeline configurations.

6. Blocking the Event Loop with Synchronous FFmpeg

Explanation: Running FFmpeg via synchronous child processes or unmanaged execSync calls saturates the Node.js event loop, causing request timeouts and memory leaks under concurrent load. Fix: Use asynchronous execution with stream-based progress tracking. For high-throughput environments, delegate to cloud APIs or message queues (RabbitMQ, SQS) with worker pools.

7. Ignoring Audio Stream Compatibility

Explanation: Developers frequently focus on video codecs while neglecting audio. MP4 rejects PCM or FLAC audio without explicit conversion, causing silent failures or truncated outputs. Fix: Validate both video and audio codecs during inspection. Map incompatible audio streams to AAC or Opus during transcoding, and preserve them during remuxing.

Production Bundle

Action Checklist

• Inspect source streams with ffprobe before any conversion attempt
• Route to remux path when source codecs match target container specifications
• Enforce -b:v 0 alongside -crf for VP9 constant quality encoding
• Append -movflags +faststart to all MP4 outputs intended for web delivery
• Validate audio codec compatibility alongside video codec selection
• Implement async job polling with exponential backoff for cloud execution
• Set explicit timeout and retry limits to prevent orphaned transcoding jobs
• Log codec mappings and strategy decisions for audit and debugging

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Web delivery (modern browsers)	WebM + VP9 (CRF 30, -b:v 0)	Superior compression reduces bandwidth and CDN costs	-30% storage, -25% egress
Maximum device compatibility	MP4 + H.264 (CRF 23)	Universal playback across legacy and mobile devices	Baseline compute, +10% size vs VP9
Legacy AVI/DIVX migration	MP4 + H.264 (forced transcode)	Modernizes codec while preserving compatibility	High CPU, one-time cost
Editor exports (ProRes/PCM)	MP4 + H.264/AAC (transcode)	Converts professional codecs to web-ready formats	Moderate CPU, predictable sizing
Same-codec container change	Remux (-c copy) + faststart	Zero quality loss, near-instant processing	Negligible compute, instant delivery

Configuration Template

// transcoding.config.ts
export const CONTAINER_PROFILES = {
  mp4: {
    compatibleVideo: ['h264', 'hevc', 'av1'],
    compatibleAudio: ['aac', 'mp3'],
    defaultVideoCodec: 'libx264',
    defaultAudioCodec: 'aac',
    webOptimization: ['-movflags', '+faststart'],
    crfDefault: '23'
  },
  webm: {
    compatibleVideo: ['vp8', 'vp9', 'av1'],
    compatibleAudio: ['vorbis', 'opus'],
    defaultVideoCodec: 'libvpx-vp9',
    defaultAudioCodec: 'libopus',
    webOptimization: [],
    crfDefault: '30',
    vp9QualityFlag: ['-b:v', '0']
  }
} as const;

export const PIPELINE_LIMITS = {
  maxConcurrentJobs: 10,
  pollIntervalMs: 2000,
  maxPollRetries: 150,
  timeoutMs: 600000,
  memoryLimitMB: 2048
};

Quick Start Guide

1. Install Dependencies: Ensure FFmpeg and ffprobe are available in your environment path. For Node.js projects, install typescript and @types/node.
2. Define Target Profile: Select mp4 or webm based on delivery requirements. Reference the configuration template for codec mappings and optimization flags.
3. Initialize Pipeline: Instantiate TranscodePipeline with optional API credentials for cloud execution. Omit credentials to run locally.
4. Execute Conversion: Call pipeline.execute(sourceUrl, targetContainer). The pipeline automatically inspects streams, selects remux or transcode strategy, and returns the output path or cloud URL.
5. Validate Output: Run ffprobe on the generated file to confirm codec alignment, faststart placement, and audio/video stream integrity before deployment.