DEV Community: Javid Jamae

FFmpeg on Cloudflare Workers: Why It Fails (And the Fix)

Javid Jamae — Wed, 22 Jul 2026 10:22:59 +0000

Originally published at ffmpeg-micro.com

Your FFmpeg pipeline works on localhost. You deploy to Cloudflare Workers, trigger a transcode, and the whole thing crashes before it starts. No output file. No error you can Google. Just a cold rejection from a runtime that was never going to run your binary.

This isn't a configuration problem. Cloudflare Workers are V8 isolates, not containers. FFmpeg will never run directly inside one, and no amount of bundler tweaking will change that.

Why FFmpeg won't run on Cloudflare Workers

Most developers try three approaches before giving up. All three fail for different architectural reasons.

V8 isolates can't spawn subprocesses

Cloudflare Workers don't run in containers or virtual machines. They run in V8 isolates, the same engine that powers Chrome's JavaScript execution. There's no operating system layer underneath. No filesystem. No shell.

That means no child_process.exec(), no spawn(), no way to invoke a binary. FFmpeg is a compiled binary that expects to be called as a subprocess. Workers literally cannot do this. The APIs don't exist in the runtime.

If you've used FFmpeg with Node.js before, you're probably calling it through child_process or a wrapper like fluent-ffmpeg. None of that code will even parse on Workers, let alone execute. You'll get build errors before your Worker ever deploys.

ffmpeg.wasm hits the bundle size limit

The natural next thought: compile FFmpeg to WebAssembly and run it in the Worker. That's what ffmpeg.wasm does in the browser, and Workers support WASM.

But Cloudflare enforces a 10 MB compressed bundle size limit for Workers (25 MB on the paid plan with some configurations). The ffmpeg.wasm core binary alone is roughly 25 MB uncompressed. Even aggressively stripped builds that remove codecs you don't need still land around 15-20 MB. You blow past the limit before adding a single line of your own code.

Some developers try to lazy-load the WASM binary from R2 or an external URL at runtime. That leads directly to the third problem.

workerd blocks dynamic WASM compilation

Cloudflare's runtime (workerd) does not allow dynamic WASM compilation. You can't call WebAssembly.compile() or WebAssembly.instantiate() with a buffer fetched at runtime. The WASM module must be pre-compiled and included in your Worker bundle at deploy time.

This is a deliberate security decision. Allowing arbitrary WASM compilation at runtime would break the isolation guarantees that make Workers safe to run on shared infrastructure.

So you can't fetch the ffmpeg.wasm binary from R2, compile it on the fly, and run it. The module would need to be bundled, which circles back to the size limit. There's no escape hatch here.

The fix: call an FFmpeg API from your Worker

Workers can't run FFmpeg, but they're excellent at one thing: making HTTP requests. Fast, globally distributed HTTP requests with sub-millisecond cold starts.

Instead of fighting the runtime, use the Worker for what it's good at. Accept the upload or webhook trigger, make a single fetch() call to FFmpeg Micro to handle the transcode, and return the result. Your Worker stays small, fast, and within every Cloudflare limit.

This is the same pattern that works for FFmpeg on AWS Lambda and FFmpeg on Heroku. The platform handles routing and triggers. The transcoding happens on infrastructure built for it.

A single API call replaces the entire ffmpeg.wasm experiment:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://your-r2-bucket.r2.dev/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "28"}
    ]
  }'

Or use a preset if you don't want to think about FFmpeg flags:

{
  "inputs": [{"url": "https://your-r2-bucket.r2.dev/input.mp4"}],
  "outputFormat": "mp4",
  "preset": {"quality": "high", "resolution": "1080p"}
}

Working example: compress-on-upload Worker

This Worker receives a video URL (for example, from an R2 upload event or a webhook), sends it to FFmpeg Micro for compression, and returns the download URL for the processed file.

export interface Env {
  FFMPEG_MICRO_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const { videoUrl } = await request.json<{ videoUrl: string }>();

    if (!videoUrl) {
      return new Response(
        JSON.stringify({ error: "videoUrl is required" }),
        { status: 400, headers: { "Content-Type": "application/json" } }
      );
    }

    const createResponse = await fetch(
      "https://api.ffmpeg-micro.com/v1/transcodes",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${env.FFMPEG_MICRO_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          inputs: [{ url: videoUrl }],
          outputFormat: "mp4",
          options: [
            { option: "-c:v", argument: "libx264" },
            { option: "-crf", argument: "28" },
            { option: "-preset", argument: "fast" },
          ],
        }),
      }
    );

    if (!createResponse.ok) {
      const error = await createResponse.text();
      return new Response(
        JSON.stringify({ error: "Transcode creation failed", details: error }),
        { status: 502, headers: { "Content-Type": "application/json" } }
      );
    }

    const job = await createResponse.json<{ id: string; status: string }>();

    const jobId = job.id;
    let status = job.status;
    let attempts = 0;
    const maxAttempts = 60;

    while (status !== "completed" && status !== "failed" && attempts < maxAttempts) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      const pollResponse = await fetch(
        `https://api.ffmpeg-micro.com/v1/transcodes/${jobId}`,
        {
          headers: {
            Authorization: `Bearer ${env.FFMPEG_MICRO_API_KEY}`,
          },
        }
      );
      const pollData = await pollResponse.json<{ status: string }>();
      status = pollData.status;
      attempts++;
    }

    if (status === "failed") {
      return new Response(
        JSON.stringify({ error: "Transcode failed", jobId }),
        { status: 500, headers: { "Content-Type": "application/json" } }
      );
    }

    if (status !== "completed") {
      return new Response(
        JSON.stringify({ error: "Transcode timed out", jobId }),
        { status: 504, headers: { "Content-Type": "application/json" } }
      );
    }

    const downloadResponse = await fetch(
      `https://api.ffmpeg-micro.com/v1/transcodes/${jobId}/download?url=true`,
      {
        headers: {
          Authorization: `Bearer ${env.FFMPEG_MICRO_API_KEY}`,
        },
      }
    );

    const downloadData = await downloadResponse.json<{ url: string }>();

    return new Response(
      JSON.stringify({
        status: "completed",
        jobId,
        downloadUrl: downloadData.url,
      }),
      { status: 200, headers: { "Content-Type": "application/json" } }
    );
  },
};

Set your API key as a Workers secret:

npx wrangler secret put FFMPEG_MICRO_API_KEY

Then deploy:

npx wrangler deploy

Your Worker stays under 1 MB. The video processing runs on dedicated infrastructure with no bundle limits, no WASM restrictions, and no subprocess constraints.

Common pitfalls

Polling too aggressively. The example above polls every 2 seconds, which is fine for most video lengths. For large files (over 1 GB), increase the interval to 5-10 seconds to avoid unnecessary API calls.

Hitting the Worker CPU time limit. Free-tier Workers have a 10ms CPU time limit per request. The polling loop uses wall-clock time (waiting on fetch), not CPU time, so it won't trigger this limit. But if you add heavy request parsing or data transformation, you could hit it. Paid plans get 30 seconds of CPU time.

Forgetting the Worker duration limit. Workers on the free plan can run for up to 30 seconds total. The polling loop in the example could exceed this for longer videos. On the paid plan ($5/month), Workers can run for up to 30 minutes, which covers most transcoding jobs. For very long encodes, consider using a Cloudflare Queue or Durable Object to handle the polling asynchronously.

Passing R2 private URLs. If your video is in a private R2 bucket, the FFmpeg Micro API can't fetch it directly. Generate a presigned R2 URL with a short expiry and pass that as the input URL instead.

You can get an FFmpeg Micro API key in under a minute at ffmpeg-micro.com.

FAQ

Can I run FFmpeg directly on Cloudflare Workers?

No. Cloudflare Workers run in V8 isolates, not containers. There's no subprocess execution, no filesystem, and no way to invoke compiled binaries. FFmpeg requires all three. The only way to process video from a Worker is to call an external API like FFmpeg Micro.

Will ffmpeg.wasm work on Cloudflare Workers?

No. The ffmpeg.wasm core binary exceeds Cloudflare's 10 MB compressed bundle size limit, and the Workers runtime (workerd) blocks dynamic WASM compilation at runtime. You can't bundle it and you can't load it on the fly. Both paths are dead ends.

What is the Cloudflare Workers bundle size limit?

Cloudflare enforces a 10 MB compressed limit for Worker bundles on the free plan and most paid configurations. Some enterprise plans allow up to 25 MB. The ffmpeg.wasm binary alone is roughly 25 MB uncompressed, which exceeds both tiers after you add your application code.

How do I process video uploads stored in Cloudflare R2?

Generate a presigned URL for the R2 object and pass it to the FFmpeg Micro API as the input URL. Your Worker handles the R2 presigning and the API call. The transcode runs externally, and you get back a download URL for the processed file. Your R2 object never needs to be publicly accessible.

Is there a Cloudflare-native alternative to FFmpeg for video processing?

Cloudflare Stream handles video hosting and adaptive bitrate delivery, but it's not a general-purpose transcoding tool. You can't pass custom FFmpeg flags, extract audio tracks, generate thumbnails at specific timestamps, or apply filters like text overlays and cropping. For anything beyond basic video hosting, you need an FFmpeg API.

ffprobe: How to Inspect Video Metadata Before Processing

Javid Jamae — Wed, 22 Jul 2026 10:22:58 +0000

Originally published at ffmpeg-micro.com

Every video file lies to you a little. The container says MP4, but the codec might be MPEG-2. The filename says 1080p, but the actual resolution is 720x480. Running ffprobe before you process a file tells you exactly what you're working with. It saves you from wasting compute time and API credits on files that will fail, produce garbage output, or need completely different settings than you assumed.

What ffprobe Does

ffprobe is a companion tool that ships with every FFmpeg installation. It reads a media file's container and streams without decoding the actual video frames, which makes it fast. You get back structured metadata: codecs, resolution, duration, bitrate, audio channels, frame rate, and more.

The command you'll use 90% of the time looks like this:

ffprobe -v quiet -print_format json -show_streams -show_format input.mp4

Breaking that down:

-v quiet suppresses the banner and warnings, so you only get clean data
-print_format json gives you machine-readable JSON instead of the default key=value dump
-show_streams returns details for each stream (video, audio, subtitle tracks)
-show_format returns container-level info like duration, bitrate, and format name

You can also point ffprobe at a URL instead of a local file. It'll pull just enough bytes to read the headers.

