Migrating from FFmpeg CLI to node-webcodecs

Stop fighting with filter strings. Start writing actual code.

About These Examples: The patterns below show the conceptual approach for each FFmpeg operation. Helper functions like decodeVideo(), composite(), and frameToJPEG() represent application-specific logic you’d implement. For complete, runnable implementations, see the Cookbook recipes.

Why Migrate?

Debuggable

Breakpoints and stack traces instead of stderr parsing

Testable

Unit test your video logic with Jest/Mocha

Conditional Logic

Use if/else, loops, variables — not filter DSL

Type Safe

TypeScript catches errors before encoding starts

Pattern Comparison

1. Basic Transcoding

FFmpeg CLI
node-webcodecs

ffmpeg -i input.mp4 \
  -c:v libx264 \
  -preset medium \
  -crf 23 \
  output.mp4

Problems:

Can’t inspect frames
No programmatic control
Hard to test

import { VideoDecoder, VideoEncoder, EncodedVideoChunk } from 'node-webcodecs';
import fs from 'fs';

async function transcode(inputFile: string, outputFile: string) {
  const chunks: EncodedVideoChunk[] = [];

  // Decode
  const decoder = new VideoDecoder({
    output: (frame) => {
      // Re-encode each frame
      encoder.encode(frame);
      frame.close();
    },
    error: (err) => console.error(err)
  });

  decoder.configure({
    codec: 'avc1.640028',  // Input codec
    // ... codec details
  });

  // Encode
  const encoder = new VideoEncoder({
    output: (chunk) => chunks.push(chunk),
    error: (err) => console.error(err)
  });

  encoder.configure({
    codec: 'avc1.42E01E',
    width: 1920,
    height: 1080,
    bitrate: 5_000_000  // Equivalent to CRF 23
  });

  // ... decode input, encode output
  await encoder.flush();

  // Save to file
  const output = Buffer.concat(chunks.map(c => {
    const buf = Buffer.alloc(c.byteLength);
    c.copyTo(buf);
    return buf;
  }));
  fs.writeFileSync(outputFile, output);
}

Benefits:

Inspect/modify each frame
Programmatic bitrate control
Error handling with try/catch

2. Text Overlay (Dynamic)

FFmpeg CLI
node-webcodecs

# Static text only
ffmpeg -i input.mp4 \
  -vf "drawtext=text='Hello':x=100:y=100:fontsize=24" \
  output.mp4

Limitations:

Text is fixed at encode time
Can’t use variables
No conditional display
String escaping nightmare for special chars

import { createCanvas } from 'canvas';  // node-canvas

for await (const frame of decodeVideo('input.mp4')) {
  const t = frame.timestamp / 1_000_000;  // seconds

  // Real programming!
  if (t >= 2 && t <= 10) {
    const canvas = frameToCanvas(frame);
    const ctx = canvas.getContext('2d');

    // Dynamic text based on time
    const text = t < 5 ? 'Beginning' : 'Ending';

    ctx.font = '24px Arial';
    ctx.fillStyle = 'white';
    ctx.strokeStyle = 'black';
    ctx.lineWidth = 2;
    ctx.strokeText(text, 100, 100);
    ctx.fillText(text, 100, 100);

    const newFrame = canvasToFrame(canvas, frame.timestamp);
    encoder.encode(newFrame);
    newFrame.close();
  } else {
    // Pass through without text
    encoder.encode(frame);
  }

  frame.close();
}

Benefits:

Conditional text display
Dynamic content (variables, API calls)
Easy to unit test
TypeScript autocomplete for canvas API

3. Watermark Overlay

FFmpeg CLI
node-webcodecs

ffmpeg -i input.mp4 -i logo.png \
  -filter_complex "[0:v][1:v]overlay=x=10:y=10" \
  output.mp4

Limitations:

Fixed position only
Can’t animate
No conditional display

import { ImageDecoder } from 'node-webcodecs';
import sharp from 'sharp';

// Load logo once
const logoImage = await sharp('logo.png')
  .resize(200, 100)
  .toBuffer();

for await (const frame of decodeVideo('input.mp4')) {
  const t = frame.timestamp / 1_000_000;

  // Conditional watermark
  if (shouldShowWatermark(t)) {
    // Animated position
    const x = t < 5 ? 10 : 100 + Math.sin(t) * 50;
    const y = 10;

    // Composite logo onto frame
    const composited = await composite(frame, logoImage, { x, y });
    encoder.encode(composited);
    composited.close();
  } else {
    encoder.encode(frame);
  }

  frame.close();
}

