DEV Community: Javid Jamae

FFmpeg on Firebase Cloud Functions: Why It Breaks (and the Fix)

Javid Jamae — Sun, 26 Jul 2026 10:27:17 +0000

Originally published at ffmpeg-micro.com

You're adding video processing to a Firebase app. You install a static FFmpeg binary, write a Cloud Function that triggers on upload, deploy it, and watch it die. The function times out, the binary bloats your deployment, and GCP bills you for memory you didn't actually need.

The Timeout Wall

Firebase Cloud Functions v1 default to a 60-second timeout. You can push that to 540 seconds (9 minutes) on v2 functions, and that's a hard cap.

Transcoding a 5-minute 1080p video to H.264 takes 8-15 minutes on Cloud Functions CPU allocation. The 540-second ceiling doesn't come close.

The Memory and CPU Trap

Cloud Functions v2 gives you up to 32 GB of memory, but CPU allocation is tied to memory. At 2 GB memory, you get 1 vCPU. FFmpeg encoding is CPU-bound, not memory-bound. You end up over-provisioning memory just to get more CPU.

Binary Bundling Problems

Getting FFmpeg into a Cloud Function means either bundling via npm (ffmpeg-static, 70-100 MB), including the binary directly, or downloading at runtime. Cloud Functions has a 100 MB compressed deployment limit.

The Fix: Call an API Instead

Keep your function small and offload the encoding:

import { onObjectFinalized } from "firebase-functions/v2/storage";
import { defineSecret } from "firebase-functions/params";
import { getStorage } from "firebase-admin/storage";
import { initializeApp } from "firebase-admin/app";

initializeApp();
const ffmpegMicroKey = defineSecret("FFMPEG_MICRO_API_KEY");

export const processUploadedVideo = onObjectFinalized(
  {
    bucket: "my-app-videos",
    secrets: [ffmpegMicroKey],
    memory: "256MiB",
    timeoutSeconds: 60,
  },
  async (event) => {
    const { name, contentType } = event.data;
    if (!contentType?.startsWith("video/")) return;

    const bucket = getStorage().bucket(event.data.bucket);
    const [signedUrl] = await bucket.file(name!).getSignedUrl({
      action: "read",
      expires: Date.now() + 60 * 60 * 1000,
    });

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

    const job = await response.json();
    console.log(`Transcode job ${job.id} started for ${name}`);
  }
);

This function deploys in seconds, cold-starts in under a second, and needs only 256 MB of memory.

Read the full post with detailed analysis

FFmpeg -map Flag Explained: Stream Selection and Multi-Track Audio

Javid Jamae — Sun, 26 Jul 2026 10:26:48 +0000

Originally published at ffmpeg-micro.com

You run ffmpeg -i input.mkv output.mp4 and somehow your output is missing the commentary audio track. Or it grabbed the wrong subtitle language. FFmpeg's automatic stream selection does its best, but "best" rarely matches what you actually want when you're working with multi-track files.

The -map flag gives you explicit control over which streams go into your output. This post walks through how -map actually works, with examples you can copy and run.

How FFmpeg Picks Streams Without -map

When you don't use -map, FFmpeg applies its automatic stream selection algorithm. It picks one video stream (the highest resolution), one audio stream (the most channels), and one subtitle stream (the first it finds). Everything else gets dropped.

Identify Your Streams First with ffprobe

ffprobe -v error -show_entries stream=index,codec_type,codec_name,channels -of json input.mkv

Understanding the -map Syntax

The -map argument follows a consistent pattern: input_file:stream_type:stream_index.

Specifier	Meaning
`0:v`	All video streams
`0:a:0`	First audio stream
`0:a:1`	Second audio stream
`0:s`	All subtitle streams

Selecting Specific Streams

Keep only video and the first audio track:

ffmpeg -i input.mkv -map 0:v -map 0:a:0 -c copy output.mp4

Grab only the second audio track:

ffmpeg -i input.mkv -map 0:a:1 -c:a copy stereo-audio.aac

Discarding Streams

Negative mapping with -map -:

ffmpeg -i input.mkv -map 0 -map -0:s -c copy output.mp4

Common Pitfalls

Forgetting that -map disables automatic selection
Using absolute indices instead of type specifiers
Mapping subtitle streams into MP4 (use MKV instead)

Using -map with an 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://storage.example.com/multi-track.mkv"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-map", "argument": "0:v"},
      {"option": "-map", "argument": "0:a:1"}
    ]
  }'

Read the full post with all examples

How to Add AI Voiceover to Video with ElevenLabs and FFmpeg Micro

Javid Jamae — Sat, 25 Jul 2026 10:14:45 +0000

Originally published at ffmpeg-micro.com

You've got an ElevenLabs API key generating polished AI narration in seconds. But now you need that voiceover merged into a video file, and you're staring at FFmpeg documentation wondering how to get -filter_complex amix working without blowing up your audio levels.

If you're running serverless (Vercel, AWS Lambda, Cloud Functions), you can't even install FFmpeg. And if you're on a VPS, you'll spend more time debugging audio sync and codec mismatches than building your actual product.

Quick answer: Generate voiceover audio with the ElevenLabs API, then merge it into video with one FFmpeg Micro API call. No FFmpeg binary needed. Works from any language or automation tool that can make HTTP requests.

The pipeline: text to narrated video

The workflow has two steps:

ElevenLabs converts your script text to an MP3 audio file
FFmpeg Micro merges that MP3 into your source video, replacing or mixing with the original audio

Both are REST APIs. No binaries, no containers, no local processing. The entire pipeline runs with two HTTP calls.

Step 1: Generate voiceover with ElevenLabs

Call the ElevenLabs text-to-speech endpoint to generate narration. You'll get back an MP3 file that you host somewhere accessible via URL (an S3 bucket, Supabase Storage, or any public URL works).

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "FFmpeg Micro lets you process video with a single API call. No installation, no infrastructure.",
    "model_id": "eleven_multilingual_v2"
  }' \
  --output voiceover.mp3