Reading the JSON Output

The JSON output from ffprobe has two top-level keys: streams and format. The streams array contains one object per track in the file.

{
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "r_frame_rate": "30/1",
      "duration": "124.500000",
      "bit_rate": "5000000"
    },
    {
      "index": 1,
      "codec_name": "aac",
      "codec_type": "audio",
      "channels": 2,
      "sample_rate": "44100",
      "bit_rate": "128000"
    }
  ],
  "format": {
    "filename": "input.mp4",
    "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration": "124.500000",
    "size": "78125000",
    "bit_rate": "5017600"
  }
}

The fields that matter most for pre-processing decisions:

Field	Where	What it tells you
`codec_name`	streams	Video codec (h264, hevc, vp9, av1)
`width` / `height`	streams	Actual pixel dimensions
`duration`	format	Total length in seconds
`bit_rate`	format	Overall bitrate in bits/sec
`channels`	streams (audio)	Mono (1), stereo (2), surround (6)
`r_frame_rate`	streams (video)	Frame rate as a fraction

Pre-Processing Checks That Save You Money

I've seen developers skip inspection and send files straight to a transcoding API. Then they're surprised when jobs fail or produce weird results. A few checks with ffprobe catch the most common problems.

1. Codec validation

Not every codec is supported by every processing pipeline. If someone uploads a ProRes file but your workflow expects H.264, you want to know before you spend credits. For a full rundown of format handling, check out our guide on converting video formats with FFmpeg.

VIDEO_CODEC=$(ffprobe -v quiet -print_format json -show_streams input.mp4 | jq -r '.streams[] | select(.codec_type=="video") | .codec_name')

if [[ "$VIDEO_CODEC" != "h264" && "$VIDEO_CODEC" != "hevc" ]]; then
  echo "Unsupported codec: $VIDEO_CODEC"
  exit 1
fi

2. Resolution check

If you're targeting 1080p output and the input is already 640x360, upscaling won't add quality. It just wastes processing time and increases file size. You might want to skip the transcode entirely or warn the user. Our FFmpeg scale filter guide covers the details of resizing while preserving aspect ratio.

HEIGHT=$(ffprobe -v quiet -print_format json -show_streams input.mp4 | jq -r '.streams[] | select(.codec_type=="video") | .height')

if [[ "$HEIGHT" -lt 720 ]]; then
  echo "Input is only ${HEIGHT}p. Skipping upscale."
fi

3. Duration sanity check

A 6-hour video will take a long time and cost real money to transcode. And a 0-second file means something is corrupt. Set boundaries.

DURATION=$(ffprobe -v quiet -print_format json -show_format input.mp4 | jq -r '.format.duration')
SECONDS=${DURATION%.*}

if [[ "$SECONDS" -eq 0 ]]; then
  echo "File appears corrupt (0 duration)"
  exit 1
elif [[ "$SECONDS" -gt 3600 ]]; then
  echo "File is over 1 hour. Consider splitting first."
fi

If you do need to split long files, our guide to splitting video into segments covers three different methods.

4. Missing audio check

Some workflows assume audio exists. If you're adding subtitles or normalizing loudness, a video-only file will cause failures downstream.

AUDIO_STREAMS=$(ffprobe -v quiet -print_format json -show_streams input.mp4 | jq '[.streams[] | select(.codec_type=="audio")] | length')

if [[ "$AUDIO_STREAMS" -eq 0 ]]; then
  echo "No audio track found"
fi

Using ffprobe Output to Pick API Settings

The real payoff comes when you use ffprobe data to dynamically set your transcoding parameters. Instead of hardcoding "1080p, high quality" for every file, you can make smart choices.

HEIGHT=$(ffprobe -v quiet -print_format json -show_streams input.mp4 | jq -r '.streams[] | select(.codec_type=="video") | .height')

if [[ "$HEIGHT" -ge 2160 ]]; then
  RESOLUTION="1080p"
  QUALITY="high"
elif [[ "$HEIGHT" -ge 1080 ]]; then
  RESOLUTION="1080p"
  QUALITY="medium"
else
  RESOLUTION="${HEIGHT}p"
  QUALITY="medium"
fi

Then pass those values to the FFmpeg Micro API:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"inputs\": [{\"url\": \"https://example.com/video.mp4\"}],
    \"outputFormat\": \"mp4\",
    \"preset\": {\"quality\": \"$QUALITY\", \"resolution\": \"$RESOLUTION\"}
  }"

This pattern is especially useful for batch processing where you're handling hundreds of files with different properties. A 4K file gets downscaled to 1080p. A 720p file stays at 720p. A corrupt file gets skipped entirely. No wasted API calls.

Common ffprobe Pitfalls

A few things catch developers off guard.

Duration lives in two places. The stream-level duration and the format-level duration can differ. Some containers don't store duration in the stream metadata at all. Always prefer format.duration for the total file length.

Variable frame rate breaks assumptions. Screen recordings and phone videos often use variable frame rate (VFR). ffprobe reports the average or the container-declared rate, which might not match what you actually see. If frame-accurate processing matters, check the r_frame_rate vs avg_frame_rate fields.

codec_name isn't always what you expect. An MP4 file can contain nearly any codec. I've seen MP4 containers with MJPEG video streams (from older cameras) and even raw PCM audio. Don't trust the file extension. Trust the codec_name from ffprobe.

Remote URLs need accessible headers. When probing a URL, ffprobe sends a standard HTTP GET. If the server requires auth headers, you'll need to pass them with -headers. See our FFmpeg auth headers guide for the syntax.

Start Inspecting, Then Process

Running ffprobe before processing is a two-minute addition to any video pipeline that prevents the most frustrating failures. Once you know what's in the file, send it to FFmpeg Micro to process. One API call, no FFmpeg install, no server to maintain.

FAQ

How do I get ffprobe output in JSON format?

Use the -print_format json flag combined with -show_streams and -show_format. The full command is ffprobe -v quiet -print_format json -show_streams -show_format input.mp4. This returns a structured JSON object with all stream and container metadata.

Can ffprobe read a video from a URL without downloading the whole file?

Yes. ffprobe only reads the container headers and metadata, not the full file. You can pass a URL directly: ffprobe -v quiet -print_format json -show_streams https://example.com/video.mp4. It pulls just enough data to identify codecs, resolution, duration, and stream info.

What's the difference between ffprobe and ffmpeg for reading metadata?

ffmpeg can show metadata too (just run ffmpeg -i input.mp4 with no output), but ffprobe is purpose-built for inspection. It gives you structured output in JSON, XML, CSV, or flat formats. ffmpeg's metadata dump is unstructured text meant for humans, not scripts.

Does ffprobe work with audio files?

ffprobe works with any format FFmpeg supports, including MP3, WAV, FLAC, AAC, and OGG. The output structure is the same. You'll get stream-level info for codec, sample rate, channels, and bitrate.

How do I check if a video file is corrupt using ffprobe?

A quick corruption check is to look for a duration of 0 or a missing video stream. For deeper validation, run ffprobe -v error input.mp4, which prints only error-level messages. If it outputs anything, the file has problems. For a full frame-by-frame check, you'll need ffmpeg -v error -i input.mp4 -f null -, which actually decodes every frame.

FFmpeg on AWS Lambda: The Layer-Size and Timeout Problem

Javid Jamae — Tue, 21 Jul 2026 10:16:32 +0000

Originally published at ffmpeg-micro.com

You're building a serverless video pipeline. You add an FFmpeg static binary as a Lambda layer, wire up an S3 trigger, deploy, and immediately hit a wall. The binary is too big, the storage is too small, and the timeout isn't long enough. I've watched this play out on dozens of projects, and the failure mode is always the same.

The 250 MB Layer Limit

AWS Lambda layers max out at 250 MB unzipped. That's a hard limit, and FFmpeg pushes right up against it.

A typical FFmpeg static build compresses to around 70-80 MB as a zip file. Unzipped, with common codecs included, you're looking at 200 MB or more. That sounds like it fits, but remember: your function code, runtime, and all layers share that 250 MB budget. Once you add the AWS SDK, a couple of Node.js dependencies, and your handler code, you're over.

The usual fix is stripping codecs. You rebuild FFmpeg with only the encoders you need. But the codecs you "don't need" have a way of becoming the codecs you do need. Drop libx265 and someone requests HEVC output. Drop libvpx and a client wants WebM. You end up maintaining a custom FFmpeg build just to stay under a Lambda limit.

A stripped FFmpeg binary with only libx264 still runs about 40-50 MB unzipped. Add libx265 and libvpx, and you're back above 150 MB before your function code enters the picture.

The /tmp Storage Cap

Lambda gives you 512 MB of ephemeral storage in /tmp by default. You can bump this to 10 GB, but you pay for it ($0.0000000309 per GB-second). And you'll need every byte.

FFmpeg doesn't just read an input and write an output. It creates intermediate temp files during encoding. So for a single transcode, you need space for the input file, the output file, and FFmpeg's working files. A 500 MB source video blows through the default 512 MB allocation before the encode even starts. Even with the 10 GB option, a 4K video file can eat that up fast when you factor in temp data.

The 15-Minute Timeout

Lambda functions have a hard ceiling of 15 minutes. You can't extend it, negotiate it, or work around it.

Encoding a 10-minute 1080p video to H.265 takes 20-30 minutes on Lambda's shared vCPUs. That's not a worst case. That's a normal case. Lambda doesn't give you dedicated CPU cores. You're on shared infrastructure, and encoding performance varies between invocations. A job that finishes in 12 minutes on one run might take 18 on the next.

For audio extraction or format remuxing (copying streams without re-encoding), 15 minutes is usually fine. For actual transcoding with compute-intensive codecs, it's not.

The Cold Start Tax

When you outgrow layers and switch to Docker images on Amazon ECR (the standard workaround for binaries larger than 250 MB), you trade the layer-size problem for a cold start problem.

Lambda container images can be up to 10 GB, which solves the binary size issue. But cold starts for container-based Lambda functions run 5-15 seconds, sometimes longer. If your video pipeline is event-driven, processing uploads as they arrive, those cold starts add real latency. A user uploads a short clip expecting a fast turnaround, and the first 10 seconds are just Lambda pulling your container image.

When Lambda + FFmpeg Actually Works

I don't want to pretend Lambda is never the right call. For small, simple jobs, it works fine.

