DEV Community: Javid Jamae

How to Split Video into Segments with FFmpeg (CLI + API)

Javid Jamae — Sat, 23 May 2026 10:15:08 +0000

Originally published at ffmpeg-micro.com.

You need to chop a long video into equal-length clips. Maybe you're building a social media repurposing pipeline, batch-processing uploads for a CMS, or splitting recordings into chapters. FFmpeg's segment muxer handles this, but getting it right means fighting with keyframe alignment, timestamp resets, and infrastructure you don't want to manage.

This guide covers the exact FFmpeg commands for splitting video, the flags that matter, and how to skip the server setup entirely with an API.

Quick answer

Split a video into 10-second segments with no re-encoding:

ffmpeg -i input.mp4 -c copy -f segment -segment_time 10 -reset_timestamps 1 segment_%03d.mp4

This uses the segment muxer to cut at the nearest keyframe boundary. Each output file gets its own timestamps starting at zero.

How the FFmpeg segment muxer works

The segment muxer (-f segment) tells FFmpeg to write output to multiple files instead of one. It splits based on a time interval you set with -segment_time.

ffmpeg -i input.mp4 \
  -c copy \
  -f segment \
  -segment_time 30 \
  -reset_timestamps 1 \
  output_%03d.mp4

Key flags:

-f segment activates the segment muxer
-segment_time 30 sets the target duration for each segment in seconds
-reset_timestamps 1 resets timestamps to zero for each segment (without this, players show wrong seek positions)
-c copy copies streams without re-encoding (fast, but cuts only at keyframes)
output_%03d.mp4 is the numbered output pattern (000, 001, 002, ...)

The %03d pattern in the output filename is required. FFmpeg increments the number for each new segment.

Getting a segment manifest

If your pipeline needs to know what segments were created and their exact timestamps, add -segment_list:

ffmpeg -i input.mp4 \
  -c copy \
  -f segment \
  -segment_time 30 \
  -reset_timestamps 1 \
  -segment_list segments.csv \
  -segment_list_type csv \
  segment_%03d.mp4

The CSV output looks like this:

segment_000.mp4,0.000000,30.030000
segment_001.mp4,30.030000,60.060000
segment_002.mp4,60.060000,85.418750

Each row has the filename, start time in seconds, and end time in seconds. You can also use -segment_list_type flat for just filenames or -segment_list_type ffconcat for FFmpeg concat demuxer format.

Timestamp-based filenames with strftime

For automation pipelines where you're processing videos on a schedule, timestamp-based filenames prevent collisions:

ffmpeg -i input.mp4 \
  -c copy \
  -f segment \
  -segment_time 30 \
  -reset_timestamps 1 \
  -strftime 1 \
  "clip_%Y%m%d_%H%M%S.mp4"

This produces files like clip_20260523_143000.mp4. Useful when you're processing multiple source videos into the same output directory.

The keyframe problem

When you use -c copy (stream copy, no re-encoding), FFmpeg can only cut at keyframe boundaries. If your video has keyframes every 2 seconds and you request 5-second segments, your actual segments might be 4 or 6 seconds long.

Two ways to handle this:

Accept keyframe-aligned cuts (fast, slightly imprecise):

ffmpeg -i input.mp4 -c copy -f segment -segment_time 5 -reset_timestamps 1 output_%03d.mp4

Force exact timing (requires re-encoding, 10-50x slower):

ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 \
  -force_key_frames "expr:gte(t,n_forced*5)" \
  -f segment \
  -segment_time 5 \
  -reset_timestamps 1 \
  output_%03d.mp4

The second approach re-encodes the video and inserts keyframes at exact 5-second intervals. Accurate, but dramatically slower depending on your hardware and encoding settings.

For most batch processing and content repurposing workflows, keyframe-aligned cuts are good enough.

Splitting video with the FFmpeg Micro API

Running FFmpeg on your own server means managing binaries, scaling for concurrent jobs, and handling timeouts on long videos. The FFmpeg Micro API handles the infrastructure so you can focus on your pipeline logic.

The API uses -ss (seek) and -t (duration) per transcode job, which gives you precise control over exactly what you extract from each video.

Extract a 30-second segment starting at 1 minute:

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/video.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-ss", "argument": "60"},
      {"option": "-t", "argument": "30"},
      {"option": "-c", "argument": "copy"}
    ]
  }'

The response includes a job ID you can poll:

{
  "id": "b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3",
  "status": "queued",
  "output_format": "mp4"
}

Check status and download the result:

curl https://api.ffmpeg-micro.com/v1/transcodes/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.ffmpeg-micro.com/v1/transcodes/JOB_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY"

Split a 5-minute video into 30-second segments programmatically:

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.ffmpeg-micro.com/v1"
VIDEO_URL = "https://storage.example.com/video.mp4"
SEGMENT_SECONDS = 30
TOTAL_SECONDS = 300

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

jobs = []
for start in range(0, TOTAL_SECONDS, SEGMENT_SECONDS):
    resp = requests.post(f"{BASE}/transcodes", headers=headers, json={
        "inputs": [{"url": VIDEO_URL}],
        "outputFormat": "mp4",
        "options": [
            {"option": "-ss", "argument": str(start)},
            {"option": "-t", "argument": str(SEGMENT_SECONDS)},
            {"option": "-c", "argument": "copy"}
        ]
    })
    job = resp.json()
    jobs.append(job)
    print(f"Segment {start}s-{start + SEGMENT_SECONDS}s: {job['id']}")

All 10 jobs run in parallel on cloud infrastructure. No server, no queue management, no timeout handling on your end.

Get a free API key and try splitting your first video.

Common pitfalls when splitting video

Forgetting -reset_timestamps 1. Without this flag, each segment keeps the timestamps from the original video. Players show the wrong position on the seek bar, and some players won't play the segments at all.

Audio sync drift with -c copy. Stream copy can sometimes drift audio out of sync at cut points. If you hear pops or sync issues, switch to -c:a aac to re-encode just the audio track while keeping video as copy.

Output pattern without %d. If you forget the number pattern in the output filename, FFmpeg overwrites the same file for every segment. Always include %03d or similar.

Segment time vs. actual duration. With -c copy, segments won't be exactly the duration you requested. They'll be close, but keyframe alignment means they might vary by 1-2 seconds. If you need frame-accurate cuts, you have to re-encode.

Large video timeouts. Running the segment muxer locally on a 2-hour video is fine. Running it on a server with a 30-second HTTP timeout kills the job mid-split. If you're processing long videos in a web pipeline, use an async API or background worker.

FAQ

How do I split a video into equal parts with FFmpeg?

Use the segment muxer: ffmpeg -i input.mp4 -c copy -f segment -segment_time 60 -reset_timestamps 1 part_%03d.mp4. Replace 60 with your desired segment length in seconds. Segments will be approximately equal, with variation depending on keyframe positions.

Can I split video without re-encoding?

Yes. Use -c copy with the segment muxer for near-instant splitting. The tradeoff is that cuts happen at keyframe boundaries, so segment durations won't be frame-accurate. For most batch processing and content repurposing workflows, keyframe-aligned cuts are close enough.

What's the difference between the segment muxer and using -ss with -t?

The segment muxer (-f segment) automatically splits into multiple files in a single FFmpeg pass. The -ss/-t approach extracts one specific clip per command. The segment muxer is faster for creating many segments from one video locally. The -ss/-t approach works better with APIs and cloud pipelines where each segment runs as an independent job.

Does the FFmpeg segment muxer work with audio files?

Yes. Same syntax with audio containers: ffmpeg -i podcast.mp3 -c copy -f segment -segment_time 600 chunk_%03d.mp3. This splits a podcast into 10-minute chunks without re-encoding.

How do I split video into segments with an API?

FFmpeg Micro lets you submit transcode jobs via HTTP with -ss and -t options to extract specific segments. Each job runs on cloud infrastructure with automatic scaling. Sign up for a free API key and POST to /v1/transcodes with your input URL, output format, and seek/duration options.

Last verified: May 2026 with FFmpeg 7.x and FFmpeg Micro API v1

Secure Video Transcoding API: No FFmpeg Server to Patch

Javid Jamae — Fri, 22 May 2026 10:28:05 +0000

Originally published at ffmpeg-micro.com

FFmpeg has over 100 known CVEs. If you’re running it on a server you manage, every one of those is your problem. Patching, network isolation, access control, storage permissions, log scrubbing. That’s before you write a single line of video processing code.

A managed transcoding API flips the security model. You send an HTTP request. The API processes your video on isolated infrastructure and hands back the result. Your attack surface shrinks from "an entire FFmpeg server" to "one API key."