Benefits:

Animated position with Math functions
Conditional display (e.g., only show for premium users)
Can load logo from API
Fade in/out with alpha blending

4. Extract Thumbnails

FFmpeg CLI
node-webcodecs

ffmpeg -i input.mp4 \
  -vf "select='eq(n,0)+eq(n,100)+eq(n,200)'" \
  -vsync 0 \
  thumb%03d.jpg

Limitations:

Frame numbers, not timestamps
Can’t inspect frame content
No quality validation

import sharp from 'sharp';

async function extractThumbnails(
  inputFile: string,
  times: number[] // Seconds
): Promise<Buffer[]> {
  const thumbnails: Buffer[] = [];

  for await (const frame of decodeVideo(inputFile)) {
    const t = frame.timestamp / 1_000_000;

    if (times.includes(Math.floor(t))) {
      // Validate frame quality
      if (!isBlackFrame(frame) && !isFrozenFrame(frame)) {
        const jpg = await frameToJPEG(frame, { quality: 90 });
        thumbnails.push(jpg);
      }
    }

    frame.close();
  }

  return thumbnails;
}

// Smart thumbnail selection
const thumbs = await extractThumbnails('input.mp4', [0, 30, 60, 90]);

Benefits:

Time-based selection
Quality validation (skip black/frozen frames)
Programmatic quality control
Can analyze frame content before saving

5. Resize Video

FFmpeg CLI
node-webcodecs

ffmpeg -i input.mp4 \
  -vf "scale=1280:720" \
  output.mp4

import sharp from 'sharp';

async function resizeVideo(
  inputFile: string,
  width: number,
  height: number
) {
  const encoder = new VideoEncoder({
    output: (chunk) => saveChunk(chunk),
    error: (err) => console.error(err)
  });

  encoder.configure({
    codec: 'avc1.42E01E',
    width,  // New dimensions
    height,
    bitrate: width * height * 3 // Auto-scale bitrate
  });

  for await (const frame of decodeVideo(inputFile)) {
    // Resize frame
    const resized = await resizeFrame(frame, width, height);

    encoder.encode(resized);
    resized.close();
    frame.close();
  }

  await encoder.flush();
}

Benefits:

Auto-scale bitrate based on dimensions
Custom resize algorithms (sharp has 10+ methods)
Preserve aspect ratio with smart cropping

6. Concatenate Videos

FFmpeg CLI
node-webcodecs

# Create file list
echo "file 'video1.mp4'" > list.txt
echo "file 'video2.mp4'" >> list.txt

ffmpeg -f concat -safe 0 -i list.txt \
  -c copy output.mp4

Limitations:

Requires intermediate file
Must have same codec/dimensions
No transition effects

async function concatenateVideos(files: string[]) {
  let currentTimestamp = 0;

  for (const file of files) {
    for await (const frame of decodeVideo(file)) {
      // Renumber timestamps for continuous playback
      const adjustedFrame = new VideoFrame(frame, {
        timestamp: currentTimestamp
      });

      encoder.encode(adjustedFrame);
      adjustedFrame.close();
      frame.close();

      currentTimestamp += frame.duration || 33333;
    }
  }

  await encoder.flush();
}

// With transitions
async function concatenateWithTransitions(files: string[]) {
  for (let i = 0; i < files.length; i++) {
    const nextFile = files[i + 1];

    for await (const frame of decodeVideo(files[i])) {
      const t = frame.timestamp / 1_000_000;
      const isLastSecond = isNearEnd(frame, files[i]);

      if (isLastSecond && nextFile) {
        // Cross-fade with next video
        const nextFrame = await getFrameAt(nextFile, 0);
        const blended = blendFrames(frame, nextFrame, t);
        encoder.encode(blended);
        blended.close();
        nextFrame.close();
      } else {
        encoder.encode(frame);
      }

      frame.close();
    }
  }
}

Benefits:

No intermediate files
Add transition effects
Different codecs/dimensions (auto-convert)
Conditional logic between clips

7. Speed Up/Slow Down

FFmpeg CLI
node-webcodecs

# 2x speed
ffmpeg -i input.mp4 \
  -filter:v "setpts=0.5*PTS" \
  -filter:a "atempo=2.0" \
  output.mp4