Extracting a thumbnail from a video? Lambda handles that in seconds. Pulling the audio track from an MP4? No problem. Trimming a sub-30-second clip or converting between container formats without re-encoding? All good.

A minimal Lambda handler that extracts a thumbnail using a pre-installed FFmpeg layer:

ffmpeg -i /tmp/input.mp4 -ss 00:00:05 -frames:v 1 /tmp/thumbnail.jpg

If your workload fits this profile (small files, simple operations, no heavy encoding), Lambda plus an FFmpeg layer is a reasonable setup. The trouble starts when the jobs get bigger.

The API Alternative: Call FFmpeg Micro from Your Lambda

Instead of cramming FFmpeg into Lambda, you can keep your Lambda function small and offload the encoding to a dedicated API. Your Lambda becomes a thin orchestration layer. No binary, no layer, no /tmp pressure.

FFmpeg Micro is a cloud API that runs FFmpeg commands over HTTP. You send a POST request with your inputs and options, and get back processed video. No binary to install, no server to manage. Get a free API key at ffmpeg-micro.com.

A TypeScript Lambda handler that starts a transcode job through the FFmpeg Micro API:

import { Handler } from 'aws-lambda';

const FFMPEG_MICRO_KEY = process.env.FFMPEG_MICRO_API_KEY;

export const handler: Handler = async (event) => {
  const { videoUrl, outputFormat = 'mp4' } = event;

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

  const job = await response.json();
  return { jobId: job.id, status: job.status };
};

This Lambda function is a few kilobytes. No layer. No Docker image. No cold start penalty beyond the standard Node.js runtime. The actual encoding happens on FFmpeg Micro's infrastructure, which means no 15-minute timeout concern and no /tmp storage juggling.

You fire the request, get a job ID back, and poll GET /v1/transcodes/{id} for completion. The finished job includes an outputUrl where you can grab the processed file. If you want to avoid polling from Lambda, trigger a second Lambda from a webhook or a Step Functions wait state.

We broke down the full AWS cost picture in FFmpeg on AWS: Cost Breakdown. For a broader comparison, see Self-Hosting FFmpeg vs API.

FAQ

Can FFmpeg run inside AWS Lambda?

Yes, but with significant constraints. AWS Lambda's 250 MB unzipped layer limit, 512 MB default /tmp storage, and 15-minute execution ceiling make it viable only for lightweight FFmpeg tasks like thumbnail extraction, audio stripping, or short clip trimming. Heavy transcoding jobs will hit timeout or storage limits.

How do I add FFmpeg to an AWS Lambda layer?

You package a statically compiled FFmpeg binary into a zip file and upload it as a Lambda layer. The binary must be compiled for Amazon Linux 2 (x86_64 or arm64). Place it in the bin/ directory of your layer zip so it's available at /opt/bin/ffmpeg in your function. Keep total unzipped size under 250 MB across all layers.

What's the maximum video size I can process with FFmpeg on Lambda?

With default settings, you're limited to roughly 150-200 MB input files because /tmp (512 MB) must hold the input, output, and FFmpeg's temp files. You can increase /tmp to 10 GB for additional cost, which raises the practical limit, but the 15-minute timeout becomes the bottleneck for larger files that require re-encoding.

Is there a serverless way to run FFmpeg without Lambda limits?

Calling a managed transcoding API like FFmpeg Micro from your Lambda function removes the binary size, storage, and timeout constraints. Your Lambda stays small and fast while the encoding runs on dedicated infrastructure. AWS also offers Elastic Transcoder and MediaConvert, though both use proprietary job configs rather than standard FFmpeg commands.

How long does FFmpeg take to encode video on Lambda?

On Lambda's shared vCPUs, encoding a 10-minute 1080p video to H.264 typically takes 10-20 minutes. H.265 encoding runs 20-30 minutes for the same input. Performance varies between invocations because CPU resources are shared. Operations that don't re-encode (remuxing, stream copying) finish in seconds.

FFmpeg drawtext Filter: Complete Guide to Text Overlays

Javid Jamae — Tue, 21 Jul 2026 10:15:52 +0000

Originally published at ffmpeg-micro.com

The drawtext filter is the most parameter-heavy filter in FFmpeg. The official documentation reads like a specification sheet, not a guide. I've spent enough time decoding it that I figured I'd write the reference I wish existed.

If you just need to add text quickly, see our step-by-step guide. This post is the full parameter breakdown for when you need precise control.

Basic drawtext Syntax

The minimum viable drawtext command needs just a text string:

ffmpeg -i input.mp4 -vf "drawtext=text='Hello World'" output.mp4

That renders white text in the top-left corner using FFmpeg's built-in font. Not useful on its own, but it confirms the filter works before you start layering on parameters.

Every parameter after that is a colon-separated key-value pair inside the filter string. The general pattern looks like this:

ffmpeg -i input.mp4 -vf "drawtext=text='Hello World':fontsize=48:fontcolor=white:x=100:y=100" output.mp4

Font Control: fontfile, fontname, fontsize, fontcolor

You've got two ways to specify a font. fontfile takes a path to a .ttf or .otf file on disk. fontname takes the name of a font installed on the system and requires that FFmpeg was built with fontconfig support.

# Using a font file path
drawtext=fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:text='Title'

# Using a system font name (requires fontconfig)
drawtext=fontname='Arial':text='Title'

I almost always use fontfile because it's portable. If you're running FFmpeg in Docker or on a remote server, you can't assume system fonts are available.

fontsize accepts an integer in pixels. The default is 16, which is tiny on most video resolutions. For 1080p, I usually start around 48 and go up from there.

fontcolor accepts named colors (white, red, yellow) or hex values. Hex values in drawtext use the format 0xRRGGBB or 0xRRGGBBAA where AA is alpha. Note that this is not the CSS #RRGGBB format.

drawtext=text='Visible':fontcolor=white
drawtext=text='Semi-transparent':fontcolor=0xFFFFFF80
drawtext=text='Named color':fontcolor=yellow

The full list of named colors comes from FFmpeg's libavutil color table, which matches the X11 color set.

Position: x and y Expressions

The x and y parameters control where the text appears, and they accept math expressions, not just static numbers. This is where drawtext gets interesting.

FFmpeg exposes several variables you can use in these expressions:

w and h are the video width and height
text_w and text_h are the rendered width and height of the text
n is the current frame number
t is the timestamp in seconds

Center the text on screen:

x=(w-text_w)/2:y=(h-text_h)/2

Bottom-center with a margin:

x=(w-text_w)/2:y=h-text_h-40

Top-right corner with padding:

x=w-text_w-20:y=20

The expression (w-text_w)/2 is the standard centering formula. It takes the video width, subtracts the text width, and divides by two. Same logic applies vertically with h and text_h.

You can also animate position. Scrolling text from right to left:

x=w-t*100:y=h-text_h-20

That moves the text 100 pixels per second toward the left edge.

Styling: box, border, and shadow

Plain white text on video is hard to read. The box, borderw, and shadow parameters fix that.

Box background draws a filled rectangle behind the text. Set box=1 to enable it, then control the color with boxcolor.

drawtext=text='Breaking News':box=1:boxcolor=black@0.6:boxborderw=10

The @0.6 syntax sets opacity. boxborderw adds padding between the text and the box edge, in pixels. You can also specify per-side padding with boxborderw=10|20|10|20 (top, right, bottom, left).

Text border draws an outline around each character. Useful for legibility without a box.

drawtext=text='Outlined':borderw=2:bordercolor=black

Shadow offsets a shadow copy of the text.

drawtext=text='Shadow':shadowx=3:shadowy=3:shadowcolor=black@0.5

I combine border and shadow often. A 1px black border with a subtle shadow makes text readable on almost any background.

Dynamic Text with Expansion Expressions

Set expansion=normal (it's actually the default) to use %{...} expressions inside your text string. These evaluate per-frame.

Burn the timestamp into the video:

drawtext=text='%{pts\:hms}':fontsize=24:fontcolor=white:x=10:y=10

The %{pts\:hms} expression renders the presentation timestamp in HH:MM:SS format. Note the backslash-escaped colon, which is necessary because colons are the parameter delimiter.

Show frame number:

drawtext=text='Frame %{n}':fontsize=20:x=10:y=10

Show local clock time:

drawtext=text='%{localtime\:%Y-%m-%d %H\\\:%M\\\:%S}':fontsize=24:x=10:y=10

The escaping in localtime gets ugly because strftime format codes also use colons and percent signs. Triple backslashes before colons inside the strftime pattern is the standard workaround.

You can also use the enable parameter to show text only during a specific time range:

drawtext=text='Intro':enable='between(t,0,5)':fontsize=48:x=(w-text_w)/2:y=(h-text_h)/2

That displays "Intro" only during the first five seconds.

Text Overlays via FFmpeg Micro API

If you don't want to manage FFmpeg binaries, FFmpeg Micro runs these commands for you over HTTP.

The @text-overlay virtual option handles font loading, line wrapping, and positioning for you:

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "mp4",
  "options": [
    {
      "option": "@text-overlay",
      "argument": {
        "text": "Your text here",
        "style": {
          "charsPerLine": 18,
          "fontSize": 60,
          "lineSpacing": 15,
          "x": "0.15*w",
          "y": "(h-text_h)/2",
          "boxBorderW": 12
        }
      }
    }
  ]
}

For full control, pass a raw drawtext filter string using the -vf option:

{
  "inputs": [{"url": "https://example.com/video.mp4"}],
  "outputFormat": "mp4",
  "options": [
    {
      "option": "-vf",
      "argument": "drawtext=text='Hello World':fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2"
    }
  ]
}

Both go to POST https://api.ffmpeg-micro.com/v1/transcodes with an Authorization: Bearer YOUR_API_KEY header.

FAQ

How do I center text in FFmpeg drawtext?

Set x=(w-text_w)/2 to center horizontally and y=(h-text_h)/2 to center vertically. The variables w and h are the video dimensions, while text_w and text_h are the rendered size of the text string.

What's the difference between fontfile and fontname in drawtext?

fontfile takes a direct file path to a .ttf or .otf font. fontname references a font by its installed name and requires FFmpeg to be compiled with fontconfig. Use fontfile if you need consistent results across environments.

How do I add a background box behind drawtext text?

Add box=1:boxcolor=black@0.5:boxborderw=10 to your drawtext parameters. The @0.5 controls opacity (0 is fully transparent, 1 is fully opaque), and boxborderw sets the padding in pixels around the text.

Can I show a timestamp on video with drawtext?