What "secure video transcoding" actually means

Most guides about secure video transcoding focus on the wrong layer. They talk about JWT tokens and reverse proxies in front of self-hosted FFmpeg. That's bolting a lock onto a door you don't need to open.

Secure video transcoding means three things:

Transport security. Every byte moves over HTTPS. No plaintext video data on the wire.
Authentication. Only your code can trigger jobs. No anonymous access, no shared credentials.
Data lifecycle. Video files don't persist after processing unless you explicitly store them. No orphaned files in a misconfigured S3 bucket.

FFmpeg Micro covers all three by default. There's nothing to configure.

Authentication: Bearer token, one header

Every request to the FFmpeg Micro API requires a Bearer token in the Authorization header. No API key in query strings. No unsigned requests.

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",
    "preset": {"quality": "high", "resolution": "1080p"}
  }'

The API key is hashed with SHA-256 before storage. The raw key never hits a database. If someone compromises the database, they get hashes, not keys.

Compare that to self-hosted FFmpeg, where you're responsible for:

Implementing your own auth middleware
Rotating credentials
Rate limiting to prevent abuse
Logging access without leaking video URLs

With a managed API, all of that is handled. You store one API key, send one header, and you're done.

Secure file uploads: presigned URLs

Uploading video to a self-hosted FFmpeg server usually means accepting file uploads directly. That opens you to oversized payloads, malicious files, and storage exhaustion attacks.

FFmpeg Micro uses a three-step presigned URL flow instead:

Step 1: Request an upload URL

curl -X POST https://api.ffmpeg-micro.com/v1/upload/presigned-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "interview-raw.mp4",
    "contentType": "video/mp4",
    "fileSize": 52428800
  }'

The API validates the file type and size before generating the URL. Files over 2GB are rejected. Only video, audio, and image MIME types are accepted.

Step 2: Upload directly to cloud storage

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @interview-raw.mp4

Your video goes straight to Google Cloud Storage. It never passes through the API server. No bandwidth bottleneck, no server-side file handling vulnerabilities.

Step 3: Confirm the upload

curl -X POST https://api.ffmpeg-micro.com/v1/upload/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "20260522-143045-interview-raw.mp4",
    "fileSize": 52428800
  }'

The API verifies the file actually landed in storage and the size matches. If the file isn't there or the sizes don't match, the confirmation fails. No phantom references to files that don't exist.

No persistent video storage

After a transcode completes, you get a signed download URL that expires in 10 minutes:

curl https://api.ffmpeg-micro.com/v1/transcodes/JOB_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "url": "https://storage.googleapis.com/...?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=600&..."
}

That URL is time-limited and cryptographically signed. After 10 minutes, it's dead. The output files themselves are cleaned up automatically. Your video doesn't sit in someone else's storage indefinitely, waiting for a misconfigured bucket policy to expose it.

This is the opposite of how most self-hosted setups work, where output files accumulate in /tmp or an S3 bucket until someone remembers to write a cleanup cron job.

The self-hosted security burden

Running your own FFmpeg server means owning a stack of security responsibilities that have nothing to do with video processing:

FFmpeg CVEs are constant. The FFmpeg project has disclosed over 100 CVEs since 2010. Heap overflows, null pointer dereferences, out-of-bounds reads. Every one of them is a potential remote code execution if you're accepting untrusted input files. Keeping FFmpeg patched on your own server is a recurring ops task that never ends.

Storage misconfigurations are the #1 cloud data breach vector. If you're writing transcoded output to S3 or GCS, one wrong bucket policy and your customers' videos are public. AWS reports that storage misconfiguration is involved in the majority of cloud data exposures.

Network exposure. A self-hosted FFmpeg server needs inbound access to receive files and outbound access to deliver results. That's two attack surfaces to manage, plus whatever internal network the server sits on.

No isolation between jobs. On a shared FFmpeg server, one user's malformed input file could crash the process handling another user's job. Container isolation helps, but you're building and maintaining that yourself.

With a managed API, all of these are someone else's full-time job. You don't patch FFmpeg. You don't configure bucket policies. You don't manage network ACLs.

Common security pitfalls (and how to avoid them)

Leaking API keys in client-side code. Never put your FFmpeg Micro API key in frontend JavaScript. Call the API from your backend server. If you need client-side uploads, use the presigned URL flow. The upload URL is temporary and scoped to one file.

Not validating file types before upload. The presigned URL endpoint validates MIME types for you, but you should also validate on your end before sending. Don't let users upload arbitrary files to your workflow.

Ignoring download URL expiry. The signed download URLs expire in 10 minutes. Don't store them. Fetch a fresh one each time you need it. If you're passing URLs to downstream services, make sure they consume the file within the window.

Hardcoding API keys. Use environment variables. Store them in your platform's secret manager (Vercel, Railway, AWS Secrets Manager). Not in your repo, not in a config file committed to git.

FAQ

Is my video data encrypted in transit?

Yes. All FFmpeg Micro API endpoints are HTTPS-only. Video uploads go directly to Google Cloud Storage over TLS. Download URLs are also HTTPS with cryptographic signatures.

Can I restrict API access by IP address?

FFmpeg Micro authenticates by API key, not IP allowlist. For additional network-level restrictions, call the API from a backend service within your own VPC and control access at that layer.

What happens to my video files after processing?

Output files are accessible via signed URLs for 10 minutes. After that, the URLs expire. Files are cleaned up automatically. There's no long-term storage of your video content on FFmpeg Micro's infrastructure.

How do I rotate my API key?

Generate a new key from your FFmpeg Micro dashboard, update your environment variables, and the old key stops working immediately. No downtime, no overlap window where both keys are active.

Is FFmpeg Micro SOC 2 compliant?

FFmpeg Micro runs on Google Cloud Platform, which is SOC 2 Type II certified. The API layer enforces authentication, encrypted transport, and automatic data cleanup. For specific compliance questions, contact support.

Last verified: 2026-05-22 against FFmpeg Micro API v1

How to Use FFmpeg with Ruby on Rails (No Installation Required)

Javid Jamae — Thu, 21 May 2026 10:13:58 +0000

Originally published at ffmpeg-micro.com.

You need to process video in your Ruby on Rails app. Users upload clips, and you need to convert formats, resize for mobile, or extract thumbnails. You search "ruby ffmpeg" and find streamio-ffmpeg, a gem that wraps the FFmpeg binary.

It works great locally. Then you deploy to Heroku.

TL;DR: You can process video from Ruby without installing FFmpeg anywhere. Send an HTTP request to a cloud API, get results back. Works on Heroku, Render, Fly.io, or any platform that can make outbound HTTP calls.

The System Call Approach (And Why It Breaks)

The raw Ruby approach looks like this:

system("ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4")

Or with backticks for capturing output:

result = `ffmpeg -i input.mp4 -vf scale=-2:720 output.mp4 2>&1`
raise "FFmpeg failed: #{result}" unless $?.success?

On your dev machine, fine. In production:

Heroku doesn't include FFmpeg. You need a buildpack, which adds cold-start time and maintenance burden.
Render and Fly.io require custom Dockerfiles just to get the binary available.
System calls block your Puma worker. That thread is stuck until FFmpeg finishes.
You own codec updates, security patches, and temp file cleanup.

The streamio-ffmpeg Gem

streamio-ffmpeg is the most popular Ruby FFmpeg wrapper:

require "streamio-ffmpeg"

movie = FFMPEG::Movie.new("input.mp4")
movie.transcode("output.mp4", "-c:v libx264 -crf 23")

Cleaner syntax, but it still shells out to the FFmpeg binary. No binary, no transcoding. The gem hasn't had a significant update in years, and it doesn't handle async processing or cloud storage.

Processing Video via API (No FFmpeg Needed)

FFmpeg Micro is a cloud API that runs FFmpeg for you. One HTTP request from Ruby, and you get a transcoded file back. No binary, no Dockerfile, no buildpack.

With Ruby's built-in Net::HTTP:

require "net/http"
require "json"

api_key = ENV.fetch("FFMPEG_MICRO_API_KEY")
uri = URI("https://api.ffmpeg-micro.com/v1/transcodes")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{api_key}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  inputs: [{ url: "https://example.com/video.mp4" }],
  outputFormat: "mp4",
  preset: { quality: "high", resolution: "1080p" }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

job = JSON.parse(response.body)
puts "Job ID: #{job["id"]}"

If you're using Faraday (common in Rails apps):

conn = Faraday.new(url: "https://api.ffmpeg-micro.com") do |f|
  f.request :json
  f.response :json
end