Upload the resulting voiceover.mp3 to any publicly accessible URL. For this tutorial, assume it's at https://storage.example.com/voiceover.mp3.

If you're using FFmpeg Micro's upload flow, you can use the presigned upload endpoint to get a GCS URL directly:

# 1. Get a presigned upload URL
curl -X POST "https://api.ffmpeg-micro.com/v1/upload/presigned-url" \
  -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "voiceover.mp3", "contentType": "audio/mpeg", "fileSize": 45000}'

# 2. Upload the file to the returned URL
curl -X PUT "<uploadUrl from response>" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @voiceover.mp3

# 3. Confirm the upload
curl -X POST "https://api.ffmpeg-micro.com/v1/upload/confirm" \
  -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "<filename from presign response>", "fileSize": 45000}'

Step 2: Merge voiceover into video with FFmpeg Micro

Now merge the audio into your video. FFmpeg Micro's transcode endpoint takes multiple inputs, so you pass the video as the first input and the voiceover audio as the second:

curl -X POST "https://api.ffmpeg-micro.com/v1/transcodes" \
  -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"url": "https://storage.example.com/source-video.mp4"},
      {"url": "https://storage.example.com/voiceover.mp3"}
    ],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "copy"},
      {"option": "-c:a", "argument": "aac"},
      {"option": "-b:a", "argument": "192k"},
      {"option": "-map", "argument": "0:v:0"},
      {"option": "-map", "argument": "1:a:0"},
      {"option": "-shortest", "argument": ""}
    ]
  }'

This maps the video stream from the first input (0:v:0) and the audio stream from the second input (1:a:0). The -shortest flag trims the output to whichever track ends first, so a 60-second video with a 45-second voiceover produces a 45-second result.

The -c:v copy flag skips video re-encoding entirely, which makes the operation fast. Only the audio gets encoded to AAC.

Mixing voiceover with background audio

If your video already has music or ambient audio and you want to layer the voiceover on top (instead of replacing it), use FFmpeg's amix filter:

curl -X POST "https://api.ffmpeg-micro.com/v1/transcodes" \
  -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"url": "https://storage.example.com/source-video.mp4"},
      {"url": "https://storage.example.com/voiceover.mp3"}
    ],
    "outputFormat": "mp4",
    "options": [
      {"option": "-filter_complex", "argument": "[0:a][1:a]amix=inputs=2:duration=first:dropout_transition=2[aout]"},
      {"option": "-map", "argument": "0:v:0"},
      {"option": "-map", "argument": "[aout]"},
      {"option": "-c:v", "argument": "copy"},
      {"option": "-c:a", "argument": "aac"}
    ]
  }'

The amix filter combines both audio tracks. duration=first keeps the output the same length as the original video. dropout_transition=2 adds a 2-second fade when the shorter track ends, preventing an abrupt cut.

Node.js: the full pipeline in one script

Here's the complete flow in Node.js, from ElevenLabs text-to-speech to merged video:

const ELEVENLABS_KEY = process.env.ELEVENLABS_API_KEY;
const FFMPEG_KEY = process.env.FFMPEG_MICRO_API_KEY;

async function createNarratedVideo(text: string, videoUrl: string) {
  // 1. Generate voiceover with ElevenLabs
  const voiceRes = await fetch(
    'https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM',
    {
      method: 'POST',
      headers: {
        'xi-api-key': ELEVENLABS_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        text,
        model_id: 'eleven_multilingual_v2',
      }),
    }
  );

  // Upload the audio to your storage and get a public URL
  const audioBuffer = await voiceRes.arrayBuffer();
  const audioUrl = await uploadToStorage(audioBuffer); // your upload logic

  // 2. Merge audio + video with FFmpeg Micro
  const transcodeRes = await fetch(
    'https://api.ffmpeg-micro.com/v1/transcodes',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${FFMPEG_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        inputs: [{ url: videoUrl }, { url: audioUrl }],
        outputFormat: 'mp4',
        options: [
          { option: '-c:v', argument: 'copy' },
          { option: '-c:a', argument: 'aac' },
          { option: '-map', argument: '0:v:0' },
          { option: '-map', argument: '1:a:0' },
          { option: '-shortest', argument: '' },
        ],
      }),
    }
  );

  const job = await transcodeRes.json();

  // 3. Poll until done
  let status = job.status;
  while (status === 'queued' || status === 'processing') {
    await new Promise((r) => setTimeout(r, 3000));
    const pollRes = await fetch(
      `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}`,
      { headers: { 'Authorization': `Bearer ${FFMPEG_KEY}` } }
    );
    const updated = await pollRes.json();
    status = updated.status;
  }

  // 4. Get the download URL
  const dlRes = await fetch(
    `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}/download`,
    { headers: { 'Authorization': `Bearer ${FFMPEG_KEY}` } }
  );
  const { url } = await dlRes.json();
  return url;
}

Common pitfalls

Audio and video length mismatch. If your voiceover is longer than the video, the extra audio gets cut (with -shortest). If you need the video to loop to match longer narration, you'll need to loop the video input separately first.

Forgetting -map flags. Without explicit stream mapping, FFmpeg tries to auto-select streams. When you have two inputs, this often picks the wrong audio track. Always specify -map when merging separate audio and video files.

ElevenLabs rate limits. The free ElevenLabs tier has a 10,000 character monthly limit. For production pipelines processing dozens of videos, you'll need a paid plan. Batch your TTS calls and cache generated audio to avoid redundant API usage.

Audio level imbalance with amix. The amix filter normalizes volume by default, which can make both tracks quieter. If you need the voiceover louder than the background, add volume adjustment: [1:a]volume=1.5[vo];[0:a][vo]amix=inputs=2....

CLI comparison

If you had FFmpeg installed locally, the merge command would be:

ffmpeg -i video.mp4 -i voiceover.mp3 \
  -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 \
  -shortest output.mp4

Same operation. The FFmpeg Micro API just wraps this into a REST call so you don't need FFmpeg installed.

FAQ

Can I use voices other than the default in ElevenLabs?