Yes. Use text='%{pts\:hms}' with expansion=normal (the default). This renders the video's presentation timestamp in HH:MM:SS format on every frame. Escape the colon with a backslash because drawtext uses colons as delimiters.

How do I make drawtext appear only for part of the video?

Use the enable parameter with a between() expression. For example, enable='between(t,2,8)' shows the text only from the 2-second mark to the 8-second mark. The variable t is the current time in seconds.

ffmpeg.wasm vs a Hosted FFmpeg API: Where Browser-Side Breaks

Javid Jamae — Mon, 20 Jul 2026 16:45:42 +0000

Originally published at ffmpeg-micro.com

ffmpeg.wasm looks like magic the first time you see it. Run FFmpeg right in the browser. No server, no install, no infrastructure. Your user picks a file, you process it client-side, and nobody's video ever leaves their machine.

Then someone uploads a 200MB file and the tab crashes.

What ffmpeg.wasm actually is

ffmpeg.wasm is a WebAssembly port of FFmpeg that runs entirely in the browser. Your JavaScript can do this:

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

const ffmpeg = new FFmpeg();
await ffmpeg.load();
await ffmpeg.writeFile('input.mp4', videoData);
await ffmpeg.exec(['-i', 'input.mp4', '-vf', 'scale=640:360', 'output.mp4']);
const data = await ffmpeg.readFile('output.mp4');

No server call. No API key. The entire operation happens in the user's browser tab.

Where ffmpeg.wasm works well

For small, quick operations on small files:

Thumbnail extraction from short clips (under 50MB)
Format detection and metadata inspection
Quick trims of short videos
Privacy-sensitive workflows where video can't leave the device

The five walls you'll hit

1. Memory ceiling

A 500MB video needs at least 500MB of RAM just for the input. The practical limit is roughly 100-200MB per file on desktop, less on mobile.

2. Single-threaded performance

A transcode that takes 30 seconds on a server can take 5-10 minutes in the browser. Multi-threaded builds require SharedArrayBuffer and specific CORS headers that break third-party embeds.

3. Codec limitations

The Wasm build doesn't include every codec. Licensing and binary size constraints mean you get a subset.

4. Mobile is unreliable

Mobile browsers have tighter memory limits and more aggressive tab killing. A transcode that works on your MacBook will crash Safari on an iPhone 12.

5. No batch processing

Processing 50 files means the user keeps the tab open. Any browser crash kills the entire batch.

Comparison table

Factor	ffmpeg.wasm	Hosted FFmpeg API
Max file size	~100-200MB	No practical limit
Processing speed	5-10x slower	Server-grade
Mobile support	Unreliable	Works everywhere
Batch processing	Manual, fragile	Built-in queuing
Privacy	Video stays on device	Video uploaded to server
Cost	Free (client CPU)	Pay per minute processed

The hybrid approach

Use ffmpeg.wasm for lightweight client-side ops and route heavier work to an API:

const FILE_SIZE_THRESHOLD = 50 * 1024 * 1024; // 50MB

async function processVideo(file) {
  if (file.size < FILE_SIZE_THRESHOLD) {
    return processClientSide(file); // ffmpeg.wasm
  }
  return processServerSide(file);   // FFmpeg Micro API
}

Read the full post with detailed analysis on ffmpeg-micro.com.

How to Remove Audio from Video with FFmpeg

Javid Jamae — Mon, 20 Jul 2026 16:45:15 +0000

Originally published at ffmpeg-micro.com

You have a product demo with terrible microphone hum, a social clip that needs a music swap, or a background loop that should just be silent. The fix in FFmpeg is one flag: -an.

This post covers three ways to strip audio from video with FFmpeg, from the simplest one-liner to batch processing hundreds of files.

The `-an` flag: remove all audio in one shot

The -an flag tells FFmpeg to drop every audio stream from the output. No re-encoding of the audio track, no codec selection. It just disappears.

ffmpeg -i input.mp4 -an -c:v copy output-silent.mp4

That is it. The video stream gets copied byte-for-byte (-c:v copy), so the operation finishes in seconds regardless of file length.

Use -c:v copy whenever you can. It avoids re-encoding video, which means no quality loss and fast execution.

When `-c:v copy` won't work

If you are also applying video filters (scaling, cropping, watermarking), you need to re-encode:

ffmpeg -i input.mp4 -an -c:v libx264 -crf 23 -pix_fmt yuv420p output-silent.mp4

Replace audio with silence instead of removing it

Some platforms reject videos without an audio track. Instagram, TikTok, and certain ad networks expect audio to exist, even if it is empty:

ffmpeg -i input.mp4 -f lavfi -i anullsrc=r=44100:cl=stereo -c:v copy -c:a aac -shortest output-silent-track.mp4

The output file has a valid audio track that happens to be completely silent.

Batch-process: mute all videos in a folder

mkdir -p muted
for f in *.mp4; do
  ffmpeg -i "$f" -an -c:v copy "muted/${f%.mp4}-silent.mp4"
done

Common pitfalls

"The output still has audio." Use -c:v copy not -c copy. The shorthand -c copy copies ALL streams including audio.
"Instagram/TikTok rejects the video." Use the silent audio track approach instead of -an.
"My player shows no duration." Add -movflags +faststart to the command.

FAQ

Does -an remove audio without re-encoding? Yes. With -c:v copy, the video is copied byte-for-byte. Only audio is dropped.

What is the difference between -an and -vn? -an removes audio, keeps video. -vn does the opposite.

Will removing audio reduce file size? Yes, by the size of the audio stream (typically 5-15% of total).

Read the full post with API examples on ffmpeg-micro.com.

Running FFmpeg on Heroku: The Ephemeral-Filesystem Trap (and the Fix)

Javid Jamae — Sun, 19 Jul 2026 17:41:51 +0000

Originally published at ffmpeg-micro.com

Your FFmpeg pipeline works on localhost. You push to Heroku, trigger a transcode, and the job vanishes. No output file. No error you can Google. Just a request that hangs and then dies.

This isn't a config mistake. Heroku's architecture is fundamentally hostile to long-running FFmpeg jobs, and the buildpack README won't tell you that.

The three ways Heroku kills your FFmpeg jobs

Most developers hit one of these. Some hit all three in the same week.

The ephemeral filesystem eats your output

Heroku dynos don't have persistent storage. Every file you write goes to /tmp, and /tmp gets wiped on every dyno restart. Deploys, config changes, Heroku's own dyno cycling (which happens at least once every 24 hours). All of it triggers a restart.

If your FFmpeg job takes 4 minutes to transcode a video and Heroku cycles the dyno at minute 3, the output file is gone. No partial recovery. No resume. The work just disappears.

This is the one that burns people the hardest because it works fine during testing. Short test files finish before the cycle hits. Production files with real-world durations don't.

The buildpack bloats your slug

The standard heroku-buildpack-ffmpeg-latest adds roughly 80MB to your slug size. Heroku caps slugs at 500MB. That sounds like plenty until you account for your Node modules, your Python dependencies, your static assets, and whatever else your app ships.

A mid-sized Rails or Next.js app can easily sit at 350-400MB before adding FFmpeg. Drop in the buildpack and you're flirting with the limit. Add a second binary or a few large dependencies and the deploy fails outright.

You can strip FFmpeg down to only the codecs you need, but that means maintaining a custom buildpack fork. Now you're debugging FFmpeg compilation flags on top of everything else.

The 30-second timeout kills long encodes

Heroku web dynos enforce a hard 30-second request timeout at the router level. This isn't configurable. If your HTTP request doesn't return a response within 30 seconds, Heroku's router drops the connection and returns an H12 error.

FFmpeg transcoding a 5-minute video at reasonable quality takes longer than 30 seconds. Every time.

The standard workaround is moving FFmpeg to a worker dyno with a job queue. That means adding Redis, adding a queue library (Sidekiq for Ruby, Bull for Node), writing the queue/worker plumbing, and handling job status polling from your frontend. Your "just run FFmpeg" feature now requires three additional infrastructure components and a new failure surface.

Worker dynos don't have the 30-second timeout, but they still have the ephemeral filesystem problem. You've solved one issue and kept another.

The honest fork: harden it or offload it

You have two real options. Neither is wrong, but they lead to very different maintenance burdens.

Option A: Harden the Heroku setup

This means:

Streaming FFmpeg output directly to S3 instead of writing to /tmp (using pipes or chunked uploads)
Running FFmpeg on worker dynos with Redis and a job queue
Pinning your buildpack to a specific FFmpeg version so deploys don't break when upstream changes
Building health checks and retry logic for jobs that die mid-transcode

This works. Teams do run FFmpeg on Heroku in production. But you're maintaining a distributed video processing pipeline on top of an app platform that wasn't designed for it. Every piece (S3 streaming, queue infrastructure, retry logic, buildpack maintenance) is another thing that can break at 2am.

Option B: Keep the dyno stateless

Instead of fighting Heroku's architecture, work with it. Keep your dyno doing what dynos are good at (serving requests, running application logic) and send the FFmpeg work to an API that handles the filesystem, the timeouts, and the binary management for you.

Your Heroku app sends a POST request with the input file URL and the FFmpeg options. The transcode runs on infrastructure built for it. Your dyno stays stateless, your slug stays small, and you don't need Redis.

A single API call from your Heroku app replaces the entire worker dyno + queue + S3 pipeline:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://your-s3-bucket.amazonaws.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "23"}
    ]
  }'

The input file gets pulled from your S3 bucket (or any public URL). The transcode runs on FFmpeg Micro's infrastructure. You poll for completion or set up a webhook. No buildpack, no worker dyno, no ephemeral filesystem.

Your Heroku app stays a Heroku app. The video processing happens somewhere that won't wipe your files mid-job.

The real cost isn't the first deploy

Getting FFmpeg running on Heroku isn't the hard part. Keeping it running is. The dyno cycling, the slug creep as your app grows, the queue jobs that silently fail, the buildpack that pulls a new FFmpeg version and breaks your encoding flags.

Every hour you spend debugging Heroku-specific FFmpeg failures is an hour you're not building the feature your users actually asked for.

FAQ

Why does FFmpeg work locally but fail on Heroku?

Local machines have persistent filesystems and no request timeouts. Heroku dynos have ephemeral storage that wipes on restart and a 30-second router timeout on web dynos. FFmpeg jobs that finish fine on your laptop will fail in production if they write to disk or take longer than 30 seconds.