response = conn.post("/v1/transcodes") do |req|
  req.headers["Authorization"] = "Bearer #{ENV.fetch("FFMPEG_MICRO_API_KEY")}"
  req.body = {
    inputs: [{ url: "https://example.com/video.mp4" }],
    outputFormat: "mp4",
    preset: { quality: "high", resolution: "1080p" }
  }
end

job = response.body
puts "Job ID: #{job["id"]}"

Both do the same thing. Pick whichever fits your project.

Checking Job Status and Downloading Results

Transcoding takes seconds to minutes depending on file size. Poll for completion:

job_id = job["id"]

loop do
  sleep 2
  uri = URI("https://api.ffmpeg-micro.com/v1/transcodes/#{job_id}")
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer #{api_key}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  status = JSON.parse(response.body)
  break unless %w[queued processing].include?(status["status"])
end

if status["status"] == "completed"
  uri = URI("https://api.ffmpeg-micro.com/v1/transcodes/#{job_id}/download")
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer #{api_key}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  download = JSON.parse(response.body)
  puts "Download URL: #{download["url"]}"
end

The download endpoint returns a signed URL valid for 10 minutes. Save the file or redirect your user to it.

Advanced: Custom FFmpeg Options

Presets handle most use cases. For full control, pass FFmpeg options directly:

response = conn.post("/v1/transcodes") do |req|
  req.headers["Authorization"] = "Bearer #{ENV.fetch("FFMPEG_MICRO_API_KEY")}"
  req.body = {
    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" }
    ]
  }
end

Same FFmpeg flags you'd use on the command line, passed as structured JSON. This converts MP4 to WebM using VP9 and Opus.

Uploading Local Files

If your video isn't at a public URL, upload it first. Three steps:

# Step 1: Get a presigned upload URL
presign = conn.post("/v1/upload/presigned-url") do |req|
  req.headers["Authorization"] = "Bearer #{api_key}"
  req.body = {
    filename: "my-video.mp4",
    contentType: "video/mp4",
    fileSize: File.size("/path/to/my-video.mp4")
  }
end

upload_url = presign.body.dig("result", "uploadUrl")
filename = presign.body.dig("result", "filename")

# Step 2: Upload directly to cloud storage
upload_conn = Faraday.new
upload_conn.put(upload_url) do |req|
  req.headers["Content-Type"] = "video/mp4"
  req.body = File.binread("/path/to/my-video.mp4")
end

# Step 3: Confirm the upload
confirm = conn.post("/v1/upload/confirm") do |req|
  req.headers["Authorization"] = "Bearer #{api_key}"
  req.body = {
    filename: filename,
    fileSize: File.size("/path/to/my-video.mp4")
  }
end

gcs_url = confirm.body.dig("result", "gcsUrl")

After confirmation, pass the GCS URL as input in your transcode request.

Common Pitfalls

Blocking Puma workers with polling. Don't poll in a web request. Use ActiveJob or Sidekiq to check transcode status in a background job.
Forgetting use_ssl: true with Net::HTTP. The API is HTTPS-only. Without SSL, you get a connection refused error, not a helpful message.
Polling too fast. A 2-second interval is plenty. Don't hammer the status endpoint every 100ms.
Ignoring the failed status. Always check for failure in your polling loop. A failed job never transitions to completed, so an infinite loop wastes resources.
Hardcoding API keys. Use ENV.fetch("FFMPEG_MICRO_API_KEY") or Rails credentials (Rails.application.credentials.ffmpeg_micro_api_key).

Frequently Asked Questions

Does this work on Heroku?

Yes. The API approach only needs Ruby's Net::HTTP (included in stdlib) or any HTTP client gem. No FFmpeg binary, no buildpack, no special configuration.

What about ActiveStorage videos?

ActiveStorage handles upload and storage. For processing, grab the blob URL and pass it to the API. You don't need ActiveStorage variants or an FFmpeg preview processor.

How much does FFmpeg Micro cost?

FFmpeg Micro bills per minute of video processed. The free tier gives you enough minutes to build and test. A 5-minute video costs a few cents to transcode. See the pricing page for current rates.

Can I process video inside a Rails controller action?

You can kick off the job in the controller, but don't wait for it to finish. Return a 202 to the user and check the result with a background job. Sidekiq, GoodJob, or Solid Queue all work.

What Ruby version do I need?

Ruby 2.7 or later. The code examples use modern syntax like ENV.fetch and dig, but the API works with any Ruby version that supports HTTPS.

Last verified: May 2026. All API examples tested against FFmpeg Micro v1.

How to Normalize Audio with FFmpeg (Volume, Loudnorm, and API)

Javid Jamae — Wed, 20 May 2026 10:12:57 +0000

Originally published at ffmpeg-micro.com

FFmpeg audio normalization trips up even experienced developers. The loudnorm filter alone has 6 parameters, a two-pass workflow that requires parsing JSON from stderr, and behavior that changes depending on whether you feed it MP4, WAV, or MKV. Most guides skip the hard parts.

This post covers three approaches to fixing audio levels with FFmpeg: simple volume scaling, broadcast-standard loudnorm normalization (EBU R128), and a cloud API that handles it without installing anything.

Quick answer: normalize audio to -16 LUFS with FFmpeg

ffmpeg -i input.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" -c:v copy output.mp4

This applies EBU R128 loudnorm normalization targeting -16 LUFS (the standard for streaming platforms). The -c:v copy flag passes video through untouched so only the audio gets re-encoded.

Approach 1: Simple volume adjustment with the volume filter

The volume filter is the simplest way to change audio levels. It multiplies every sample by a fixed factor.

Halve the volume:

ffmpeg -i input.mp4 -af "volume=0.5" -c:v copy output.mp4

Double the volume:

ffmpeg -i input.mp4 -af "volume=2.0" -c:v copy output.mp4

Adjust by decibels (more precise):

ffmpeg -i input.mp4 -af "volume=6dB" -c:v copy output.mp4

The volume filter is predictable but dumb. It doesn't analyze the source audio first, so you can easily clip loud sections or amplify noise in quiet ones. For consistent levels across multiple files, you need actual normalization.

Approach 2: EBU R128 normalization with loudnorm

The loudnorm filter implements the EBU R128 broadcast standard. Instead of blindly scaling amplitude, it measures perceived loudness (LUFS) and adjusts dynamically.

Single-pass normalization (good enough for most cases):

ffmpeg -i input.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" -c:v copy output.mp4

What the parameters mean:

I=-16 sets the target integrated loudness to -16 LUFS. YouTube uses -14, Spotify uses -14, podcasts typically use -16 to -19.
TP=-1.5 sets the true peak ceiling to -1.5 dBTP. This prevents clipping on lossy codecs like AAC and MP3 that can overshoot 0 dB during decoding.
LRA=11 sets the loudness range to 11 LU. This controls how much dynamic range the output keeps.

Two-pass normalization (more accurate):

Pass 1 - Analyze and capture stats:

ffmpeg -i input.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json" -f null - 2>&1 | tail -12

Pass 2 - Apply the measured values:

ffmpeg -i input.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=-19.6:measured_TP=-5.9:measured_LRA=0.6:measured_thresh=-29.6:offset=0.1:linear=true" -c:v copy output.mp4

Which approach should you use?

Scenario	Best approach	Why
Quick fix on one file	volume filter	Simple, predictable, no analysis needed
Batch normalize for a platform	loudnorm single-pass	EBU R128 standard, good enough for streaming
Mastering or archival quality	loudnorm two-pass	Most accurate, preserves dynamics
Automated pipeline	Cloud FFmpeg API	No installation, scales with your workflow

Common pitfalls

Forgetting -c:v copy and re-encoding the entire video. Without it, FFmpeg re-encodes the video stream too. This takes 10-50x longer.

Using volume instead of loudnorm for batch processing. The volume filter applies the same gain to every file. loudnorm measures each file and targets a consistent output level.

Setting the true peak ceiling to 0 dBTP. Lossy codecs generate intersample peaks during decoding that can exceed the encoded peak by 1-3 dB.

Running loudnorm on already-normalized audio. Double-normalizing compresses dynamics further each pass. Check levels first.

FAQ

What LUFS level should I target for YouTube?
YouTube normalizes all audio to -14 LUFS. Targeting -14 means YouTube won't touch your audio. -16 is close enough that the difference is barely audible.

Can I normalize audio without re-encoding the video?
Yes. Use -c:v copy to pass the video stream through unchanged. Only the audio gets re-encoded.

What is the difference between loudnorm and dynaudnorm?
loudnorm targets a specific LUFS level per the EBU R128 standard. dynaudnorm adjusts volume frame-by-frame and can introduce pumping artifacts. For most use cases, loudnorm is the right choice.