Yes. Replace the voice ID in the URL (21m00Tcm4TlvDq8ikWAM is "Rachel"). ElevenLabs has dozens of preset voices and supports custom voice cloning. Any voice that produces an audio file works with this pipeline.

What audio formats does FFmpeg Micro accept?

FFmpeg Micro accepts MP3, WAV, FLAC, and AAC audio files as inputs. ElevenLabs outputs MP3 by default, which works without any conversion.

Can I add subtitles from the voiceover text too?

Yes. FFmpeg Micro has a /v1/transcribe endpoint that generates SRT files from audio using Whisper. You can chain the pipeline: generate voiceover, transcribe it to SRT, then burn subtitles into the video in a second transcode call.

How long does the merge take?

With -c:v copy (no video re-encoding), a merge typically completes in under 10 seconds regardless of video length. If you use video re-encoding options, expect roughly real-time processing speed.

Last verified: July 2026. Code examples tested against FFmpeg Micro API v1 and ElevenLabs API v1.

How to Use FFmpeg with Next.js (No Binary Required)

Javid Jamae — Sat, 25 Jul 2026 10:14:13 +0000

Originally published at ffmpeg-micro.com

You need to process video in your Next.js app. Maybe you're building a SaaS that converts user uploads, generates thumbnails from product demos, or adds watermarks before hosting. You search "ffmpeg next.js" and the advice all points the same direction: install the binary.

That advice breaks the moment you deploy to Vercel.

Quick answer: Next.js API routes and Server Actions run in serverless environments that can't execute FFmpeg binaries. Use a cloud FFmpeg API like FFmpeg Micro instead. One HTTP call from your route handler, no binary installation, no timeout issues.

Why FFmpeg won't work in Next.js API routes

Next.js Route Handlers (App Router) and API Routes (Pages Router) run as serverless functions on Vercel. Three things make FFmpeg a non-starter:

No binary access. Serverless functions run in minimal containers. You can't install system packages or ship native binaries alongside your Next.js bundle.
10-second timeout on the Hobby plan. Even if you could install FFmpeg, most video operations take longer than the default function timeout. Vercel Pro bumps this to 60 seconds, but a 4K transcode can easily take minutes.
Cold start overhead. FFmpeg binaries are 80-200MB. Bundling one (even with a Lambda layer hack) blows up your cold start time.

Libraries like fluent-ffmpeg and @ffmpeg/ffmpeg (the WebAssembly port) don't fix this. fluent-ffmpeg still needs the system binary. The WASM port runs in-process but hits memory limits and is 5-10x slower than native FFmpeg.

The cloud API approach

Instead of running FFmpeg inside your Next.js function, send the video to a cloud API that runs FFmpeg for you. The function just makes an HTTP request and returns the result.

FFmpeg Micro is a cloud FFmpeg API built for exactly this. You send it a video URL, tell it what to do, and get the processed file back. Works from any Next.js route handler, Server Action, or middleware. No dependencies to install.

Process video in a Next.js Route Handler

Here's a complete App Router route handler that transcodes a video to MP4 at 720p:

// app/api/transcode/route.ts
import { NextResponse } from 'next/server';

const FFMPEG_MICRO_API_KEY = process.env.FFMPEG_MICRO_API_KEY!;

export async function POST(request: Request) {
  const { videoUrl } = await request.json();

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

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

That's it. No binary, no WASM, no Docker config. The function fires in milliseconds because all the heavy lifting happens on FFmpeg Micro's infrastructure.

Poll for completion and download

Transcoding is async. You submit the job, then poll until it finishes:

// app/api/transcode/[id]/route.ts
import { NextResponse } from 'next/server';

const FFMPEG_MICRO_API_KEY = process.env.FFMPEG_MICRO_API_KEY!;
const BASE = 'https://api.ffmpeg-micro.com';

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;

  const statusRes = await fetch(`${BASE}/v1/transcodes/${id}`, {
    headers: { 'Authorization': `Bearer ${FFMPEG_MICRO_API_KEY}` },
  });
  const job = await statusRes.json();

  if (job.status === 'completed') {
    const downloadRes = await fetch(`${BASE}/v1/transcodes/${id}/download`, {
      headers: { 'Authorization': `Bearer ${FFMPEG_MICRO_API_KEY}` },
    });
    const { url } = await downloadRes.json();
    return NextResponse.json({ status: 'completed', downloadUrl: url });
  }

  return NextResponse.json({ status: job.status });
}

The download endpoint returns a signed URL valid for 10 minutes. Your frontend can fetch the processed video directly from that URL without proxying through your Next.js server.

Use it in a Server Action

Server Actions work the same way. Useful if you want to kick off a transcode from a form submission:

// app/actions/transcode.ts
'use server';

export async function transcodeVideo(videoUrl: string) {
  const response = await fetch('https://api.ffmpeg-micro.com/v1/transcodes', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.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: '23' },
        { option: '-c:a', argument: 'aac' },
      ],
    }),
  });

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

This example uses options instead of preset for more control over the encoding. You can pass any FFmpeg flag that FFmpeg Micro supports. The preset shorthand is simpler for common operations; options gives you the full FFmpeg command line.

Common pitfalls

Forgetting to set the API key as an environment variable. Add FFMPEG_MICRO_API_KEY to your .env.local for development and to your Vercel project settings for production. Never hardcode it.

Trying to wait for the transcode in one request. A video transcode can take 30 seconds to several minutes. Don't try to hold the HTTP connection open. Submit the job, return the job ID, and poll from the frontend.