Can I increase the Heroku dyno timeout for video processing?

No. The 30-second timeout on web dynos is enforced at the Heroku router and is not configurable. Your options are moving FFmpeg to a background worker dyno with a job queue (Redis + Sidekiq or Bull) or offloading the transcode to an external API.

What is the best FFmpeg buildpack for Heroku?

The most common is heroku-buildpack-ffmpeg-latest, which pulls the current FFmpeg build. It adds roughly 80MB to your slug. For production use, pin it to a specific FFmpeg version so your deploys don't break when upstream releases a new build with different codec defaults.

How do I handle large video files on Heroku's ephemeral filesystem?

Don't write to the local filesystem for anything you need to keep. Stream FFmpeg output directly to S3 using pipes, or use a hosted FFmpeg API that handles storage independently. Any file written to /tmp on a Heroku dyno will be lost on the next restart, which happens at least once every 24 hours.

Is Heroku a good platform for video processing?

Heroku is built for stateless web applications, not compute-heavy media processing. You can make it work with worker dynos, job queues, and external storage, but you're adding significant infrastructure complexity. If video processing is a core feature of your app, purpose-built infrastructure (or a hosted API) will save you maintenance time.

How to Flip a Video with FFmpeg (hflip and vflip Filters)

Javid Jamae — Sun, 19 Jul 2026 17:41:47 +0000

Originally published at ffmpeg-micro.com

Front-facing camera footage is mirrored. Text reads backwards, logos are reversed, and the left-right orientation is wrong. If you're processing selfie video, screen recordings from mobile devices, or any source that captured a mirror image, you need to flip it before the output goes anywhere useful.

To flip a video horizontally with FFmpeg, use the hflip video filter: ffmpeg -i input.mp4 -vf hflip -c:a copy output.mp4. For a vertical flip, replace hflip with vflip.

Flip vs. Rotate

This trips people up constantly. A flip mirrors the frame along an axis. A rotation spins it. Horizontal flip (hflip) mirrors left to right, like looking in a mirror. A 90-degree rotation turns the entire frame sideways, changing the orientation and usually the resolution dimensions too.

If someone tells you their video is "upside down," they probably want vflip or a 180-degree rotation. A 180-degree rotation is actually identical to combining hflip and vflip together, which we'll cover below.

Horizontal Flip with `hflip`

The hflip filter mirrors the video along the vertical axis. Every frame gets its pixels reversed left-to-right. This is the filter you want for selfie correction, fixing mirrored webcam footage, or creating a mirror effect for social media content.

ffmpeg -i input.mp4 -vf hflip -c:a copy output.mp4

The -vf hflip flag applies the horizontal flip filter. The -c:a copy flag passes the audio stream through without re-encoding, which saves time and avoids any quality loss on the audio side.

The video stream does get re-encoded. FFmpeg has to decode each frame, flip the pixel data, and encode it again. You can't flip a video with stream copy on the video track because the actual pixel data needs to change.

Vertical Flip with `vflip`

The vflip filter mirrors the video along the horizontal axis, flipping it upside down. Every frame gets its rows of pixels reversed top-to-bottom.

ffmpeg -i input.mp4 -vf vflip -c:a copy output.mp4

You'll run into vertical flip less often than horizontal. The most common use case is correcting footage from cameras mounted upside down, like security cameras or action cameras with inverted mounts.

Combining `hflip` and `vflip` for 180-Degree Rotation

Chaining both filters together gives you the equivalent of a 180-degree rotation. The frame gets mirrored horizontally and vertically, which produces the same result as spinning it halfway around.

ffmpeg -i input.mp4 -vf "hflip,vflip" -c:a copy output.mp4

The filter chain runs left to right. FFmpeg applies hflip first, then vflip to the already-flipped output. The order doesn't matter for this specific combination since the end result is the same either way. It does matter when you start mixing flips with other filters like scaling or cropping.

Preserving Audio

Both examples above use -c:a copy to pass the audio through untouched. This is almost always what you want. Flipping video has nothing to do with the audio stream, so re-encoding it just wastes time and adds a generation of lossy compression for no reason.

If you leave out -c:a copy, FFmpeg will re-encode the audio using its default codec for the output container. For MP4, that's usually AAC. The quality difference on a single re-encode is minimal, but there's no upside when stream copy is available.

Common Pitfalls

Forgetting that video gets re-encoded

You can't use -c:v copy with flip filters. The pixel data is changing, so FFmpeg needs to decode and re-encode the video stream. If you try -c:v copy -vf hflip, FFmpeg will throw an error. This means your output file size and quality depend on your encoder settings. If you need to match the original quality closely, set your bitrate or CRF value explicitly:

ffmpeg -i input.mp4 -vf hflip -c:v libx264 -crf 18 -c:a copy output.mp4

Confusing flip with transpose

FFmpeg also has a transpose filter that combines rotation with an optional flip. If you use transpose=1 expecting a simple mirror, you'll get a 90-degree clockwise rotation instead. Stick with hflip and vflip when you just need mirroring. Use transpose only when you actually need to rotate by 90 or 270 degrees.

Not accounting for metadata rotation

Some mobile video files store rotation in metadata rather than in the actual pixel data. FFmpeg auto-rotates based on metadata by default. If your input has a rotation flag in its metadata and you apply hflip, you get unexpected results because FFmpeg applies the auto-rotation before your filter. To disable auto-rotation and work with the raw pixel data, add -noautorotate:

ffmpeg -noautorotate -i input.mp4 -vf hflip -c:a copy output.mp4

Flipping Video at Scale with the FFmpeg Micro API

Running these commands locally works fine for one-off jobs. When you need to flip hundreds or thousands of videos programmatically, shelling out to FFmpeg from your application code gets messy fast. You're managing processes, handling failures, provisioning compute, and babysitting encoding queues.

FFmpeg Micro gives you a REST API that runs FFmpeg filters in the cloud, including hflip and vflip. Send a POST request with your filter chain and get back the processed video:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "hflip"},
      {"option": "-c:a", "argument": "copy"}
    ]
  }'

No infrastructure to manage. No FFmpeg installation to maintain. Just an API call with the same filter syntax you already know.

FAQ

How do I mirror a video in FFmpeg?

Use the hflip video filter to mirror a video horizontally in FFmpeg: ffmpeg -i input.mp4 -vf hflip -c:a copy output.mp4. This reverses the frame left-to-right, producing a mirror image of the original footage.

What is the difference between hflip and vflip in FFmpeg?

The hflip filter mirrors the video along the vertical axis, flipping it left-to-right like a mirror reflection. The vflip filter mirrors the video along the horizontal axis, flipping it upside down. You can combine both with -vf "hflip,vflip" to get a 180-degree rotation.

Can I flip a video without re-encoding the audio?

Yes. Add -c:a copy to your FFmpeg command to pass the audio stream through without re-encoding. The video stream will still be re-encoded because the pixel data changes during a flip, but the audio stays untouched.

How do I rotate a video 180 degrees with FFmpeg?

Combine hflip and vflip filters: ffmpeg -i input.mp4 -vf "hflip,vflip" -c:a copy output.mp4. This mirrors the frame both horizontally and vertically, which produces the same result as a 180-degree rotation.

Does flipping a video affect quality?

Flipping requires FFmpeg to re-encode the video stream, which can reduce quality depending on your encoder settings. To minimize quality loss, use a low CRF value (like 18) with libx264. The audio stream isn't affected if you use -c:a copy.

Optimize Videos for Framer with FFmpeg Micro

Javid Jamae — Sat, 18 Jul 2026 15:59:34 +0000

Originally published at ffmpeg-micro.com.

Framer doesn't process video. Drop a 200MB ProRes file into a Framer project and that's exactly what visitors download. No compression, no format conversion, no codec negotiation. Your marketing site loads like it's 2008.

Framer's own documentation tells you to run FFmpeg commands before uploading. That's the right advice. But most Framer users are designers and founders, not people who want to install a command-line tool and memorize codec flags.

TL;DR: Convert your video to H.264 MP4, compress it with CRF, and apply the +faststart flag before uploading to Framer. FFmpeg Micro's REST API does all three in one call. No FFmpeg installation required.

Why Framer Can't Handle This for You

Framer is a design tool, not a media pipeline. When you upload a video, Framer stores it on its CDN without any transcoding. That means whatever codec, resolution, and file size you upload is what every visitor gets.

This creates three problems.

File size. Framer caches assets in the browser, but most browsers cap that cache at around 5 MB per resource. A 50 MB hero video won't stay cached. Every repeat visit triggers a fresh download.

Codec compatibility. Safari won't play WebM. Older browsers choke on HEVC. If you shot on an iPhone (HEVC by default) or exported from Premiere as WebM, a chunk of your audience sees a broken player.

Progressive download. Without the faststart flag, MP4 files store their metadata (the moov atom) at the end of the file. The browser has to download the entire file before it can start playback. On a landing page, that delay kills conversions.

The Three Things Every Framer Video Needs

Before uploading any video to Framer, you need to do three things:

Compress it. Reduce the file size using CRF (Constant Rate Factor) so the visual quality stays high while the bitrate drops. CRF 23 is a good starting point for web video.
Convert to H.264 MP4. This is the one format that plays everywhere. Safari, Chrome, Firefox, Edge, iOS, Android. No exceptions.
Add faststart. The -movflags +faststart flag moves the moov atom to the beginning of the file so browsers can start playback immediately, even before the full download finishes.

The FFmpeg CLI Way

If you have FFmpeg installed locally, this single command handles all three:

ffmpeg -i input.mov -c:v libx264 -crf 23 -c:a aac -movflags +faststart output.mp4

That works. But it requires installing FFmpeg, knowing the right flags, and running it manually every time you want to update a video on your Framer site. If you're processing multiple hero sections, testimonial clips, or product demos, it gets old fast.

The API Way (FFmpeg Micro)

FFmpeg Micro is a hosted REST API that runs FFmpeg in the cloud. You send it a video URL, tell it what you want, and get back a processed file. No binary to install. No server to manage.

Simple mode uses presets:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/raw-hero.mov"}],
    "outputFormat": "mp4",
    "preset": {"quality": "high", "resolution": "1080p"}
  }'

Advanced mode gives you full control over codec, CRF, and faststart:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://example.com/raw-hero.mov"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "23"},
      {"option": "-movflags", "argument": "+faststart"},
      {"option": "-c:a", "argument": "aac"}
    ]
  }'