How to Add a Watermark to Video with FFmpeg (CLI + API)

Javid Jamae — Tue, 19 May 2026 10:19:23 +0000

Originally published at ffmpeg-micro.com

The Quick Answer

FFmpeg adds a watermark to video using the overlay filter. Two inputs (your video + your logo PNG), one filter, one output.

ffmpeg -i input.mp4 -i logo.png -filter_complex "[1:v]scale=100:-1[wm];[0:v][wm]overlay=W-w-10:H-h-10" -c:a copy output.mp4

That command scales your logo to 100px wide, pins it to the bottom-right corner with 10px padding, and copies the audio untouched. If you want to skip the FFmpeg installation and do this through an API call instead, jump to the API section below.

How the Overlay Filter Works

The overlay filter combines two video streams into one. Stream [0:v] is your base video. Stream [1:v] is the watermark image. The filter positions the watermark on top of the base at the coordinates you specify.

The basic syntax:

ffmpeg -i video.mp4 -i watermark.png -filter_complex "overlay=x:y" output.mp4

x and y are pixel positions measured from the top-left corner. But hardcoded pixel values break when your input resolution changes. That's where FFmpeg's position variables come in:

W / H = base video width / height
w / h = overlay (watermark) width / height

Position	Overlay value
Top-left	`overlay=10:10`
Top-right	`overlay=W-w-10:10`
Bottom-left	`overlay=10:H-h-10`
Bottom-right	`overlay=W-w-10:H-h-10`
Center	`overlay=(W-w)/2:(H-h)/2`

The 10 in each expression is padding in pixels. Adjust it to taste.

Scaling the Watermark

If your logo is 2000px wide and your video is 1280px, the watermark will cover the entire frame. Always scale first using scale2ref or a fixed-width scale:

ffmpeg -i input.mp4 -i logo.png \
  -filter_complex "[1:v]scale=100:-1[wm];[0:v][wm]overlay=W-w-10:H-h-10" \
  -c:a copy output.mp4

scale=100:-1 sets the width to 100px and calculates the height automatically to preserve aspect ratio. For a watermark that's always 10% of the video width:

-filter_complex "[1:v]scale=main_w/10:-1[wm];[0:v][wm]overlay=W-w-10:H-h-10"

Semi-Transparent Watermarks

If your watermark PNG already has an alpha channel (transparent background), overlay preserves it automatically. For adding opacity to a fully opaque logo, use the colorchannelmixer filter:

ffmpeg -i input.mp4 -i logo.png \
  -filter_complex "[1:v]colorchannelmixer=aa=0.3,scale=100:-1[wm];[0:v][wm]overlay=W-w-10:H-h-10" \
  -c:a copy output.mp4

aa=0.3 sets the alpha channel to 30% opacity. Lower values make the watermark more transparent.

Adding a Watermark via API (No Server Required)

Running FFmpeg locally works for one-off jobs. But if you're building an app that watermarks user-uploaded video, or automating a content pipeline, you don't want to manage FFmpeg servers.

FFmpeg Micro handles this with two API calls. Upload your logo once, then watermark any video with a single POST request.

Step 1: Upload your logo

Upload your watermark PNG using the 3-step presigned URL flow:

# Get a presigned upload URL for your logo
curl -X POST https://api.ffmpeg-micro.com/v1/upload/presigned-url \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my-logo.png",
    "contentType": "image/png",
    "fileSize": 24680
  }'

# Upload the file to the returned URL
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @my-logo.png

# Confirm the upload
curl -X POST https://api.ffmpeg-micro.com/v1/upload/confirm \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "20260519-my-logo.png",
    "fileSize": 24680
  }'

The confirm response gives you a gcsUrl like gs://bucket/20260519-my-logo.png. Save this. You only upload the logo once and reuse it across all your watermark jobs.

Step 2: Watermark a video

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/my-video.mp4" },
      { "url": "gs://your-bucket/20260519-my-logo.png" }
    ],
    "outputFormat": "mp4",
    "filters": [
      { "filter": "[1:v]scale=100:-1[wm];[0:v][wm]overlay=main_w-overlay_w-10:main_h-overlay_h-10" }
    ]
  }'

The filters field takes the same FFmpeg filter graph syntax you'd use locally. Two inputs, one filter, one API call. No FFmpeg binary to install, no server to scale.

Step 3: Poll and download

The response includes a job id. Poll GET /v1/transcodes/{id} until status is completed, then grab the output:

curl https://api.ffmpeg-micro.com/v1/transcodes/$JOB_ID/download \
  -H "Authorization: Bearer $API_KEY"

This returns a signed download URL valid for 10 minutes.

Text Watermarks via API

For text-based watermarks (copyright notices, channel branding), FFmpeg Micro has a built-in @text-overlay virtual option that handles font rendering, word wrap, and positioning:

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/my-video.mp4" }],
    "outputFormat": "mp4",
    "options": [
      {
        "option": "@text-overlay",
        "argument": {
          "text": "(c) 2026 My Brand",
          "style": {
            "fontSize": 24,
            "fontColor": "white",
            "x": "main_w-text_w-20",
            "y": "main_h-text_h-20",
            "boxBorderW": 8
          }
        }
      }
    ]
  }'

No font files to install, no drawtext filter compilation issues.

Common Pitfalls

Your FFmpeg build might not have drawtext. The drawtext filter requires FFmpeg compiled with --enable-libfreetype. Many default installations skip it. If you see No such filter: 'drawtext', you need to rebuild FFmpeg or switch to the image overlay approach. The FFmpeg Micro API handles this for you since @text-overlay runs on infrastructure where fonts are pre-installed.

PNG without alpha channel = ugly rectangle. If your logo is a JPEG or a PNG with a solid background, the watermark renders as a rectangle covering your video. Export your logo as PNG with a transparent background before using it as a watermark.

Scaling breaks aspect ratio if you set both width and height. Use scale=100:-1 (set width, auto-calculate height) instead of scale=100:100 (which stretches the logo).

Position variables differ between -vf and -filter_complex. In -filter_complex, use main_w and main_h for the base video dimensions, and overlay_w / overlay_h for the watermark. In -vf mode, the shorthand W, H, w, h also works.

Watermark disappears on short videos. If the watermark image has a longer duration than the video, FFmpeg may drop it. Add -shortest to your command to stop encoding at the end of the shortest input stream.

FAQ

Can I add a watermark to multiple videos at once?
With the CLI, you'd loop through files in a shell script. Through the FFmpeg Micro API, fire off one POST request per video. Each job runs independently on cloud infrastructure, so 100 watermark jobs process in parallel without you managing concurrency.

Does watermarking re-encode the entire video?
Yes. The overlay filter requires decoding and re-encoding. This means some quality loss unless you set a low CRF value (18 or lower for near-lossless). There's no way to avoid re-encoding when compositing two streams.

What image formats work for watermarks?
PNG is the standard choice because it supports transparency. JPEG works but renders with a solid background. SVG doesn't work directly with FFmpeg. Convert SVGs to PNG first.

Can I animate the watermark (fade in, move across the screen)?
Yes. FFmpeg's overlay filter accepts expressions for x and y that reference the frame number (n) or timestamp (t). For example, overlay=10:'if(lt(t,3),H,H-h-10)' keeps the watermark off-screen for the first 3 seconds, then snaps it into position.

How much does watermarking cost through the API?
FFmpeg Micro bills by processed input duration. A 1-minute video costs the same whether you're watermarking, transcoding, or trimming. Check the pricing page at ffmpeg-micro.com/pricing for current rates.

Last verified: 2026-05-19 against FFmpeg 3.3.3 (CLI) and FFmpeg Micro API v1

How to Convert Video Format with FFmpeg (MP4, WebM, MKV, AVI)

Javid Jamae — Mon, 18 May 2026 10:17:50 +0000

Originally published at ffmpeg-micro.com

Converting video between formats is one of the most common FFmpeg operations, and one of the most error-prone. Pick the wrong codec for a container and FFmpeg exits with a cryptic error. Pick the right codec but wrong settings and your file size doubles.

This guide covers the exact FFmpeg commands for converting between MP4, WebM, MOV, and AVI. Each conversion includes the CLI command and the equivalent API call using FFmpeg Micro, so you can run it from any app or automation tool without installing FFmpeg.

Quick Answer

To convert MP4 to WebM with FFmpeg:

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm

Or via the FFmpeg Micro API (no FFmpeg install needed):

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/input.mp4"}],
    "outputFormat": "webm",
    "options": [
      {"option": "-c:v", "argument": "libvpx-vp9"},
      {"option": "-crf", "argument": "30"},
      {"option": "-b:v", "argument": "0"},
      {"option": "-c:a", "argument": "libopus"}
    ]
  }'