Limitations:

Fixed multiplier
Can’t have variable speed
PTS math is confusing

async function changeSpeed(
  inputFile: string,
  speedMultiplier: number
) {
  let outputTimestamp = 0;
  const frameDuration = Math.floor(33333 / speedMultiplier);

  for await (const frame of decodeVideo(inputFile)) {
    const newFrame = new VideoFrame(frame, {
      timestamp: outputTimestamp,
      duration: frameDuration
    });

    encoder.encode(newFrame);
    newFrame.close();
    frame.close();

    outputTimestamp += frameDuration;
  }
}

// Variable speed (timelapse → normal → slow-mo)
async function variableSpeed(inputFile: string) {
  let outputTimestamp = 0;

  for await (const frame of decodeVideo(inputFile)) {
    const t = frame.timestamp / 1_000_000;

    // Different speed in each segment
    const speed =
      t < 10 ? 4.0 :  // 4x timelapse
      t < 20 ? 1.0 :  // Normal
      0.5;            // 0.5x slow motion

    const duration = Math.floor(33333 / speed);

    const newFrame = new VideoFrame(frame, {
      timestamp: outputTimestamp,
      duration
    });

    encoder.encode(newFrame);
    newFrame.close();
    frame.close();

    outputTimestamp += duration;
  }
}

Benefits:

Variable speed throughout video
Easy timestamp math
Frame-accurate control

8. Extract Audio

FFmpeg CLI
node-webcodecs

ffmpeg -i input.mp4 \
  -vn -acodec copy \
  output.aac

import { AudioDecoder, AudioEncoder } from 'node-webcodecs';

async function extractAudio(inputFile: string, outputFile: string) {
  const chunks: EncodedAudioChunk[] = [];

  const encoder = new AudioEncoder({
    output: (chunk) => chunks.push(chunk),
    error: (err) => console.error(err)
  });

  encoder.configure({
    codec: 'mp4a.40.2',  // AAC
    sampleRate: 48000,
    numberOfChannels: 2,
    bitrate: 128000
  });

  for await (const audio of decodeAudio(inputFile)) {
    // Optional: analyze/modify audio
    if (hasSilence(audio)) {
      // Skip silent segments
      audio.close();
      continue;
    }

    encoder.encode(audio);
    audio.close();
  }

  await encoder.flush();

  // Save to file
  const output = Buffer.concat(chunks.map(c => {
    const buf = Buffer.alloc(c.byteLength);
    c.copyTo(buf);
    return buf;
  }));
  fs.writeFileSync(outputFile, output);
}

Benefits:

Skip silent segments
Analyze audio levels
Apply filters/effects
Conditional encoding

9. Create Slideshow from Images

FFmpeg CLI
node-webcodecs

ffmpeg -framerate 1/3 \
  -pattern_type glob -i '*.jpg' \
  -c:v libx264 \
  output.mp4

Limitations:

All images same duration
No transitions
Glob patterns can be unreliable

import { ImageDecoder, VideoFrame } from 'node-webcodecs';
import sharp from 'sharp';

interface Slide {
  image: string;
  duration: number;  // seconds
  transition?: 'fade' | 'slide' | 'none';
}

async function createSlideshow(slides: Slide[]) {
  const fps = 30;
  const frameDuration = Math.floor(1_000_000 / fps);
  let timestamp = 0;

  for (let i = 0; i < slides.length; i++) {
    const slide = slides[i];
    const nextSlide = slides[i + 1];

    // Load image
    const imageBuffer = await sharp(slide.image)
      .resize(1920, 1080, { fit: 'contain' })
      .toBuffer();

    const totalFrames = Math.floor(slide.duration * fps);

    for (let f = 0; f < totalFrames; f++) {
      let frameData = imageBuffer;

      // Transition effect
      if (nextSlide && f > totalFrames - fps) {
        // Last second: transition to next slide
        const progress = (f - (totalFrames - fps)) / fps;
        const nextImage = await sharp(nextSlide.image)
          .resize(1920, 1080, { fit: 'contain' })
          .toBuffer();

        frameData = await blendImages(
          imageBuffer,
          nextImage,
          progress
        );
      }

      const frame = new VideoFrame(frameData, {
        format: 'RGBA',
        codedWidth: 1920,
        codedHeight: 1080,
        timestamp,
        duration: frameDuration
      });

      encoder.encode(frame, { keyFrame: f === 0 });
      frame.close();

      timestamp += frameDuration;
    }
  }

  await encoder.flush();
}