The API returns a job ID. Poll the status endpoint until it completes, then grab the download URL.

Here's the full flow in JavaScript:

const API_KEY = "your-api-key";

// 1. Start the transcode
const job = await fetch("https://api.ffmpeg-micro.com/v1/transcodes", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inputs: [{ url: "https://example.com/raw-hero.mov" }],
    outputFormat: "mp4",
    options: [
      { option: "-c:v", argument: "libx264" },
      { option: "-crf", argument: "23" },
      { option: "-movflags", argument: "+faststart" },
      { option: "-c:a", argument: "aac" },
    ],
  }),
}).then((r) => r.json());

// 2. Poll until complete
let status = job.status;
while (status !== "completed" && status !== "failed") {
  await new Promise((r) => setTimeout(r, 5000));
  const check = await fetch(
    `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
  ).then((r) => r.json());
  status = check.status;
}

// 3. Get the download URL
const download = await fetch(
  `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}/download`,
  { headers: { "Authorization": `Bearer ${API_KEY}` } }
).then((r) => r.json());

console.log("Download your optimized video:", download.url);

Upload the resulting file to Framer and you're done. Compressed H.264 MP4 with faststart, ready for every browser.

Common Framer Video Problems (and Fixes)

Video won't play in Safari. Safari doesn't support WebM or VP9. Convert to H.264 MP4 using the options above. This is the single most common Framer video complaint.

Hero video loads slowly. Two culprits: the file is too large, or it's missing the faststart flag. Compress with CRF 23 and make sure -movflags +faststart is in your options. For above-the-fold hero videos, aim for under 5 MB.

Video looks blurry after upload. Framer didn't compress it. You did, probably too aggressively. Lower the CRF number (18-20 gives near-lossless quality at a larger file size) or bump the resolution preset to 1080p.

File is still too large after compression. Drop the resolution. A 720p video at CRF 23 is often under 3 MB for a 15-second clip. On a marketing site, most visitors won't notice the resolution difference on a background video.

FAQ

Does Framer compress video automatically?

No. Framer serves videos exactly as uploaded. There is no server-side transcoding, compression, or format conversion. You need to optimize video files before uploading them to your Framer project.

What video format works best for Framer sites?

H.264 MP4 with the faststart flag is the best format for Framer. It plays in every major browser including Safari on iOS, supports progressive download for fast playback, and compresses well for web delivery.

Why won't my video play in Safari on a Framer site?

Safari does not support WebM or VP9 video codecs. If your video was exported as WebM or uses HEVC without a fallback, Safari will show a blank player or an error. Converting to H.264 MP4 fixes this across all browsers.

Can I optimize video for Framer without installing FFmpeg?

Yes. FFmpeg Micro is a cloud API that runs FFmpeg remotely. You send a video URL via HTTP request and receive a compressed, converted file back. No installation, no command line, no server. A free tier is available to get started.

What CRF value should I use for Framer hero videos?

CRF 23 is a good default for web video. It produces a significant file size reduction with minimal visible quality loss. For hero sections where quality matters more, try CRF 18-20. For background videos where some softness is acceptable, CRF 28 keeps files very small.

How to Use FFmpeg with Bun

Javid Jamae — Sat, 18 Jul 2026 15:59:17 +0000

Originally published at ffmpeg-micro.com.

You're building something in Bun and you need video processing. Thumbnail generation, format conversion, transcoding user uploads. You search for "ffmpeg bun" and find a bunch of Node.js tutorials that mostly work but don't use any of Bun's native APIs. You're stuck shimming child_process when Bun has its own subprocess interface built in.

Bun's selling points are speed and developer experience. Native TypeScript, fast startup, a built-in bundler. But when it comes to calling FFmpeg, you still need to figure out how to bridge your code to a native binary. Or avoid the binary entirely.

There are three realistic paths. Each works, each has real tradeoffs.

Using Bun.spawn with a Local FFmpeg Binary

If FFmpeg is installed on the machine, you can call it directly using Bun.spawn. This is Bun's native subprocess API. It's similar in spirit to Node's child_process.spawn, but the interface is cleaner and returns a Subprocess object you can await directly.

const proc = Bun.spawn(
  [
    "ffmpeg",
    "-i", "input.mp4",
    "-c:v", "libx264",
    "-crf", "23",
    "-preset", "medium",
    "-c:a", "aac",
    "-b:a", "192k",
    "output.mp4",
  ],
  { stderr: "pipe" },
);

const exitCode = await proc.exited;

if (exitCode !== 0) {
  const stderr = await new Response(proc.stderr).text();
  console.error("FFmpeg failed:", stderr);
} else {
  console.log("Transcoding complete");
}

No permission flags needed. Unlike Deno, Bun doesn't sandbox subprocess execution. You call Bun.spawn and it runs. That makes local development faster but also means your code has full system access by default.

This approach works well for local scripts, CLI tools, and servers where you control the environment. But it breaks down in production. You need FFmpeg installed on every machine. Most serverless and edge runtimes don't support spawning native binaries. And you're responsible for managing FFmpeg versions, codec libraries, and OS-level dependencies yourself.

Using FFmpeg WASM in Bun

ffmpeg.wasm compiles FFmpeg to WebAssembly, so it runs without a native binary. Bun's Node.js compatibility means it just works:

import { FFmpeg } from "@ffmpeg/ffmpeg";
import { fetchFile } from "@ffmpeg/util";

const ffmpeg = new FFmpeg();
await ffmpeg.load();

await ffmpeg.writeFile("input.mp4", await fetchFile("./input.mp4"));
await ffmpeg.exec(["-i", "input.mp4", "-c:v", "libx264", "output.mp4"]);
const data = await ffmpeg.readFile("output.mp4");

await Bun.write("output.mp4", data);

No FFmpeg binary needed. No system dependencies. But the tradeoffs are significant. Processing is 10-20x slower than native FFmpeg because WebAssembly can't match native CPU performance for heavy compute work. Memory is constrained. Not all codecs are available in the WASM build. And large files (anything over a few hundred MB) will likely crash.

ffmpeg.wasm is fine for lightweight operations like extracting a single frame or trimming a short clip. Don't try to transcode a full-length video with it.

Using the FFmpeg Micro Cloud API

If you don't want to manage FFmpeg binaries or accept WASM performance penalties, a cloud API is the cleanest path. FFmpeg Micro processes video through standard HTTP requests, which Bun handles natively with fetch(). No npm packages. No binary dependencies. Just HTTP.

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

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

One fetch call. FFmpeg Micro handles the transcoding infrastructure, codec management, and scaling. Your Bun app just sends an HTTP request.

For advanced use cases where you need specific FFmpeg flags, use the options array instead of presets:

const response = await fetch("https://api.ffmpeg-micro.com/v1/transcodes", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${Bun.env.FFMPEG_MICRO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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" },
    ],
  }),
});

Polling for Completion

Transcodes are async. Poll the status endpoint until the job finishes:

async function waitForTranscode(jobId: string): Promise<Record<string, unknown>> {
  const apiKey = Bun.env.FFMPEG_MICRO_API_KEY;

  while (true) {
    const res = await fetch(
      `https://api.ffmpeg-micro.com/v1/transcodes/${jobId}`,
      { headers: { "Authorization": `Bearer ${apiKey}` } },
    );
    const job = await res.json();

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

    await Bun.sleep(2000);
  }
}

Once completed, grab the download URL:

const downloadRes = await fetch(
  `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}/download`,
  { headers: { "Authorization": `Bearer ${apiKey}` } },
);
const { url } = await downloadRes.json();
console.log("Download:", url);

This works identically on your local machine, in a Docker container, or on any hosting platform that runs Bun. No environment-specific setup.

Which Approach Should You Use

Bun.spawn if you're writing a local script or CLI tool where you control the machine and FFmpeg is already installed. Bun's fast startup makes it great for quick scripts that shell out to FFmpeg.

ffmpeg.wasm if you need in-process video handling for small files and can tolerate much slower performance.

A cloud API like FFmpeg Micro if you're building a production app, deploying to serverless infrastructure, or want to avoid managing FFmpeg binaries entirely. The API approach is the only option on platforms that don't support native binaries, and it keeps your Bun app lightweight.

Common Pitfalls

Using child_process instead of Bun.spawn. Bun supports Node's child_process for compatibility, but Bun.spawn is faster and returns a cleaner API. The proc.exited promise is simpler than wiring up event listeners on a ChildProcess object.

Forgetting to handle stderr. FFmpeg writes all its logging (including progress) to stderr, not stdout. If you don't set stderr: "pipe" in Bun.spawn, you won't see error messages when a transcode fails. Bun defaults to inheriting the parent's stderr, which works for debugging but swallows output if you need to capture it programmatically.

Using Bun.file for reading FFmpeg output before it's flushed. Bun.file is fast, but if you read an output file before FFmpeg has fully flushed and closed it, you'll get a partial file. Always await proc.exited before reading the output.

Assuming Bun.spawn works everywhere. Bun's subprocess API needs a real OS process. On platforms like Cloudflare Workers or other V8 isolate runtimes, subprocess spawning isn't available. If your deployment target restricts system calls, use a cloud API instead.

FAQ

Can I use fluent-ffmpeg with Bun?

Yes. Bun's Node.js compatibility layer supports fluent-ffmpeg out of the box. Install it with bun add fluent-ffmpeg and it works the same as in Node. But you still need a local FFmpeg binary installed. If you want Bun-native code without the Node compatibility layer, use Bun.spawn directly or the FFmpeg Micro API for cloud processing.

How does Bun compare to Node.js for FFmpeg video processing?

The FFmpeg CLI itself is identical. The difference is in how you call it. Node.js uses child_process.spawn, Bun uses Bun.spawn. Both need the binary installed. Bun's faster startup makes short-lived scripts noticeably quicker, and native TypeScript means no build step. The cloud API approach is the same across both runtimes since it's just HTTP fetch. For a Node.js comparison, check the Node.js FFmpeg guide.

Does Bun.spawn work on serverless platforms?

It depends on the platform. Bun can run on traditional servers and in Docker, where Bun.spawn works fine. But serverless environments like Cloudflare Workers or edge functions typically run in V8 isolates that don't support subprocess execution. If you're deploying to those platforms, the cloud API approach is your best option.

What video formats does the FFmpeg Micro API support?