Container vs. Codec: Why Format Conversion Breaks

Most format conversion failures come from one misunderstanding: the container (MP4, WebM, MKV) is just a wrapper. The codec (H.264, VP9, AAC) is the actual encoding inside it.

Every container only accepts certain codecs:

Container	Video Codecs	Audio Codecs
MP4	H.264, H.265/HEVC, AV1	AAC, MP3
WebM	VP8, VP9, AV1	Vorbis, Opus
MOV	H.264, H.265, ProRes	AAC, PCM
AVI	Most codecs (legacy)	Most codecs (legacy)
MKV	Virtually any codec	Virtually any codec

If you put H.264 video inside a WebM container, FFmpeg fails with: "Only VP8 or VP9 or AV1 video and Vorbis or Opus audio are supported for WebM." The container is rejecting the codec. We confirmed this by running a real API call without specifying VP9, and got exactly this error.

Convert MP4 to WebM

WebM is the standard for web video when you need better compression than H.264. VP9 gives you smaller files at the same quality, but encoding takes longer.

CLI:

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm

The -b:v 0 flag tells VP9 to use pure constant quality mode. Without it, VP9 defaults to constrained quality with a target bitrate that usually wastes space.

API:

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/input.mp4"}],
    "outputFormat": "webm",
    "options": [
      {"option": "-c:v", "argument": "libvpx-vp9"},
      {"option": "-crf", "argument": "30"},
      {"option": "-b:v", "argument": "0"},
      {"option": "-c:a", "argument": "libopus"}
    ]
  }'

{
  "id": "67e11131-a21c-4f60-ba9e-c524f74c3357",
  "status": "pending",
  "outputFormat": "webm"
}

We ran this against a 13-second 640x360 MP4. The API completed processing in under 1 second.

Convert MKV or MOV to MP4

MKV files from video editors and MOV files from iPhones often already contain H.264 video and AAC audio. Since MP4 supports both codecs, you can remux without re-encoding:

CLI (remux, near-instant):

ffmpeg -i input.mkv -c copy -movflags +faststart output.mp4

This copies the streams into a new container. No re-encoding means it finishes in seconds regardless of file length. The -movflags +faststart flag moves MP4 metadata to the front of the file so browsers can start playback before the download finishes. Always add this for web delivery.

If the MKV or MOV contains codecs that MP4 doesn't support (like VP9 inside MKV), you need to re-encode:

CLI (re-encode):

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

API:

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/input.mkv"}],
    "outputFormat": "mp4"
  }'

The API selects H.264 + AAC by default when you set outputFormat to mp4. No codec flags needed for the common case.

Convert AVI to MP4

AVI is a legacy format. Most AVI files use older codecs (MPEG-4 Part 2, DivX, Xvid) that need re-encoding for modern playback:

CLI:

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

API:

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/input.avi"}],
    "outputFormat": "mp4"
  }'

Batch Convert Videos via API

The CLI approach breaks down at scale. Converting 50 or 500 files means writing a shell loop and hoping your machine doesn't run out of memory.

The API handles this natively. Each job runs on its own cloud instance:

const API_KEY = process.env.FFMPEG_MICRO_API_KEY;

async function convertVideo(inputUrl: string, outputFormat: string) {
  const res = 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: inputUrl }],
      outputFormat,
    }),
  });
  return res.json();
}

const videos = [
  'https://storage.example.com/video1.mov',
  'https://storage.example.com/video2.avi',
  'https://storage.example.com/video3.mkv',
];

const jobs = await Promise.all(
  videos.map(url => convertVideo(url, 'mp4'))
);

console.log(`Started ${jobs.length} conversions`);

No concurrency limits to manage, no server to scale up.

Common Pitfalls

WebM + H.264 = instant failure. The WebM container only accepts VP8, VP9, or AV1 video. If you set outputFormat: "webm" without specifying a VP9 codec, the job fails. Always pass -c:v libvpx-vp9 (or libvpx for VP8) when targeting WebM.

Missing -b:v 0 for VP9 CRF mode. Without this flag, VP9 uses constrained quality with a default target bitrate. The result is usually a larger file than necessary. Pair -crf with -b:v 0 for pure quality-based encoding.

Forgetting -movflags +faststart for web MP4s. Without this, the browser must download the entire file before playback starts. Add it to every MP4 destined for web delivery or streaming.

Re-encoding when remuxing would do. If the source codec is compatible with the target container (H.264 in MKV going to MP4), use -c copy to remux. It finishes instantly and is completely lossless.

Assuming "format" means "codec." "Convert to MP4" is ambiguous. MP4 can contain H.264, H.265, or AV1. If you need a specific codec for device compatibility, spell it out with -c:v libx264.

FAQ

Can I convert video format without installing FFmpeg?

Yes. FFmpeg Micro is a cloud API that runs FFmpeg on managed infrastructure. Send an HTTP request with your video URL and target format. No FFmpeg binary, no server to maintain. Get a free API key at ffmpeg-micro.com.

What's the difference between remuxing and transcoding?

Remuxing (-c copy) changes the container without touching the video or audio data. It's near-instant and lossless. Transcoding (-c:v libx264) decodes and re-encodes the streams, which takes longer and can reduce quality slightly, but lets you change the actual codec.

Which format should I use for web video?

MP4 with H.264 has the widest browser support. WebM with VP9 gives better compression but slightly less compatibility on older devices. For maximum reach, go with MP4. For bandwidth savings on modern browsers, WebM.

How long does format conversion take via API?

It depends on video length and whether re-encoding is needed. A 13-second 640x360 MP4 to WebM conversion completed in under 1 second on FFmpeg Micro. Longer videos scale roughly linearly with duration.

Can I convert MKV or AVI files to MP4 via API?

Yes. Pass any publicly accessible video URL (or upload via the presigned upload flow) and set outputFormat: "mp4". The API handles codec detection and re-encoding automatically.

Last verified: 2026-05-18 against FFmpeg Micro API v1 and FFmpeg 7.0.2

How to Encode H.265 Video with FFmpeg (CRF + Preset Guide)

Javid Jamae — Sun, 17 May 2026 10:12:57 +0000

Originally published at ffmpeg-micro.com

H.265 (HEVC) produces files 30-50% smaller than H.264 at the same visual quality. The trade-off is encoding time. Getting the right CRF and preset combination for your use case is the difference between a file that's too big and an encode that takes all night.

What CRF and Preset Actually Control

CRF (Constant Rate Factor) sets your quality target. Lower numbers mean higher quality and larger files. The libx265 default is 28, which is roughly equivalent to CRF 23 in H.264.

Preset controls how hard the encoder works to hit that quality target. Slower presets find better compression at the same CRF, producing smaller files without losing quality. The trade-off is encode time.

The two settings are independent. CRF picks the quality. Preset picks how efficiently the encoder reaches that quality.

The Basic libx265 Command

ffmpeg -i input.mp4 -c:v libx265 -crf 28 -preset medium -c:a aac -b:a 128k -tag:v hvc1 output.mp4

Flag breakdown:

-c:v libx265 selects the H.265/HEVC encoder
-crf 28 sets quality (lower = better quality, larger file)
-preset medium balances speed and compression (default)
-c:a aac -b:a 128k re-encodes audio to AAC at 128kbps
-tag:v hvc1 marks the stream for Apple/browser playback compatibility

That -tag:v hvc1 flag is one people miss. Without it, Safari and iOS won't play the file. QuickTime will refuse to open it. If you're encoding for web delivery, always include it.

Which CRF Value for Which Use Case

Use Case	CRF Range	Why
Archival / master copy	18-22	Visually lossless. Large files, but you keep everything.
Streaming / web delivery	23-28	Good quality at reasonable file sizes. CRF 26 is the sweet spot for most web video.
Social media / batch processing	28-32	Smaller files, acceptable quality for short-form content where compression artifacts are less noticeable.
Preview / thumbnail generation	32-38	Low quality is fine. You're optimizing for speed and small size.

Start at CRF 28 and adjust. Encode a 30-second sample, check the output, then move the CRF up or down by 2-3 points until you hit your target file size and quality.

Preset Speed vs Compression

Preset	Relative Speed	File Size (same CRF)	Best For
ultrafast	10x	~40% larger	Testing, previews
fast	4x	~15% larger	Real-time or near-real-time
medium	1x (baseline)	baseline	General use
slow	0.4x	~5-10% smaller	Final renders, overnight batches
veryslow	0.1x	~10-15% smaller	Archival. Only worth it for content you'll serve thousands of times.