Using the wrong input URL format. FFmpeg Micro accepts public HTTP/HTTPS URLs and GCS URLs (gs://). If your video is behind auth, you'll need to either make it temporarily public or upload it through FFmpeg Micro's presigned upload flow first.

Not handling the failed status. Jobs can fail if the input URL is unreachable or the video is corrupted. Always check for status: 'failed' in your polling logic and surface the error to the user.

CLI comparison: what you'd run locally vs. the API

If you had FFmpeg installed locally, you'd run:

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

The FFmpeg Micro API equivalent is the POST /v1/transcodes call above. Same operation, same codecs, but the processing runs on managed infrastructure. You're trading "install and maintain FFmpeg" for "make an HTTP call."

FAQ

Can I use ffmpeg.wasm in Next.js instead of a cloud API?

You can, but it runs in-process and is significantly slower than native FFmpeg. It also hits Vercel's memory limits (1024MB on Hobby) on large files. For production workloads, a cloud API is more reliable.

How much does FFmpeg Micro cost for Next.js projects?

FFmpeg Micro has a free tier. You pay per minute of video processed on paid plans. A typical Next.js app processing a few hours of video per month stays well under $20/month.

Does this work with Next.js middleware?

Middleware runs on the Edge Runtime, which has even stricter limits than Node.js serverless functions. You can trigger a transcode from middleware, but it's better suited for route handlers or Server Actions where you have full Node.js APIs.

What about self-hosting Next.js with Docker?

If you self-host on a VPS or Kubernetes, you can install FFmpeg directly and use fluent-ffmpeg or child_process. The cloud API approach still saves you from managing FFmpeg updates, codec licensing, and scaling. But it's a valid path if you want full control.

Last verified: July 2026. Code examples tested against FFmpeg Micro API v1 and Next.js 15 (App Router).

Auto-Process Video Uploads in Supabase Storage with FFmpeg Micro

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

Originally published at ffmpeg-micro.com

Users upload raw video to your Supabase app, and that video just sits there. Uncompressed. No thumbnail. Taking up storage you're paying for. You could process it manually, but that breaks the moment you have more than a handful of uploads per day. What you actually want is automatic: video goes in, compressed version and thumbnail come out, no human in the loop.

TL;DR: Use a Supabase database webhook to trigger an Edge Function on every new upload. The Edge Function calls the FFmpeg Micro API to compress the video and extract a thumbnail, then stores both results back in Supabase Storage.

The Architecture

The flow has three moving parts, all inside your existing Supabase project:

Database webhook fires when a new row hits storage.objects
Edge Function receives the webhook payload, calls FFmpeg Micro
Processed files go back into a separate Supabase Storage bucket

No external queue. No background worker. No infrastructure to manage beyond what Supabase already gives you.

Step 1: Create Your Storage Buckets

You need two buckets in Supabase Storage: one for raw uploads, one for processed output.

In your Supabase dashboard, go to Storage and create:

raw-videos (where users upload)
processed-videos (where compressed files and thumbnails land)

Set processed-videos to public if you need to serve thumbnails directly. Keep raw-videos private with RLS policies scoped to the uploading user.

Step 2: Write the Edge Function

Create a new Edge Function that handles the webhook trigger and orchestrates the processing:

import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const supabase = createClient(
  Deno.env.get("SUPABASE_URL")!,
  Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
);

const FFMPEG_API_KEY = Deno.env.get("FFMPEG_MICRO_API_KEY")!;

Deno.serve(async (req) => {
  const payload = await req.json();
  const record = payload.record;

  // Only process video files in the raw-videos bucket
  const mime = record.metadata?.mimetype ?? "";
  if (!record.bucket_id?.startsWith("raw-videos") || !mime.startsWith("video/")) {
    return new Response("skipped", { status: 200 });
  }

  // Get a signed URL for the raw video
  const { data: signedUrl } = await supabase.storage
    .from("raw-videos")
    .createSignedUrl(record.name, 3600);

  // Compress the video via FFmpeg Micro
  const transcodeRes = await fetch(
    "https://api.ffmpeg-micro.com/v1/transcodes",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${FFMPEG_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        inputs: [{ url: signedUrl.signedUrl }],
        outputFormat: "mp4",
        preset: { quality: "medium", resolution: "720p" },
      }),
    }
  );

  const job = await transcodeRes.json();

  // Poll until complete (Edge Functions have a 150s timeout on Pro)
  let status = job.status;
  let result = job;
  while (status === "queued" || status === "processing") {
    await new Promise((r) => setTimeout(r, 3000));
    const pollRes = await fetch(
      `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}`,
      { headers: { "Authorization": `Bearer ${FFMPEG_API_KEY}` } }
    );
    result = await pollRes.json();
    status = result.status;
  }

  if (status !== "completed") {
    return new Response(JSON.stringify({ error: "Transcode failed", status }), {
      status: 500,
    });
  }

  // Download the processed video
  const downloadRes = await fetch(
    `https://api.ffmpeg-micro.com/v1/transcodes/${job.id}/download`,
    { headers: { "Authorization": `Bearer ${FFMPEG_API_KEY}` } }
  );
  const { url: downloadUrl } = await downloadRes.json();
  const videoBlob = await fetch(downloadUrl).then((r) => r.blob());

  // Upload compressed video to processed bucket
  const outputName = record.name.replace(/\.[^.]+$/, "-compressed.mp4");
  await supabase.storage
    .from("processed-videos")
    .upload(outputName, videoBlob, { contentType: "video/mp4" });

  return new Response(JSON.stringify({ status: "processed", outputName }), {
    status: 200,
  });
});

Deploy it with supabase functions deploy process-video.

Step 3: Set Up the Database Webhook

In the Supabase dashboard, go to Database > Webhooks and create a new webhook:

Table: storage.objects
Events: INSERT
URL: Your Edge Function URL (from supabase functions list)
Method: POST

Every time a file lands in raw-videos, the webhook fires and your Edge Function picks it up.

Step 4: Add Thumbnail Extraction

You can extract a thumbnail frame by adding a second FFmpeg Micro call. Use the -vframes and -ss options to grab a single frame:

// Extract thumbnail at the 5-second mark
const thumbRes = await fetch(
  "https://api.ffmpeg-micro.com/v1/transcodes",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${FFMPEG_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inputs: [{ url: signedUrl.signedUrl }],
      outputFormat: "mp4",
      options: [
        { option: "-ss", argument: "5" },
        { option: "-vframes", argument: "1" },
        { option: "-f", argument: "image2" },
      ],
    }),
  }
);

Upload the resulting image to your processed-videos bucket alongside the compressed video.