FFmpeg Micro accepts any format FFmpeg can read as input. For output, you can specify mp4, webm, or mov in the outputFormat field. The preset mode supports quality levels (high, medium, low) and resolution options (480p, 720p, 1080p, 4k). Check the full API docs for the complete list.

Do I need to pay to use FFmpeg Micro with Bun?

FFmpeg Micro has a free tier with enough processing time to build and test your integration. You can sign up for a free API key and start processing video in minutes. For a hands-on walkthrough of FFmpeg concepts, the Learn FFmpeg training covers everything from basics to automation.

How to Use FFmpeg with Trigger.dev (No Binary Setup Required)

Javid Jamae — Fri, 17 Jul 2026 10:21:29 +0000

Originally published at ffmpeg-micro.com.

Trigger.dev's official FFmpeg guide tells you to install the @trigger.dev/build extension, bundle a static FFmpeg binary into your task, and call it with ffmpegPath(). It works. Until your build artifact balloons past 100 MB, your cold starts crawl, and you're debugging codec availability across deployment environments.

You don't need to ship FFmpeg with your Trigger.dev task. Call an FFmpeg API over HTTP instead, and keep your tasks lean.

Quick answer: Replace the @trigger.dev/build FFmpeg extension with HTTP calls to FFmpeg Micro. POST your video URL to /v1/transcodes, poll for completion, and grab the download link. No binary in your build, no cold-start penalty, and it works on any Trigger.dev deployment target.

What breaks when you bundle FFmpeg as a binary

The @trigger.dev/build approach uses ffmpegExtension() to include a static FFmpeg binary in your task's build output. Trigger.dev's own docs walk through this pattern. For simple cases, it's fine. But production workloads expose several problems:

Build size bloat. A static FFmpeg binary adds 80-120 MB to your task artifact. Every deploy ships that weight, and every cold start loads it into memory.
Cold-start latency. Larger artifacts mean slower cold starts. If your task scales to zero between runs, each invocation pays the binary loading tax.
Codec availability. Static builds may lack specific codecs you need. Want libx265 or libvpx-vp9? You're recompiling or hoping the bundled binary includes it.
Version management. Pinning FFmpeg versions across environments is your problem. Updates mean rebuilding and redeploying.

None of these issues exist when FFmpeg runs on someone else's infrastructure.

The binary approach (before)

This is what Trigger.dev's guide recommends. You install the extension, configure your build, and call FFmpeg from the task:

// trigger.config.ts
import { ffmpegExtension } from "@trigger.dev/build/extensions";

export default defineConfig({
  build: {
    extensions: [ffmpegExtension()],
  },
});

// tasks/process-video.ts
import { task } from "@trigger.dev/sdk/v3";
import { ffmpegPath } from "@trigger.dev/build/extensions";
import { execSync } from "child_process";

export const processVideoTask = task({
  id: "process-video",
  run: async (payload: { videoUrl: string }) => {
    const inputPath = "/tmp/input.mp4";
    const outputPath = "/tmp/output.mp4";

    // Download the file first
    execSync(`curl -o ${inputPath} "${payload.videoUrl}"`);

    // Run FFmpeg binary
    execSync(`${ffmpegPath()} -i ${inputPath} -vf scale=1280:720 -crf 23 ${outputPath}`);

    // Upload output somewhere...
  },
});

You're managing file I/O, disk space in /tmp, the binary path, and cleanup. The task does too much.

Drop the binary: FFmpeg over HTTP in Trigger.dev

Replace all of that with three HTTP calls. No extension, no binary, no file system management.

import { task } from "@trigger.dev/sdk/v3";

export const processVideoTask = task({
  id: "process-video",
  run: async (payload: { videoUrl: string }) => {
    const API_KEY = process.env.FFMPEG_MICRO_API_KEY;
    const BASE_URL = "https://api.ffmpeg-micro.com";

    // 1. Start the transcode job
    const createRes = await fetch(`${BASE_URL}/v1/transcodes`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        inputs: [{ url: payload.videoUrl }],
        outputFormat: "mp4",
        preset: { quality: "high" },
      }),
    });

    const job = await createRes.json();

    // 2. Poll until complete
    let status = job.status;
    while (status !== "completed" && status !== "failed") {
      await new Promise((r) => setTimeout(r, 5000));

      const pollRes = await fetch(`${BASE_URL}/v1/transcodes/${job.id}`, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      const pollData = await pollRes.json();
      status = pollData.status;
    }

    if (status === "failed") {
      throw new Error(`Transcode failed for job ${job.id}`);
    }

    // 3. Get the download URL
    const downloadRes = await fetch(
      `${BASE_URL}/v1/transcodes/${job.id}/download`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );
    const { url } = await downloadRes.json();

    return { downloadUrl: url };
  },
});

That's the entire task. No trigger.config.ts changes. No build extensions. No /tmp disk management. Your task artifact stays small, cold starts stay fast, and FFmpeg version management is someone else's problem.

Using custom FFmpeg options

The preset field handles common operations, but you can pass raw FFmpeg flags through the options array when you need fine-grained control. Resize to 720p, set a specific CRF, or choose a codec:

body: JSON.stringify({
  inputs: [{ url: payload.videoUrl }],
  outputFormat: "mp4",
  options: [
    { option: "-vf", argument: "scale=1280:720" },
    { option: "-c:v", argument: "libx264" },
    { option: "-crf", argument: "23" },
    { option: "-c:a", argument: "aac" },
    { option: "-b:a", argument: "128k" },
  ],
}),

The outputFormat accepts mp4, webm, or mov. Use -vf for video filters. Note that -filter_complex is not supported. Use -vf for all filter operations.

Handling file uploads in your task

If your Trigger.dev task receives a file that isn't publicly accessible by URL, upload it to FFmpeg Micro first using the presigned upload flow:

// 1. Get a presigned upload URL
const presignRes = await fetch(`${BASE_URL}/v1/upload/presigned-url`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filename: "input.mp4",
    contentType: "video/mp4",
    fileSize: fileBuffer.byteLength,
  }),
});
const { result } = await presignRes.json();

// 2. PUT the file to the presigned URL
await fetch(result.uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "video/mp4" },
  body: fileBuffer,
});

// 3. Confirm the upload
const confirmRes = await fetch(`${BASE_URL}/v1/upload/confirm`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filename: result.filename,
    fileSize: fileBuffer.byteLength,
  }),
});
const confirmed = await confirmRes.json();

// Now use confirmed.result.gcsUrl as your input URL for transcoding

The upload goes directly to cloud storage, not through the API server. Fast even for large files.

Common pitfalls

Checking only for "completed" in your poll loop. If a job fails and you're not checking for "failed", your loop runs until the Trigger.dev task times out. Always check both terminal states.

Mixing options and preset in the same request. If you include both, options takes priority and preset is ignored. Pick one per request.

Storing the signed download URL for later use. Signed URLs expire after 10 minutes. Always call the /download endpoint fresh when you actually need the file.

Using -filter_complex instead of -vf. The FFmpeg Micro API doesn't support -filter_complex. Use -vf for video filter operations.

Polling too aggressively. A 1-second interval wastes API calls. Five seconds works well for most video lengths. A 10-minute 1080p file typically processes in 1-3 minutes.

FAQ

Do I still need @trigger.dev/build for this approach?

No. The API approach uses standard fetch calls. Remove ffmpegExtension() from your trigger.config.ts entirely. No build extensions are needed.

What if my Trigger.dev task times out before the transcode finishes?

Increase the maxDuration on your task definition. Most transcodes finish within a few minutes. For very long videos, consider splitting the polling into a separate task that the first task triggers, or use Trigger.dev's wait utilities.

Can I process videos that require authentication to download?

Yes. Use a pre-signed URL from your storage provider (S3 pre-signed URL, GCS signed URL) as the input URL. FFmpeg Micro downloads the video from whatever URL you provide. For more details, see our guide on FFmpeg authorization headers.

How does pricing compare to running my own FFmpeg binary?

The binary approach costs you compute time on your Trigger.dev infrastructure, plus the cold-start overhead on every invocation. FFmpeg Micro has a free tier with 10 minutes of processing per month, enough to build and test your workflow. Paid plans scale based on usage. For a deeper comparison, see self-hosting FFmpeg vs. using an API.

What video formats are supported?

Input: any format FFmpeg can read, including MP4, WebM, MOV, AVI, and MKV. Output: mp4, webm, or mov. Audio formats (MP3, WAV, AAC) are supported for audio extraction workflows.

If you're already using Trigger.dev for background jobs and want video processing without the binary overhead, grab a free FFmpeg Micro API key and swap out the extension. The TypeScript examples above work as-is. For more on using FFmpeg with TypeScript in general, check out our FFmpeg with TypeScript guide.

Last verified: July 2026. Code examples tested against Trigger.dev SDK v3 and FFmpeg Micro API v1.

FFmpeg eq Filter: Adjust Brightness, Contrast, and Saturation

Javid Jamae — Fri, 17 Jul 2026 10:21:17 +0000

Originally published at ffmpeg-micro.com.

Video shot in different conditions looks different. A batch of user-uploaded clips won't match each other. Camera auto-exposure shifts between takes. Screen recordings come out dim. The FFmpeg eq filter lets you fix brightness, contrast, saturation, and gamma in a single filter pass, right from the command line or an API call, without opening a GUI editor.

Quick answer: The FFmpeg eq filter adjusts brightness, contrast, saturation, and gamma of a video stream. Apply it with -vf "eq=brightness=0.06:contrast=1.2:saturation=1.3" to brighten, boost contrast, and enrich colors in one pass. All parameters are optional and default to neutral values (brightness 0, contrast 1.0, saturation 1.0, gamma 1.0).

How the FFmpeg eq Filter Works

The eq filter modifies pixel values in the YUV color space. Brightness shifts the luma channel up or down. Contrast scales luma around a midpoint. Saturation scales the chroma channels. Gamma applies a nonlinear curve to luma (or individual RGB channels after internal conversion).

The basic syntax:

eq=brightness=<val>:contrast=<val>:saturation=<val>:gamma=<val>

All parameters are keyword arguments separated by colons. You only need to specify the ones you want to change.