For most developers building automation pipelines, medium or slow is the right answer. veryslow gives diminishing returns that don't justify 10x the encode time unless you're Netflix.

Running H.265 Encodes via API (No libx265 Install)

Installing libx265 means compiling FFmpeg from source on most Linux distros, managing codec dependencies, and dealing with version mismatches. If you're building an automation pipeline, you can skip all of that.

The FFmpeg Micro API accepts raw FFmpeg options. Same flags, no local install:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx265"},
      {"option": "-crf", "argument": "28"},
      {"option": "-preset", "argument": "medium"},
      {"option": "-tag:v", "argument": "hvc1"}
    ]
  }'

The response comes back immediately with a job ID:

{
  "id": "trc_abc123",
  "status": "queued",
  "outputFormat": "mp4",
  "createdAt": "2026-05-17T10:00:00.000Z"
}

Poll GET /v1/transcodes/trc_abc123 until status is completed, then grab the output from GET /v1/transcodes/trc_abc123/download.

For high-quality archival encodes, just change the CRF and preset:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"url": "https://storage.example.com/input.mp4"}],
    "outputFormat": "mp4",
    "options": [
      {"option": "-c:v", "argument": "libx265"},
      {"option": "-crf", "argument": "22"},
      {"option": "-preset", "argument": "slow"},
      {"option": "-tag:v", "argument": "hvc1"}
    ]
  }'

Same two-line change you'd make in the CLI command, but no server to maintain.

Common Pitfalls

Forgetting -tag:v hvc1 for web delivery. Apple devices and most browsers need the hvc1 tag to recognize the HEVC stream. Without it, the file plays fine in VLC but fails in Safari, iOS, and many HTML5 video players.

Using H.264 CRF values with libx265. CRF 23 in H.264 and CRF 23 in H.265 are not the same quality. H.265's CRF 28 matches H.264's CRF 23. If you copy your H.264 settings directly, you'll get unnecessarily large files.

Choosing veryslow for batch pipelines. The compression gain from slow to veryslow is 3-5% smaller files. The time cost is 3-5x longer encodes. For automated pipelines processing hundreds of videos, medium or slow is almost always the right trade-off.

Not specifying audio codec explicitly. If your input has audio in a format incompatible with the MP4 container (like Vorbis), FFmpeg will fail silently or produce a broken file. Always set -c:a aac or -c:a copy (if the source audio is already AAC).

Expecting hardware encoders to support CRF. NVENC, VideoToolbox, and QSV don't support FFmpeg's -crf flag. They use -qp or -b:v instead. If you're running on GPU, the libx265 CRF workflow doesn't apply.

FAQ

Is H.265 always better than H.264?
For file size at the same quality, yes. But H.265 encoding is 2-5x slower, and some older devices can't decode it. If your audience is on modern browsers and mobile devices (2020+), H.265 is the better choice. For maximum compatibility with legacy players, stick with H.264.

What's the difference between CRF and two-pass encoding?
CRF targets constant quality (file size varies). Two-pass targets a specific bitrate (quality varies). Use CRF when you care about quality and can tolerate variable file sizes. Use two-pass when you have a strict file size budget, like streaming with a fixed bitrate cap.

Can I use CRF with the FFmpeg Micro API?
Yes. Pass -crf and -preset as options in the API request. The API runs the same FFmpeg binary with the same flags. No difference in output quality or behavior.

What CRF value gives "visually lossless" H.265?
CRF 18-20 with preset slow or veryslow. At these settings, most viewers can't distinguish the encode from the source in an A/B comparison. File sizes will be 60-70% smaller than the raw source, compared to 80-90% smaller at CRF 28.

Does preset affect quality or just file size?
At the same CRF, slower presets produce smaller files at the same quality. They don't improve quality. They improve compression efficiency. Think of it as: same visual result, less wasted bits.

Last verified: 2026-05-17 against FFmpeg 7.x and FFmpeg Micro API v1

How to Extract Frames from Video with FFmpeg

Javid Jamae — Sat, 16 May 2026 10:14:47 +0000

Originally published at ffmpeg-micro.com.

Extracting frames from video is one of the most common FFmpeg operations, and one of the most confusing. The flags aren't intuitive, the output naming is easy to get wrong, and quality control requires knowing which JPEG encoder settings FFmpeg actually respects.

This guide covers the patterns developers actually need: single frame at a timestamp, periodic extraction, keyframe-only extraction, quality control, and scaled thumbnails. Every command was tested against a real 640x360 H.264 MP4, and the actual file sizes are included so you know what to expect.

Extract a Single Frame at a Specific Timestamp

The most common case. Grab one frame from a specific point in the video.

ffmpeg -ss 00:00:05 -i input.mp4 -frames:v 1 frame.jpg

Two things matter here.

Put -ss before -i. This tells FFmpeg to seek before decoding, which is dramatically faster on long videos. If you put -ss after -i, FFmpeg decodes every frame from the start up to your timestamp. On a 2-hour file, that's the difference between milliseconds and minutes.

-frames:v 1 limits output to one frame. Without it, FFmpeg extracts every frame from that timestamp onward. Thousands of JPEGs filling your disk.

The timestamp accepts HH:MM:SS.ms or raw seconds:

ffmpeg -ss 90.5 -i input.mp4 -frames:v 1 frame.jpg

Output: a single 23KB JPEG at the video's native resolution.

Extract Frames at Regular Intervals

To grab one frame per second across the entire video:

ffmpeg -i input.mp4 -vf "fps=1" frame_%03d.jpg

The fps filter value controls the interval:

fps=0.5 gives one frame every 2 seconds
fps=0.1 gives one frame every 10 seconds
fps=5 gives five frames per second

The %03d in the output filename is a C-style format specifier. FFmpeg increments it per frame: frame_001.jpg, frame_002.jpg, and so on. Use %04d if you expect more than 999 frames.

On a 13-second test video at fps=1, this produced 14 frames ranging from 23KB to 38KB each. Total extraction time: under 1 second.

Extract Only Keyframes

If you don't need every frame and just want the visually significant ones, extract keyframes (I-frames). These are fully encoded frames that mark scene changes or major visual shifts.

ffmpeg -i input.mp4 -vf "select='eq(pict_type,I)'" -vsync vfr keyframe_%03d.jpg

-vsync vfr is critical. Without it, FFmpeg duplicates frames to maintain constant frame rate, and you get hundreds of identical images instead of just the keyframes.

On the same 13-second video, this produced 2 keyframes instead of 14. Much less disk usage, and the frames tend to be the ones you'd pick manually.

Generate Scaled Thumbnails

For thumbnail grids or preview strips, combine extraction with the scale filter:

ffmpeg -i input.mp4 -vf "fps=1,scale=320:180" -q:v 2 thumb_%03d.jpg

This chains two filters: fps=1 for the extraction interval, and scale=320:180 for the output dimensions. Filter order matters. fps first reduces the frame count, then scale resizes only those frames. Reversing works but wastes CPU.

The -q:v flag controls JPEG quality. Range is 2 (highest) to 31 (lowest). Default is around 8-10. For thumbnails displayed at small sizes, -q:v 5 balances quality and file size well.

At 320x180 with -q:v 2, thumbnails were 9-12KB each. At native 640x360 resolution, the same quality setting produced 36-38KB files.

To auto-calculate one dimension and preserve aspect ratio:

ffmpeg -i input.mp4 -vf "fps=1,scale=320:-1" thumb_%03d.jpg

scale=320:-1 sets width to 320 and calculates height automatically. Use -2 instead of -1 if the codec requires even dimensions.

Common Pitfalls

Wrong -ss placement. Putting -ss after -i decodes from the start. On long videos, this turns a millisecond operation into a multi-minute wait. Always put -ss before -i.

Missing -frames:v 1 for single frames. Without it, you get every frame from the seek point to the end. On a 1080p video, that's tens of thousands of files.

Forgetting -vsync vfr with select. Keyframe extraction without -vsync vfr produces duplicated frames. Hundreds of output files that are mostly identical.

Wrong format specifier. frame_%d.jpg works but produces frame_1.jpg, frame_2.jpg without padding. Sorting breaks after 9. Use %03d or %04d.

Output directory doesn't exist. FFmpeg won't create directories. ffmpeg -i input.mp4 output/frame_%03d.jpg fails if output/ doesn't exist. Create it first with mkdir -p output.

FAQ

Can I extract frames as PNG instead of JPEG?

Yes. Change the extension to .png. FFmpeg picks the encoder from the file extension. PNG is lossless but much larger. The same frame that was 23KB as JPEG was 269KB as PNG. About 11x bigger.