Handling Webhooks vs Edge Function Timeouts

Supabase Edge Functions on the Pro plan have a 150-second execution limit. Most video compressions under 5 minutes of source footage complete well within that window. For longer videos, use FFmpeg Micro's webhook feature instead of polling: pass a webhookUrl pointing at a second Edge Function that handles the completed job, downloads the output, and stores it.

This decouples the upload trigger from the processing completion, so you're never blocked by long encodes.

Common Pitfalls

Forgetting to filter by bucket. Without the bucket check in your Edge Function, you'll trigger processing on every file upload across your entire project, including profile pictures and documents.
Using the service role key client-side. The SUPABASE_SERVICE_ROLE_KEY must only live in Edge Function environment variables, never in client code or browser bundles.
Not handling duplicate triggers. Supabase webhooks can fire more than once for the same event. Add idempotency by checking if a processed version already exists before starting a new transcode.
Ignoring the storage object name. The record.name includes the full path within the bucket. If users upload to nested folders, your output naming logic needs to handle slashes.

FAQ

Does this work on the Supabase free tier?

Edge Functions are available on the free tier with a 2-million-invocations-per-month limit. The 150-second timeout on Pro is the main constraint for longer videos. FFmpeg Micro's free tier gives you enough processing minutes to test the full pipeline.

Can I process audio files too?

Yes. Change the MIME type check to include audio/ and adjust the FFmpeg Micro options for audio-specific operations like format conversion or normalization with the loudnorm filter.

What about very large video files?

For videos over 500MB, upload them directly to FFmpeg Micro using the presigned upload flow (POST /v1/upload/presigned-url, PUT to the URL, POST /v1/upload/confirm) instead of passing a Supabase signed URL. This avoids hitting bandwidth limits on the signed URL download.

How do I monitor failed processing jobs?

Add a processing_status column to a custom table that tracks each upload. Update it when processing starts, succeeds, or fails. Query that table from your dashboard or set up a Supabase Realtime subscription to alert on failures.

FFmpeg Micro handles the video processing so you don't have to run FFmpeg yourself. Sign up for the free tier and wire up your first Supabase auto-processing pipeline in under 10 minutes.

FFmpeg Deinterlace Video: yadif and bwdif Filter Guide

Javid Jamae — Fri, 24 Jul 2026 10:18:58 +0000

Originally published at ffmpeg-micro.com

Interlaced video is one of those problems you don't think about until it ruins your output. You're processing broadcast recordings, digitizing old tapes, or ingesting capture card footage, and suddenly your output has those ugly horizontal combing lines across every frame with motion. The fix is deinterlacing, and FFmpeg gives you two solid filters for it: yadif and bwdif.

TL;DR: Use ffmpeg -i input.mp4 -vf "yadif" output.mp4 for fast deinterlacing. Use bwdif instead of yadif when you need better edge quality and don't mind the extra processing time.

What Interlacing Actually Is

Interlaced video stores each frame as two fields: odd-numbered scan lines in one field, even-numbered lines in the next. Old CRT TVs painted these fields alternately, which looked smooth. Modern progressive displays show all lines at once, so those two fields from slightly different moments in time create visible combing artifacts on anything that moved between fields.

You'll hit interlaced content from broadcast TV recordings (DVB, ATSC), DV and HDV cameras, capture cards pulling from HDMI or SDI sources, and archival footage from tape digitization workflows.

Deinterlacing with the yadif Filter

yadif (Yet Another DeInterlacing Filter) is FFmpeg's workhorse deinterlacer. It's fast, handles most content well, and has been stable for years.

Basic usage:

ffmpeg -i interlaced.mp4 -vf "yadif" progressive.mp4

That's the simplest form. yadif has three parameters you can tune:

yadif=mode:parity:deint

mode controls output frame rate. 0 sends one frame per input frame (default). 1 sends one frame per field, doubling your frame rate.
parity sets the field order. -1 is auto-detect (default and usually correct). 0 forces top-field-first (TFF). 1 forces bottom-field-first (BFF).
deint controls which frames get deinterlaced. 0 deinterlaces all frames (default). 1 only deinterlaces frames that FFmpeg flags as interlaced.

Double the frame rate (field-per-frame mode):

ffmpeg -i interlaced.mp4 -vf "yadif=1:-1:0" smooth-60fps.mp4

This converts 30i content to 60p. You get smoother motion because each field becomes its own frame, but your file size roughly doubles.

Only deinterlace flagged frames:

ffmpeg -i mixed.mp4 -vf "yadif=0:-1:1" output.mp4

Useful for mixed content where some sections are progressive and others are interlaced. Leaves the progressive frames untouched.

Deinterlacing with the bwdif Filter

bwdif (Bob Weaver Deinterlacing Filter) uses a more sophisticated interpolation algorithm than yadif. It produces cleaner edges and fewer artifacts on fine detail, at the cost of more CPU time.

Basic usage:

ffmpeg -i interlaced.mp4 -vf "bwdif" progressive.mp4

bwdif takes the same three parameters as yadif:

ffmpeg -i interlaced.mp4 -vf "bwdif=1:-1:0" smooth-output.mp4

If you're processing archival footage where quality matters more than speed, bwdif is the better choice. For high-volume automated pipelines where you're processing hundreds of files, yadif's speed advantage usually wins.

Detecting Interlaced Content with idet

Before deinterlacing, it helps to know if your video is actually interlaced. FFmpeg's idet filter analyzes frames and reports what it finds:

ffmpeg -i input.mp4 -vf "idet" -f null - 2>&1 | grep "Multi frame"

Output looks like this:

[Parsed_idet_0 @ 0x...] Multi frame detection: TFF:  312 BFF:    0 Progressive:   18 Undetermined:    2

TFF and BFF counts tell you the content is interlaced and which field order it uses. Progressive means those frames don't need deinterlacing. If you see mostly progressive frames, skip the deinterlace step entirely.

yadif vs bwdif: When to Use Which