Parameter	Range	Default	What it does
brightness	-1.0 to 1.0	0.0	Shifts luma up (brighter) or down (darker)
contrast	-1000.0 to 1000.0	1.0	Scales luma around the midpoint. Below 1.0 flattens, above 1.0 sharpens tonal separation
saturation	0.0 to 3.0	1.0	Scales color intensity. 0 is grayscale, above 1.0 makes colors more vivid
gamma	0.1 to 10.0	1.0	Nonlinear luma curve. Below 1.0 brightens midtones, above 1.0 darkens them
gamma_r	0.1 to 10.0	1.0	Gamma correction for the red channel only
gamma_g	0.1 to 10.0	1.0	Gamma correction for the green channel only
gamma_b	0.1 to 10.0	1.0	Gamma correction for the blue channel only

Adjusting Brightness and Contrast with FFmpeg

The most common use case: a video came out too dark or too flat, and you need to correct it before publishing.

CLI:

ffmpeg -i input.mp4 -vf "eq=brightness=0.1:contrast=1.3" -c:a copy output.mp4

This bumps brightness by 0.1 (a subtle lift) and increases contrast to 1.3 (noticeable tonal punch). The -c:a copy flag passes audio through without re-encoding.

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "eq=brightness=0.1:contrast=1.3"},
      {"option": "-c:a", "argument": "copy"}
    ]
  }'

A brightness value of 0.1 is a good starting point for underexposed footage. Going above 0.2 usually looks washed out. For contrast, stay between 1.0 and 1.5 for natural results. Anything above 2.0 starts to crush shadows and clip highlights.

Color Correction: Adjusting Saturation

Desaturated footage is a common problem with screen recordings, webcam captures, and action cameras in overcast light. The saturation parameter fixes it.

CLI:

ffmpeg -i input.mp4 -vf "eq=saturation=1.5" -c:a copy output.mp4

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "eq=saturation=1.5"},
      {"option": "-c:a", "argument": "copy"}
    ]
  }'

Setting saturation to 0 converts the video to grayscale. That's useful for stylistic effects or for feeding into computer vision pipelines where color is irrelevant. A value of 1.5 adds noticeable vibrancy without looking artificial. Above 2.0, colors start to bleed.

Using Gamma for Midtone Correction

Brightness is a linear shift. Gamma is a curve. That distinction matters when you're correcting footage that looks dim but you don't want to blow out the highlights.

Gamma below 1.0 lifts the midtones and shadows while leaving the brightest parts mostly untouched. Gamma above 1.0 darkens midtones without crushing blacks.

CLI:

ffmpeg -i input.mp4 -vf "eq=gamma=0.7:saturation=1.2" -c:a copy output.mp4

This brightens midtones (gamma 0.7 gives a visible lift) and slightly boosts color. It's a better choice than the brightness parameter for footage that's underexposed but has intact highlights.

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "eq=gamma=0.7:saturation=1.2"},
      {"option": "-c:a", "argument": "copy"}
    ]
  }'

For per-channel control, use gamma_r, gamma_g, and gamma_b. This is useful for correcting white balance problems. Footage shot under tungsten lighting looks orange. You can fix it by reducing the red gamma and boosting the blue gamma:

ffmpeg -i input.mp4 -vf "eq=gamma_r=0.85:gamma_b=1.15" -c:a copy output.mp4

Combining eq with Other Filters

The eq filter works well chained with other video filters. A common pipeline is to scale, color-correct, then encode.

CLI:

ffmpeg -i input.mp4 -vf "scale=1920:1080,eq=brightness=0.06:contrast=1.2:saturation=1.3" \
  -c:v libx264 -crf 23 -c:a copy output.mp4

This resizes to 1080p, applies color correction, and encodes with libx264 at CRF 23. Filters in a -vf chain execute left to right, so scale runs before eq.

API (FFmpeg Micro):

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "scale=1920:1080,eq=brightness=0.06:contrast=1.2:saturation=1.3"},
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "23"},
      {"option": "-c:a", "argument": "copy"}
    ]
  }'

You can also combine eq with the FFmpeg fade filter for polished intros, or chain it after the scale filter when resizing user uploads to a consistent resolution.

Common Pitfalls

Confusing brightness with gamma. Brightness adds a flat offset to every pixel. Highlights clip, shadows shift uniformly. Gamma applies a curve that affects midtones most. For exposure correction, gamma almost always produces more natural results than brightness.

Contrast values that destroy detail. A contrast of 1.3 looks good. A contrast of 3.0 makes your video look like a threshold filter. The useful range for natural-looking output is 0.8 to 1.5. Use values outside that range only for deliberate stylistic effects.

Saturation above 2.0 on compressed video. Highly compressed source video (low-bitrate H.264, heavily compressed WebM) already has chroma artifacts. Pushing saturation above 2.0 amplifies those artifacts and produces color banding. If the source is lossy, keep saturation under 1.8.

Not using -c:a copy. The eq filter only touches video. Without -c:a copy, FFmpeg re-encodes your audio track for no reason. Always pass audio through when you're only doing video corrections. The FFmpeg Micro API handles this automatically.

Expecting -filter_complex support. The eq filter is a simple single-input, single-output filter. Use it with -vf, not -filter_complex. In the FFmpeg Micro API, use the -vf option field. The API doesn't support -filter_complex.

FAQ

How do I make a video brighter with FFmpeg?

Use the eq filter with a positive brightness value: ffmpeg -i input.mp4 -vf "eq=brightness=0.1" -c:a copy output.mp4. The brightness parameter ranges from -1.0 (black) to 1.0 (white), with 0 being no change. For a more natural lift that preserves highlights, use gamma instead: eq=gamma=0.8.

Can I convert a video to grayscale with FFmpeg?

Yes. Set the eq filter's saturation parameter to 0: ffmpeg -i input.mp4 -vf "eq=saturation=0" -c:a copy output.mp4. This removes all color information while preserving the luma channel. The output is a true grayscale video.

What's the difference between the eq filter and the curves filter in FFmpeg?

The eq filter adjusts brightness, contrast, saturation, and gamma with simple numeric parameters. The curves filter provides fine-grained control with custom tone curves (similar to Photoshop curves). For quick corrections, eq is faster to use. For precise color grading with specific control points, curves gives you more flexibility at the cost of a more complex syntax.

How do I fix white balance with FFmpeg?

Use the eq filter's per-channel gamma controls. For warm (orange-tinted) footage, reduce red and boost blue: eq=gamma_r=0.85:gamma_b=1.15. For cool (blue-tinted) footage, do the opposite: eq=gamma_r=1.15:gamma_b=0.85. These corrections are approximate. For precise white balance, consider the colorbalance or colortemperature filters.

Does the eq filter re-encode the video?

Yes. Any video filter in FFmpeg requires decoding and re-encoding the video stream. To control output quality, specify an encoder and quality setting like -c:v libx264 -crf 20. If you want to adjust brightness or contrast without re-encoding, that's not possible with any filter-based approach.

Color-Correct Video Without Managing FFmpeg

If you're building color correction into a product or processing user uploads at scale, you can skip the FFmpeg installation and server management. The FFmpeg Micro API runs the eq filter (and every other FFmpeg filter) as a stateless HTTP endpoint. Get a free API key and start correcting video in minutes.

Last verified: July 2026 against FFmpeg 7.x and the FFmpeg Micro API v1.

DEV Community: Javid Jamae

FFmpeg on Cloudflare Workers: Why It Fails (And the Fix)

Why FFmpeg won't run on Cloudflare Workers

V8 isolates can't spawn subprocesses

ffmpeg.wasm hits the bundle size limit

workerd blocks dynamic WASM compilation

The fix: call an FFmpeg API from your Worker

Working example: compress-on-upload Worker

Common pitfalls

FAQ

Can I run FFmpeg directly on Cloudflare Workers?

Will ffmpeg.wasm work on Cloudflare Workers?

What is the Cloudflare Workers bundle size limit?

How do I process video uploads stored in Cloudflare R2?

Is there a Cloudflare-native alternative to FFmpeg for video processing?

ffprobe: How to Inspect Video Metadata Before Processing

What ffprobe Does

Reading the JSON Output

Pre-Processing Checks That Save You Money

1. Codec validation

2. Resolution check

3. Duration sanity check

4. Missing audio check

Using ffprobe Output to Pick API Settings

Common ffprobe Pitfalls

Start Inspecting, Then Process

FAQ

How do I get ffprobe output in JSON format?

Can ffprobe read a video from a URL without downloading the whole file?

What's the difference between ffprobe and ffmpeg for reading metadata?

Does ffprobe work with audio files?

How do I check if a video file is corrupt using ffprobe?

FFmpeg on AWS Lambda: The Layer-Size and Timeout Problem

The 250 MB Layer Limit

The /tmp Storage Cap

The 15-Minute Timeout

The Cold Start Tax

When Lambda + FFmpeg Actually Works

The API Alternative: Call FFmpeg Micro from Your Lambda

FAQ

Can FFmpeg run inside AWS Lambda?

How do I add FFmpeg to an AWS Lambda layer?

What's the maximum video size I can process with FFmpeg on Lambda?

Is there a serverless way to run FFmpeg without Lambda limits?

How long does FFmpeg take to encode video on Lambda?

FFmpeg drawtext Filter: Complete Guide to Text Overlays

Basic drawtext Syntax

Font Control: fontfile, fontname, fontsize, fontcolor

Position: x and y Expressions

Styling: box, border, and shadow

Dynamic Text with Expansion Expressions

Text Overlays via FFmpeg Micro API

FAQ

How do I center text in FFmpeg drawtext?

What's the difference between fontfile and fontname in drawtext?

How do I add a background box behind drawtext text?

Can I show a timestamp on video with drawtext?

How do I make drawtext appear only for part of the video?

ffmpeg.wasm vs a Hosted FFmpeg API: Where Browser-Side Breaks

What ffmpeg.wasm actually is

Where ffmpeg.wasm works well

The five walls you'll hit

1. Memory ceiling

2. Single-threaded performance

3. Codec limitations

4. Mobile is unreliable

5. No batch processing

Comparison table

The hybrid approach

How to Remove Audio from Video with FFmpeg

The -an flag: remove all audio in one shot

When -c:v copy won't work

Replace audio with silence instead of removing it

Batch-process: mute all videos in a folder

Common pitfalls

FAQ

Running FFmpeg on Heroku: The Ephemeral-Filesystem Trap (and the Fix)

The three ways Heroku kills your FFmpeg jobs

The ephemeral filesystem eats your output

The buildpack bloats your slug

The `-an` flag: remove all audio in one shot

When `-c:v copy` won't work

Horizontal Flip with `hflip`

Vertical Flip with `vflip`

Combining `hflip` and `vflip` for 180-Degree Rotation