ffmpeg -ss 5 -i input.mp4 -frames:v 1 frame.png

How do I extract every Nth frame instead of every Nth second?

Use the select filter with a modulo expression:

ffmpeg -i input.mp4 -vf "select='not(mod(n,30))'" -vsync vfr every_30th_%03d.jpg

This grabs every 30th frame. For a 30fps video, that's roughly one per second, but frame-count-based instead of time-based.

What's the fastest way to extract a single frame?

Put -ss before -i and add -frames:v 1. FFmpeg seeks to the nearest keyframe, decodes forward to your timestamp, outputs one frame, and exits. On a 2GB file, this typically completes in under 100ms.

How do I extract frames from a specific time range?

Combine -ss (start) with -t (duration):

ffmpeg -ss 00:01:00 -i input.mp4 -t 10 -vf "fps=1" range_%03d.jpg

This extracts one frame per second from the 1:00 to 1:10 mark.

Is JPEG or PNG better for extracted frames?

JPEG for most cases. It's 10x smaller (23KB vs 269KB for the same 640x360 frame) and good enough for thumbnails, preview images, and visual inspection. Use PNG only when you need lossless pixel data for machine learning training sets or when frames feed into another image processing pipeline.

If you're building a video processing pipeline and need transcoding, format conversion, or watermarking alongside frame extraction, FFmpeg Micro handles the heavy lifting through a simple API. One HTTP call handles the transcode, so you can keep your local FFmpeg work focused on frame extraction. Grab a free API key at ffmpeg-micro.com.

Last verified: 2026-05-16 against FFmpeg 3.3.3

FFmpeg Subtitles Filter: How to Burn SRT Subtitles Into Video

Javid Jamae — Thu, 14 May 2026 10:22:01 +0000

Originally published at ffmpeg-micro.com

FFmpeg's subtitles filter burns SRT or ASS captions directly into the video pixels. Unlike soft subtitles (which viewers can toggle off), burned-in subtitles are permanent. They show up everywhere: social media players that strip subtitle tracks, messaging apps, and platforms that don't support external caption files.

The basic command is one line, but the filter's syntax for styling, positioning, and encoding has a few traps that waste hours if you don't know about them.

The Basic Command

ffmpeg -i input.mp4 -vf "subtitles=captions.srt" -c:v libx264 -crf 23 -c:a copy output.mp4

FFmpeg reads captions.srt, renders each subtitle at its timestamp, and encodes the result into a new MP4. The -c:a copy flag passes audio through untouched so you don't re-encode it for no reason.

Two things to know up front:

The subtitles filter requires FFmpeg compiled with libass. If you get No such filter: 'subtitles', your build doesn't have it. Most package managers include it by default (brew install ffmpeg on macOS, apt install ffmpeg on Ubuntu), but minimal Docker images often skip it.
The filter reads the SRT file at filter-graph init time. If the file path has spaces or colons, you need to escape them (more on that below).

Styling with force_style

The default appearance (white text, thin black outline) works, but you'll almost always want to customize it. The force_style parameter accepts ASS override tags:

ffmpeg -i input.mp4 \
  -vf "subtitles=captions.srt:force_style='FontSize=28,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,Shadow=1'" \
  -c:v libx264 -crf 23 -c:a copy output.mp4

force_style Parameter Reference

Parameter	What it does	Example value
FontSize	Text size in pixels	`28`
FontName	Font family	`Arial`
PrimaryColour	Text fill color (ASS hex: `&HAABBGGRR`)	`&H00FFFFFF` (white)
OutlineColour	Outline color	`&H00000000` (black)
BackColour	Shadow/background color	`&H80000000` (50% black)
Outline	Outline thickness in pixels	`2`
Shadow	Shadow distance in pixels	`1`
BorderStyle	1 = outline + shadow, 4 = opaque box	`4`
Alignment	Position on screen (numpad layout)	`2` (bottom center)
MarginV	Vertical margin from the edge	`30`
Bold	Bold text (1 = on, 0 = off)	`1`

The color format is tricky. ASS uses &HAABBGGRR, not the #RRGGBB you're used to from CSS. White is &H00FFFFFF. Yellow is &H0000FFFF. Red is &H000000FF. The AA prefix is transparency (00 = fully opaque, FF = fully transparent).

Character Encoding and Escaping

Three escaping rules that catch people off guard:

Colons in file paths. On Windows, paths like C:\Users\me\captions.srt break the filter because : is a parameter separator. Escape them with backslashes.

Single quotes inside force_style. The force_style value is wrapped in single quotes. If your font name contains an apostrophe, escape it with a backslash.

UTF-8 encoding. The SRT file must be UTF-8. If you get garbled characters or blank subtitles, check with file captions.srt. Convert if needed:

iconv -f UTF-16 -t UTF-8 captions-utf16.srt > captions.srt

Common Pitfalls

"No such filter: subtitles" means your FFmpeg build doesn't include libass. Reinstall with subtitle support: brew install ffmpeg (macOS), sudo apt install ffmpeg libass-dev (Ubuntu).

Timing is off after trimming. If you use -ss (seek) to trim the video, subtitle timestamps don't shift automatically. Put -ss before -i as an input option.

Output file is bigger than the input. Burning subtitles forces a full re-encode. Use -crf 23 or lower for quality parity. Don't use -c:v copy because the filter can't modify copied frames.

Text renders at wrong size after scaling. Put subtitles AFTER the scale filter: -vf "scale=1280:720,subtitles=captions.srt". Chain order matters.

FAQ

Does the subtitles filter work with WebM and MKV output?

Yes. The filter burns text into video frames, so it works with any output container.

Can I use the subtitles filter with a URL instead of a local file?

No. The subtitles filter only reads local files. Download your SRT first with curl or wget before passing it to the filter.

How do I burn subtitles without re-encoding?

You can't. The filter modifies video frames, which requires a full decode-and-encode cycle. To minimize quality loss, match the original codec and use a CRF value equal to or lower than the source.

Read the full guide with more examples on ffmpeg-micro.com.

How to Learn FFmpeg: The Developer's Guide (2026)

Javid Jamae — Wed, 13 May 2026 10:16:07 +0000

Originally published at ffmpeg-micro.com.

FFmpeg has over 400 command-line flags, dozens of codecs, and documentation that reads like a reference manual for people who already know what they're doing. Most developers don't need 90% of it.

This guide covers the five operations you'll use in almost every project, the tool you should learn before ffmpeg itself, and when it makes sense to stop running FFmpeg locally and use an API instead.

Start with ffprobe, Not ffmpeg

Before you process anything, learn what you're working with. ffprobe ships with FFmpeg and tells you everything about a media file: codecs, resolution, duration, bitrate, frame rate.

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

This prints structured JSON you can pipe into any script. You'll use it constantly to debug why a transcode failed or why a file is bigger than expected.

The Five Commands You Actually Need

Most FFmpeg tutorials bury you in options. In practice, these five operations cover about 80% of developer use cases.

Convert Between Formats

ffmpeg -i input.mov -c:v libx264 -c:a aac output.mp4

This converts a QuickTime file to MP4 with H.264 video and AAC audio. The -c:v flag sets the video codec, -c:a sets the audio codec.

Compress Video

ffmpeg -i input.mp4 -c:v libx264 -crf 28 -preset fast -c:a aac -b:a 128k compressed.mp4

CRF (Constant Rate Factor) controls quality. Lower numbers mean higher quality and larger files. 23 is the default. 28 gives you a noticeably smaller file with acceptable quality for most web delivery.

Extract Audio

ffmpeg -i input.mp4 -vn -c:a libmp3lame -q:a 2 output.mp3

The -vn flag strips the video stream entirely. -q:a 2 sets MP3 quality on a 0-9 scale (0 is best, 9 is worst).

Resize Video

ffmpeg -i input.mp4 -vf scale=-2:720 -c:v libx264 -preset fast -crf 23 -c:a copy output.mp4

-vf scale=-2:720 scales the video to 720 pixels tall and calculates width automatically. The -2 keeps it divisible by 2, which H.264 requires.

Trim a Clip

ffmpeg -i input.mp4 -ss 00:00:30 -t 10 -c copy trimmed.mp4

-ss is the start time, -t is the duration in seconds. -c copy avoids re-encoding, so this runs almost instantly.

When to Stop Running FFmpeg Yourself

FFmpeg is the right tool when you're processing files on your own machine. It stops being the right tool when your app needs to process user-uploaded video, or you need video processing inside an automation tool like n8n or Make.com.

At that point, an API handles the same operations without the infrastructure. FFmpeg Micro lets you send a video URL and get a processed file back with a single HTTP call.