Benefits:

Variable duration per slide
Smooth transitions
Programmatic image selection (from DB, API)
Custom effects

10. Live Stream Recording

FFmpeg CLI
node-webcodecs

ffmpeg -i rtmp://stream.url/live \
  -c copy \
  output.mp4

Limitations:

Can’t process frames
No real-time analysis
Can’t create highlights

import { VideoDecoder, VideoEncoder } from 'node-webcodecs';

async function recordWithHighlights(streamUrl: string) {
  const allFrames: VideoFrame[] = [];
  const highlights: { start: number; end: number }[] = [];

  for await (const frame of decodeStream(streamUrl)) {
    const t = frame.timestamp / 1_000_000;

    // Real-time analysis
    const action = await detectAction(frame); // AI model

    if (action.score > 0.8) {
      // Highlight detected!
      highlights.push({
        start: t - 5,  // 5 seconds before
        end: t + 5     // 5 seconds after
      });
    }

    // Record full stream
    mainEncoder.encode(frame);

    // Also create highlight reel
    if (isInHighlightRange(t, highlights)) {
      highlightEncoder.encode(frame);
    }

    frame.close();
  }

  // Result: Full recording + auto-generated highlight reel
  await mainEncoder.flush();
  await highlightEncoder.flush();
}

Benefits:

Real-time frame analysis
Auto-generate highlights
Multiple outputs simultaneously
Conditional recording based on content

Migration Checklist

Install node-webcodecs

npm install node-webcodecs

Identify your FFmpeg patterns

List all your current FFmpeg commands and their purposes

Map to WebCodecs APIs

Encoding → VideoEncoder
Decoding → VideoDecoder
Filters → Canvas API or image processing libs

Refactor with real code

Replace filter strings with JavaScript/TypeScript logic

Add tests

Unit test your video logic with Jest

Add type safety

Use TypeScript for compile-time error checking

##Advantages Summary

Feature	FFmpeg CLI	node-webcodecs
Debugging	stderr parsing	Breakpoints, stack traces
Conditionals	❌ Not possible	✅ if/else, switch
Variables	Limited ENV vars	✅ Full JavaScript
Testing	Shell scripts	✅ Jest/Mocha unit tests
Type Safety	❌ None	✅ TypeScript
Frame Access	❌ No	✅ Every frame
API Integration	❌ Hard	✅ Easy (fetch, DB)
Error Handling	Exit codes	try/catch
IDE Support	❌ None	✅ Autocomplete

Next Steps

API Reference

Complete VideoEncoder docs

Cookbook

More real-world recipes

Hardware Acceleration

8-15x faster encoding

Examples

Working code examples

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

Migrating from FFmpeg CLI

Migrating from FFmpeg CLI to node-webcodecs

Why Migrate?

Debuggable

Testable

Conditional Logic

Type Safe

Pattern Comparison

1. Basic Transcoding

2. Text Overlay (Dynamic)

3. Watermark Overlay

4. Extract Thumbnails

5. Resize Video

6. Concatenate Videos

7. Speed Up/Slow Down

8. Extract Audio

9. Create Slideshow from Images

10. Live Stream Recording

Migration Checklist

Next Steps

API Reference

Cookbook

Hardware Acceleration

Examples

​Migrating from FFmpeg CLI to node-webcodecs

​Why Migrate?

Debuggable

Testable

Conditional Logic

Type Safe

​Pattern Comparison

​1. Basic Transcoding

​2. Text Overlay (Dynamic)

​3. Watermark Overlay

​4. Extract Thumbnails

​5. Resize Video

​6. Concatenate Videos

​7. Speed Up/Slow Down

​8. Extract Audio

​9. Create Slideshow from Images

​10. Live Stream Recording

​Migration Checklist

​Next Steps

API Reference

Cookbook

Hardware Acceleration

Examples

Migrating from FFmpeg CLI to node-webcodecs

Why Migrate?

Pattern Comparison

1. Basic Transcoding

2. Text Overlay (Dynamic)

3. Watermark Overlay

4. Extract Thumbnails

5. Resize Video

6. Concatenate Videos

7. Speed Up/Slow Down

8. Extract Audio

9. Create Slideshow from Images

10. Live Stream Recording

Migration Checklist

Next Steps