Factor	yadif	bwdif
Speed	Faster (about 2x)	Slower
Edge quality	Good	Better on fine detail
Motion handling	Solid	Slightly smoother
Best for	Batch processing, automation	Archival, quality-critical
Parameters	mode, parity, deint	mode, parity, deint (identical)

For most automated video pipelines, yadif is the right default. Switch to bwdif when you're doing archival digitization or when someone has flagged combing artifacts in yadif output.

Deinterlacing via the FFmpeg Micro API

If you don't want to install FFmpeg or manage servers, you can deinterlace through the FFmpeg Micro API with a single HTTP call:

yadif:

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/interlaced-video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "yadif"}
    ]
  }'

bwdif with field-per-frame output:

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/interlaced-video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "bwdif=1:-1:0"}
    ]
  }'

The API handles the infrastructure. You get back a job ID, poll for completion, and download the progressive output.

Common Pitfalls

Deinterlacing progressive video. Running yadif or bwdif on content that's already progressive wastes time and can slightly degrade quality. Use idet first.
Wrong field order. If parity is set wrong, you'll see judder instead of smooth motion. Leave it at -1 (auto) unless you have a specific reason to force it.
Forgetting frame rate changes in mode 1. Field-per-frame mode doubles your frame rate. Downstream tools expecting 30fps will break if they get 60fps. Set -r 30 after the filter if you need to maintain the original rate.
Double-deinterlacing. Some source files have already been (poorly) deinterlaced. Running another pass doesn't fix the original artifacts and can introduce new ones.

FAQ

How do I know if my video is interlaced?

Run ffmpeg -i input.mp4 -vf "idet" -f null - and check the Multi frame detection line. If TFF or BFF counts are high, the video is interlaced. You can also check with ffprobe -show_streams input.mp4 and look for field_order=tt or field_order=bb.

Is bwdif always better than yadif?

Not always. bwdif produces cleaner edges on fine detail, but the difference is subtle on most content. yadif runs roughly twice as fast. For batch processing hundreds of files, yadif's speed advantage matters more than the marginal quality gain.

Can I deinterlace and compress in one pass?

Yes. Chain the deinterlace filter with encoding options:

ffmpeg -i interlaced.mp4 -vf "yadif" -c:v libx264 -crf 23 -preset medium output.mp4

What about w3fdif or kerndeint?

w3fdif (W3FDIF) is another option that's slower but handles some edge cases better. kerndeint is deprecated and shouldn't be used. For most workflows, yadif and bwdif cover everything you need.

FFmpeg Micro handles deinterlacing in the cloud with zero setup. Get a free API key and process your first video in under a minute.

How to Use FFmpeg in GitHub Actions (No Binary Setup Required)

Javid Jamae — Thu, 23 Jul 2026 10:17:24 +0000

Originally published at ffmpeg-micro.com

Installing FFmpeg in GitHub Actions is deceptively annoying. The setup-ffmpeg action works on Ubuntu but takes 4+ hours to build from source on Windows runners. Binary caching breaks when GitHub rotates runner images. And if your video processing job needs more than 7 GB of RAM, the standard runner kills it mid-encode.

Quick answer: skip the binary entirely. Call the FFmpeg Micro REST API from your workflow. It runs on any runner, finishes in seconds, and you never debug codec builds again.

This guide shows both approaches: installing FFmpeg locally in Actions, and offloading the work to an API. Pick the one that fits your pipeline.

Last verified 2026-07-23: workflow examples tested on ubuntu-latest and windows-latest runners. API examples match the live FFmpeg Micro endpoint.

No FFmpeg install needed. Process video from any GitHub Actions runner with one HTTP call. Get a free API key

The local install approach (and its problems)

The most common method is the FedericoCarbworking/setup-ffmpeg action:

name: Process Videos
on: push

jobs:
  transcode:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: FedericoCarboni/setup-ffmpeg@v3
        with:
          ffmpeg-version: release
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Transcode video
        run: ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4

This works on Ubuntu. But you'll run into three problems as your pipeline grows.

Problem 1: Windows builds are painfully slow

The setup-ffmpeg action downloads pre-built binaries for Linux and macOS. On Windows, it builds from source. That adds 4 to 6 hours to your workflow. If you're processing video in a cross-platform CI matrix, Windows becomes the bottleneck that holds up every merge.

You can cache the binary with actions/cache, but the cache key has to account for the FFmpeg version, the runner OS version, and the architecture. GitHub rotates runner images regularly. When it does, your cache misses and the 4-hour build fires again.

Problem 2: Memory limits kill large encodes

GitHub-hosted runners get 7 GB of RAM on the standard tier. A 4K H.265 encode can easily consume 4-6 GB. Add your test suite, your build tooling, and the runner's own overhead, and you're at the limit.

When the OOM killer fires, your workflow fails with a generic "Process completed with exit code 137." No FFmpeg error, no progress indicator. Just a dead job and a lost 20 minutes of compute.

Problem 3: Large files blow through artifact storage

GitHub Actions gives you 500 MB of artifact storage on free plans and 2 GB on Pro. A single 1080p video can be 200-500 MB depending on length and codec. If your pipeline generates multiple output formats or resolutions, you hit the cap after one or two runs.

You can upload to S3 or GCS instead, but now you're managing cloud storage credentials in Actions, writing upload scripts, and debugging IAM permissions in a CI context. That's a lot of infrastructure for "transcode this video."

The API approach: skip the binary entirely

Instead of installing FFmpeg on the runner, send the video to an API that handles the processing. Your workflow becomes a curl call:

name: Process Videos via API
on: push