Common Pitfalls

Forgetting -y in scripts. FFmpeg prompts before overwriting. Add -y to auto-overwrite in automation.
Using -ss after -i. Put -ss before -i for fast seeking on large files.
Assuming codec from extension. An .mp4 can hold H.264, H.265, VP9. Always run ffprobe first.
Ignoring exit codes. Check $? or you'll silently pass corrupt files downstream.

FAQ

Is FFmpeg hard to learn? The basics take an afternoon. Five commands cover 80% of what developers need.

Can I use FFmpeg without installing it? Yes. Cloud APIs like FFmpeg Micro expose the same operations over HTTP.

Is FFmpeg free? FFmpeg is free and open-source (LGPL/GPL). Running it at scale costs whatever your server costs. API services charge per minute instead.

Last verified May 2026.

FFmpeg -ss, -t, and -to Flags: Input vs Output Seeking

Javid Jamae — Mon, 11 May 2026 10:17:17 +0000

Originally published at ffmpeg-micro.com

Trimming video with FFmpeg looks simple until your 5-second clip comes out as 7 seconds. Or your output starts a few frames late. The culprit is almost always flag order: where you put -ss relative to -i completely changes how FFmpeg processes the seek.

This post covers what -ss, -t, and -to do, why their placement matters, and when to use each combination.

What -ss, -t, and -to Actually Do

Three flags control timing in FFmpeg:

-ss sets the start position (the seek point)
-t sets the duration of the output
-to sets the end timestamp

-t and -to are mutually exclusive. If you use both, -t wins and -to gets ignored silently.

The critical distinction is where you place -ss: before -i (input seeking) or after -i (output seeking). The two produce different results with different tradeoffs.

Input Seeking: Fast but Imprecise

Place -ss before -i and FFmpeg jumps directly to the nearest keyframe at or before your timestamp. It doesn't decode anything before that point.

ffmpeg -ss 2 -i input.mp4 -t 5 -c copy output.mp4

This is fast. On a 2-hour file, FFmpeg skips straight to the 2-second mark instead of decoding from the beginning.

The catch: with -c copy (stream copy), FFmpeg can only cut at keyframes. If the nearest keyframe is at 0.5s instead of 2s, your output starts earlier than you asked for. In testing on a 13-second 640x360 MP4, this command produced a 7.07-second file instead of the expected 5 seconds.

Output Seeking: Slow but Frame-Accurate

Place -ss after -i and FFmpeg decodes the entire file from the beginning, throwing away frames until it hits your timestamp.

ffmpeg -i input.mp4 -ss 2 -t 5 output.mp4

This re-encodes by default, which means frame-accurate cuts. The same test file produced exactly 5.005 seconds. The timestamp landed right where expected.

The cost: on long files, FFmpeg decodes everything before the seek point just to discard it.

The Sweet Spot: Input Seek + Re-encode

ffmpeg -ss 2 -i input.mp4 -t 5 -c:v libx264 -preset fast output.mp4

Input seeking jumps to the approximate position (fast), then re-encoding trims at exact frame boundaries (precise). Best of both.

-t vs -to: Duration vs End Position

-t specifies how long the output should be. -to specifies an absolute end timestamp.

# Extract from 5s, for 3 seconds
ffmpeg -i input.mp4 -ss 5 -t 3 output.mp4

# Same result: from 5s, stop at the 8-second mark
ffmpeg -i input.mp4 -ss 5 -to 8 output.mp4

Both produce a 3-second file. When -ss is before -i, the timeline resets to zero, so -to and -t become equivalent.

Common Pitfalls

Using -c copy and expecting exact timestamps. Stream copy can't cut between keyframes. Drop -c copy and re-encode for precision.

Mixing up -t and -to with input seeking. When -ss is before -i, both flags are relative to the seeked position, not the original file.

Using output seeking on huge files. Output seeking at -ss 3:59:00 on a 4-hour file decodes nearly the entire thing. Use input seeking.

Using -to before -i on old FFmpeg versions. Requires FFmpeg 4.0+. Older versions silently ignore it.

Combining -t and -to. FFmpeg doesn't warn you. It uses -t and throws away -to.

FAQ

Why is my trimmed video longer than expected?
You're probably using -c copy. FFmpeg can only cut at keyframe boundaries with stream copy. Re-encode for frame-accurate timestamps.

What's the fastest way to trim a video?
Input seeking with stream copy: ffmpeg -ss 30 -i input.mp4 -t 10 -c copy output.mp4. Finishes in milliseconds but won't be frame-accurate.

Last verified: 2026-05-11 against FFmpeg 7.x

How to Extract Audio from Video with FFmpeg (MP3, WAV, and API Guide)

Javid Jamae — Sun, 10 May 2026 10:17:02 +0000

Originally published at ffmpeg-micro.com

You recorded a webinar, a YouTube video, or a product demo. Now you need the audio track as a standalone file. Maybe you're repurposing video content as podcast episodes. Maybe your app needs to strip audio from user uploads for transcription. FFmpeg handles this in a single command, but getting the codec and container options right takes some trial and error.

How to Extract Audio from Video with FFmpeg

The core command is simple. The -vn flag tells FFmpeg to drop the video stream, and you specify the output format through the file extension or codec flag.

ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 192k output.mp3

This extracts the audio from input.mp4, re-encodes it as MP3 at 192 kbps, and writes output.mp3. The -c:a libmp3lame flag selects the LAME MP3 encoder, and -b:a 192k sets a bitrate that balances quality and file size.

If you just need the raw audio without re-encoding, use -c:a copy to stream-copy the existing audio codec:

ffmpeg -i input.mp4 -vn -c:a copy output.aac

Stream copying is faster because FFmpeg skips the decode/encode cycle entirely. But the output container must support whatever codec the source video uses. An MP4 with AAC audio can stream-copy to .aac or .m4a, but not directly to .mp3.

Extract Audio as WAV (Uncompressed)

WAV is the go-to when you need lossless audio for editing, transcription pipelines, or feeding into speech-to-text models like Whisper.

ffmpeg -i input.mp4 -vn -acodec pcm_s16le output.wav

The pcm_s16le codec produces 16-bit signed PCM, which is what most audio tools expect. WAV files are large. A 5-minute video produces roughly 50 MB of uncompressed audio. If storage matters, use FLAC instead for lossless compression at about half the size:

ffmpeg -i input.mp4 -vn -c:a flac output.flac

Convert Video to MP3 with Custom Quality

MP3 is still the most universal audio format. For podcasts and general distribution, 128-192 kbps covers most use cases. For music or high-fidelity content, bump it to 320 kbps:

ffmpeg -i input.mp4 -vn -c:a libmp3lame -b:a 320k output.mp3

You can also use FFmpeg's variable bitrate mode with -q:a instead of -b:a. Lower values mean higher quality:

ffmpeg -i input.mp4 -vn -c:a libmp3lame -q:a 2 output.mp3

A -q:a value of 2 averages around 190 kbps and produces better quality than a fixed 192k bitrate at roughly the same file size.

Common Gotchas When Extracting Audio

Container vs. codec mismatch. The most common error is trying to stream-copy audio into an incompatible container. If your source has Opus audio and you try -c:a copy output.mp3, FFmpeg will fail. Either re-encode or pick a container that supports the source codec (.ogg or .webm for Opus).

No audio stream. Some screen recordings and generated videos don't have an audio track at all. FFmpeg will error with "Output file does not contain any stream." Check first with ffprobe:

ffprobe -v quiet -show_streams -select_streams a input.mp4

If this returns nothing, the video has no audio to extract.

Sample rate mismatches. When feeding extracted audio into pipelines that expect a specific sample rate (like 16kHz for Whisper), set it explicitly:

ffmpeg -i input.mp4 -vn -c:a libmp3lame -ar 16000 -ac 1 -b:a 64k output.mp3

The -ar 16000 flag resamples to 16kHz, and -ac 1 downmixes to mono.

Extract Audio via API (No FFmpeg Installation)

All those CLI commands work great on your local machine. But if you're building an app that needs to extract audio from user uploads, or automating extraction across hundreds of videos, you don't want to install FFmpeg on a server and manage the infrastructure.

FFmpeg Micro is a cloud API that handles this with a single HTTP request. Send the video URL and your desired output format:

curl -X POST "https://www.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": "mp3",
    "options": [
      {"option": "-vn", "argument": ""},
      {"option": "-b:a", "argument": "192k"}
    ]
  }'

The API queues the job, processes it in the cloud, and gives you a download URL when it's done. No FFmpeg binary to install. No server to scale. No codec dependencies to manage.