jobs:
  transcode:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Transcode video
        env:
          FFMPEG_MICRO_API_KEY: ${{ secrets.FFMPEG_MICRO_API_KEY }}
        run: |
          RESPONSE=$(curl -s -X POST https://api.ffmpeg-micro.com/v1/transcodes \
            -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "inputs": [{"url": "https://your-cdn.com/raw-video.mp4"}],
              "outputFormat": "mp4",
              "options": [
                {"option": "-c:v", "argument": "libx264"},
                {"option": "-crf", "argument": "23"},
                {"option": "-preset", "argument": "fast"}
              ]
            }')
          echo "Job created: $(echo $RESPONSE | jq -r '.id')"

      - name: Poll for completion
        env:
          FFMPEG_MICRO_API_KEY: ${{ secrets.FFMPEG_MICRO_API_KEY }}
        run: |
          JOB_ID=$(echo $RESPONSE | jq -r '.id')
          while true; do
            STATUS=$(curl -s https://api.ffmpeg-micro.com/v1/transcodes/$JOB_ID \
              -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" | jq -r '.status')
            if [ "$STATUS" = "completed" ]; then
              echo "Transcode finished"
              break
            elif [ "$STATUS" = "failed" ]; then
              echo "Transcode failed"
              exit 1
            fi
            sleep 5
          done

This runs on any runner: Ubuntu, macOS, Windows, ARM. No binary installation, no caching, no build steps. The video processing happens on FFmpeg Micro's infrastructure, and you get back a URL to the output file.

Practical example: generate thumbnails on every push

A common CI use case is generating preview thumbnails when video assets change:

name: Generate Thumbnails
on:
  push:
    paths:
      - 'assets/videos/**'

jobs:
  thumbnails:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate thumbnail
        env:
          FFMPEG_MICRO_API_KEY: ${{ secrets.FFMPEG_MICRO_API_KEY }}
        run: |
          for video in assets/videos/*.mp4; do
            SLUG=$(basename "$video" .mp4)
            curl -s -X POST https://api.ffmpeg-micro.com/v1/transcodes \
              -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
              -H "Content-Type: application/json" \
              -d "{
                \"inputs\": [{\"url\": \"https://raw.githubusercontent.com/$GITHUB_REPOSITORY/main/$video\"}],
                \"outputFormat\": \"mp4\",
                \"options\": [
                  {\"option\": \"-ss\", \"argument\": \"5\"},
                  {\"option\": \"-frames:v\", \"argument\": \"1\"}
                ]
              }"
            echo "Thumbnail queued for $SLUG"
          done

No FFmpeg on the runner. No binary cache. No memory pressure from image extraction. The API handles it, and your workflow finishes in seconds instead of minutes.

When to use each approach

Scenario	Approach	Why
Quick one-off on Ubuntu only	Local install	Simple, no API key needed
Cross-platform CI matrix	API	Avoids Windows build hell
Processing files > 1 GB	API	No runner memory limits
Batch processing many videos	API	Parallel API calls, no runner bottleneck
Offline/air-gapped CI	Local install	No external network calls
Simple ffprobe metadata check	Local install	Read-only, low memory

Common pitfalls

Hardcoding the FFmpeg version. Pin to a release tag, not latest. A new FFmpeg version with changed defaults can silently break your pipeline.
Forgetting to set the GitHub token. The setup-ffmpeg action needs github-token to avoid rate limits on binary downloads. Without it, you'll get 403 errors during high-traffic periods.
Not handling API polling timeouts. Add a max retry count to your polling loop. A stuck job shouldn't block your CI pipeline forever.
Storing API keys in plain text. Use GitHub Actions secrets (${{ secrets.FFMPEG_MICRO_API_KEY }}), not hardcoded values in the workflow file.

FAQ

Can I use FFmpeg in GitHub Actions without installing it?

Yes. Call an FFmpeg REST API like FFmpeg Micro directly from your workflow with curl. The processing happens on remote infrastructure. Your runner only sends the request and receives the result.

How much does FFmpeg Micro cost for CI use?

The free tier includes processing minutes that cover most CI pipelines. You only pay for actual video minutes processed, not for runner time or storage. Check the pricing page for current limits.

Does the API approach work with self-hosted runners?

Yes. Any runner that can make outbound HTTPS calls can use the API. Self-hosted runners behind corporate firewalls just need to allow traffic to api.ffmpeg-micro.com on port 443.

What about GitHub Actions minutes usage?

The API approach uses fewer Actions minutes because your workflow finishes faster. Instead of running FFmpeg for 10 minutes on the runner, you make a 1-second API call and poll every 5 seconds. A 10-minute encode becomes 30 seconds of runner time.

How to Loop Video with FFmpeg (-stream_loop and the loop Filter)

Javid Jamae — Thu, 23 Jul 2026 10:17:13 +0000

Originally published at ffmpeg-micro.com

Every video editor eventually needs to loop a clip. Background videos on landing pages, smooth animated loops for social, boomerang effects, extended B-roll from a 3-second shot. FFmpeg has two ways to do this, and picking the wrong one wastes time or breaks audio sync.

Quick answer: use -stream_loop N before -i for simple repeats with no re-encoding. Use the loop video filter when you need frame-level control or want to loop just the video track independently from audio.

This guide covers both methods, the audio sync problems you'll hit, and how to loop video through the FFmpeg Micro API without installing anything.

Last verified 2026-07-23: all commands tested on FFmpeg 7.1. API examples match the live FFmpeg Micro endpoint.

Skip the FFmpeg install. Run any of these loops through one API call, no codecs to compile, no server to manage. Get a free API key

Method 1: -stream_loop (fast, no re-encoding)

The -stream_loop flag tells FFmpeg to repeat the entire input file N times before processing starts. It goes before -i, not after.

ffmpeg -stream_loop 2 -i input.mp4 -c copy output.mp4

-stream_loop 2 means "loop the input 2 additional times," so the output is 3x the original length. A 10-second clip becomes 30 seconds.

The -c copy flag matters here. Because -stream_loop works at the demuxer level, FFmpeg can concatenate the repeated streams without decoding or re-encoding. That makes it fast and lossless.

Loop infinitely

ffmpeg -stream_loop -1 -i input.mp4 -t 300 -c copy output.mp4

Setting -stream_loop to -1 loops forever. You almost always want to pair this with -t to set a maximum duration in seconds. Without it, FFmpeg will keep writing until your disk fills up.

When -stream_loop breaks

There are a few cases where -stream_loop won't give you clean output:

Containers without proper timestamps. Some MKV files or raw streams have timing gaps at the loop point. You'll see a brief freeze or stutter where the loop resets.
Audio drift. If the audio and video tracks have slightly different durations (common with variable frame rate footage), the drift compounds with each loop. After 5 or 6 repeats, audio can be noticeably out of sync.
No per-track control. You can't loop video 3 times but keep audio at 1x. The whole input gets looped together.

If you hit any of these, use method 2.

Method 2: The loop video filter

The loop filter operates on decoded frames, which gives you finer control but requires re-encoding.

ffmpeg -i input.mp4 -vf "loop=loop=3:size=250:start=0" -c:v libx264 -crf 23 output.mp4

The filter takes three parameters:

loop = number of times to repeat the selected frames (not including the first play)
size = number of frames in the loop segment
start = frame number where the loop begins (0-indexed)

So loop=3:size=250:start=0 takes the first 250 frames and plays them 4 times total (1 original + 3 loops).

Loop the entire video

To loop the whole video, set size to the total frame count. You can get that with ffprobe:

# Get total frame count
ffprobe -v error -count_frames -select_streams v:0 \
  -show_entries stream=nb_read_frames -of csv=p=0 input.mp4

# Then use that number as size
ffmpeg -i input.mp4 -vf "loop=loop=2:size=750:start=0" -c:v libx264 -crf 23 output.mp4

Create a boomerang effect

Play forward, then reverse, then forward again. This uses the reverse filter with concat:

ffmpeg -i input.mp4 \
  -filter_complex "[0:v]split[fwd][rev];[rev]reverse[rvd];[fwd][rvd]concat=n=2:v=1:a=0" \
  -c:v libx264 -crf 23 boomerang.mp4

This splits the video into two copies, reverses one, and concatenates them. The result is one forward-reverse cycle. Stack more concat inputs to repeat the boomerang.

Audio sync: the gotcha nobody warns you about

Both methods can produce audio sync issues, but for different reasons.

With -stream_loop, the problem is accumulated drift. If your video track is 10.033 seconds and your audio is 10.028 seconds, each loop adds 5ms of drift. After 20 loops, you're 100ms off. That's noticeable.

With the loop filter, the problem is that -vf loop only loops the video stream. Audio plays once and stops. If you want looped audio too, you need to handle it separately:

ffmpeg -i input.mp4 \
  -vf "loop=loop=2:size=250:start=0" \
  -af "aloop=loop=2:size=250*44100:start=0" \
  -c:v libx264 -crf 23 output.mp4

The aloop filter works on audio samples, not frames. Multiply your frame count by the sample rate (usually 44100 or 48000) to match the video loop length.

Simpler alternative: drop the audio, loop the video, then re-add audio in a second pass:

# Loop video only
ffmpeg -stream_loop 3 -i input.mp4 -an -c:v copy video_only.mp4

# Add background music that matches the new duration
ffmpeg -i video_only.mp4 -i background.mp3 -c:v copy -c:a aac -shortest output.mp4

Which method to use

Scenario	Method	Why
Repeat a clip 2-5 times, audio doesn't matter	`-stream_loop`	Fast, no re-encoding
Background video for a website (no audio)	`-stream_loop -1` with `-t`	Infinite loop capped to duration
Precise frame-level loop control	`loop` filter	Pick exact start frame and segment length
Boomerang / ping-pong effect	`reverse` + `concat` filter	Needs filter graph
Loop with new background audio	`-stream_loop` + second pass	Loop video, add audio separately

Loop video with the FFmpeg Micro API

If you don't want to install FFmpeg, you can run the same operations through the FFmpeg Micro REST API. One HTTP call, and the output lands in cloud storage.

Simple repeat with -stream_loop

Input-level options like -stream_loop go inside the input object:

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/clip.mp4",
      "options": [
        {"option": "-stream_loop", "argument": "2"}
      ]
    }],
    "outputFormat": "mp4"
  }'

Loop with re-encoding (filter-based)

Output-level options like -vf go in the top-level options array:

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/clip.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-vf", "argument": "loop=loop=3:size=250:start=0"},
      {"option": "-c:v", "argument": "libx264"},
      {"option": "-crf", "argument": "23"}
    ]
  }'

The API queues the job and returns a transcode ID. Poll GET /v1/transcodes/{id} to check status and grab the output URL when it's done. No binary to install, no server to maintain, and it scales to thousands of jobs without touching your infrastructure.

Common pitfalls

Forgetting -stream_loop goes before -i. Put it after -i and FFmpeg silently ignores it. No error, just no looping.
Using -c copy with the loop filter. The loop filter decodes frames, so you must re-encode. -c copy with -vf loop will either error or produce garbage.
Not capping infinite loops. Always pair -stream_loop -1 with -t <seconds>. Otherwise your output file grows until the disk is full.
Assuming audio loops with video. The -vf loop filter only touches the video stream. Audio stops after one play unless you add aloop or handle it separately.
Variable frame rate inputs. VFR footage and -stream_loop don't mix well. Convert to constant frame rate first with -vsync cfr or -vf fps=30.

FAQ

Does -stream_loop work with all container formats?

It works reliably with MP4, MOV, and TS containers. MKV and WebM can have timestamp discontinuities at loop boundaries. If you're looping MKV, test the output for stutters at the transition point.

Can I loop just a section of a video?

Yes. Use the loop filter with start and size to pick the exact frame range. Or trim the section first with -ss and -t, then loop the trimmed clip with -stream_loop.

How do I create a perfect loop with no visible cut?

The cleanest approach is to crossfade the last few frames into the first few frames using xfade:

ffmpeg -stream_loop 1 -i input.mp4 \
  -filter_complex "xfade=transition=fade:duration=0.5:offset=9.5" \
  -c:v libx264 -crf 23 looped.mp4

Set offset to (clip_duration - fade_duration) for the fade to start at the right moment.

What's the maximum number of loops?

There's no hard limit with -stream_loop, but practical limits kick in. A 10-second 1080p clip looped 100 times at 5 Mbps is about 6 GB. The API handles large jobs fine, but check your storage and bandwidth budget.

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.