Process WordPress Video Uploads with FFmpeg Micro (No Plugin)

WordPress resizes every image you upload, which makes it feel like the media library handles media. It doesn't handle video. Upload an MP4 and WordPress stores the exact bytes you sent: no compression, no transcoding, no resolution change, so a 40 MB phone clip ships to every visitor at 40 MB.
Quick answer: To process WordPress video uploads you either install FFmpeg on the server and shell out withexec()on every upload, which shared and managed hosts block, or you hand the file to a cloud encoder. With FFmpeg Micro, hookadd_attachment, POST the attachment URL tohttps://api.ffmpeg-micro.com/v1/transcodeswithwp_remote_post(), then poll the job on WP-Cron and sideload the compressed file back into the media library. No WordPress plugin is needed, nothing to install on the WordPress host, and the free tier covers about 33 minutes of video.
Why WordPress has no built-in video processing
WordPress is a CMS, not a media pipeline. The media library accepts uploads and generates image thumbnails, but it skips video entirely: no transcoding queue, no codec selection, no compression settings. Every byte a contributor uploads is a byte your visitors download.
Installing FFmpeg directly on a shared hosting environment is usually impossible. Managed WordPress hosts like WP Engine and Flywheel block shell access, so exec('ffmpeg ...') returns nothing at all. On a VPS you can install the binary, but then you own it: OS upgrades that change the FFmpeg version, encoder jobs competing with PHP-FPM for CPU, and a 20-minute transcode holding a worker while visitors wait.
The third option is a SaaS video platform. A managed streaming service solves processing, and it also takes over storage, delivery and the player, billed per minute stored and per minute delivered. For a site that wants its own media library and just needs uploads compressed before serving them, that is a large amount of platform for a small job.
Server-side FFmpeg vs a transcoding API in WordPress
The decision comes down to what you are willing to operate. Both paths produce the same H.264 MP4; they differ in where the encoder runs and who keeps it alive.
| FFmpeg installed on the server | FFmpeg Micro API | |
|---|---|---|
| Works on shared/managed hosts | No, shell access is blocked | Yes, outbound HTTPS is all it needs |
| Setup | Install binary, keep it patched | Define an API key in `wp-config.php` |
| Encoding load | Your PHP server's CPU | Off-box, no PHP worker held open |
| Long jobs | Risk hitting `max_execution_time` | Job ID plus polling, no blocked request |
| Cost | Server time you already pay for | 1 token per 10 seconds of input video, billed per second |
| Failure cost | Half-written files on disk | Failed jobs are never billed |
If keeping an encoder patched is not work you want, the FFmpeg Micro quickstart issues a temporary key and runs an upload, transcode, poll and download for you in the dashboard, so you can confirm the job shape before you write any PHP.
How to process video uploads in WordPress with a REST API
The pattern has three parts: register a hook that fires on every new upload, check the MIME type, and POST the file URL to FFmpeg Micro. WordPress media URLs are public by default, so the API can fetch the file directly and you never upload it twice.
Register the upload hook
The add_attachment action fires once per new media item, including uploads from the block editor, the classic uploader and the REST API. Store the job ID in post meta so the polling callback can find it later.
add_action('add_attachment', 'ffmpeg_micro_process_video');
function ffmpeg_micro_process_video($attachment_id) {
$mime_type = get_post_mime_type($attachment_id);
if (strpos($mime_type, 'video/') !== 0) {
return;
}
$file_url = wp_get_attachment_url($attachment_id);
$job_id = ffmpeg_micro_submit_transcode($file_url);
if ($job_id) {
update_post_meta($attachment_id, '_ffmpeg_micro_job_id', $job_id);
wp_schedule_single_event(time() + 30, 'ffmpeg_micro_check_job', [$attachment_id]);
}
}
Submit the transcode job
A transcode request takes inputs (an array of {url} objects), an outputFormat, and either a preset or an options array of {option, argument} pairs that map one to one onto FFmpeg flags. Use options here, because a preset resolution scales every video to that exact size, including videos that are already smaller.
function ffmpeg_micro_submit_transcode($video_url) {
$api_key = defined('FFMPEG_MICRO_API_KEY') ? FFMPEG_MICRO_API_KEY : '';
$response = wp_remote_post('https://api.ffmpeg-micro.com/v1/transcodes', [
'headers' => [
'Authorization' => 'Bearer ' . $api_key,
'Content-Type' => 'application/json',
],
'body' => wp_json_encode([
'inputs' => [['url' => $video_url]],
'outputFormat' => 'mp4',
'options' => [
['option' => '-c:v', 'argument' => 'libx264'],
['option' => '-crf', 'argument' => '28'],
['option' => '-c:a', 'argument' => 'aac'],
['option' => '-vf', 'argument' => 'scale=-2:min(720\,ih)'],
],
]),
'timeout' => 30,
]);
if (is_wp_error($response)) {
error_log('FFmpeg Micro error: ' . $response->get_error_message());
return null;
}
$body = json_decode(wp_remote_retrieve_body($response), true);
return $body['id'] ?? null;
}
The filter is the part worth reading twice. min(720\,ih) caps the output height at 720 pixels but leaves anything shorter alone, and -2 picks a width that keeps the aspect ratio on an even number, which H.264 requires. The comma is escaped because FFmpeg treats a bare comma as a filter separator.
That one line is the difference between compressing and inflating. Submitting the same 640x360 test upload with a 1080p preset returned a 1920x1080 file that grew from 0.99 MB to 4.98 MB. The options above returned it at its original 640x360 and 0.47 MB, a little over half the original size.
Poll for completion and point the attachment at the new file
WP-Cron handles the waiting. Each run checks the job, and when the status is completed it asks for a download URL, pulls the file into the uploads directory and repoints the attachment. Job statuses are pending, processing, completed, failed and canceled, so treat the last two as the end of the line and reschedule for everything else.
add_action('ffmpeg_micro_check_job', 'ffmpeg_micro_poll_and_replace');
function ffmpeg_micro_poll_and_replace($attachment_id) {
// WP-Cron does not load the admin file that defines download_url() and wp_handle_sideload().
require_once ABSPATH . 'wp-admin/includes/file.php';
$job_id = get_post_meta($attachment_id, '_ffmpeg_micro_job_id', true);
$api_key = defined('FFMPEG_MICRO_API_KEY') ? FFMPEG_MICRO_API_KEY : '';
$response = wp_remote_get(
"https://api.ffmpeg-micro.com/v1/transcodes/{$job_id}",
[
'headers' => ['Authorization' => 'Bearer ' . $api_key],
'timeout' => 15,
]
);
if (is_wp_error($response)) {
wp_schedule_single_event(time() + 30, 'ffmpeg_micro_check_job', [$attachment_id]);
return;
}
$job = json_decode(wp_remote_retrieve_body($response), true);
if ($job['status'] === 'completed') {
$dl_response = wp_remote_get(
"https://api.ffmpeg-micro.com/v1/transcodes/{$job_id}/download",
['headers' => ['Authorization' => 'Bearer ' . $api_key]]
);
$dl_data = json_decode(wp_remote_retrieve_body($dl_response), true);
$tmp_file = download_url($dl_data['url']);
if (!is_wp_error($tmp_file)) {
$file_array = [
'name' => basename(get_attached_file($attachment_id)),
'tmp_name' => $tmp_file,
];
$new_file = wp_handle_sideload($file_array, ['test_form' => false]);
if (empty($new_file['error'])) {
update_attached_file($attachment_id, $new_file['file']);
}
}
} elseif (in_array($job['status'], ['failed', 'canceled'], true)) {
error_log("FFmpeg Micro job {$job_id} ended as {$job['status']} for attachment {$attachment_id}");
} else {
wp_schedule_single_event(time() + 30, 'ffmpeg_micro_check_job', [$attachment_id]);
}
}
Three details in that function come from running it rather than reading it. The require_once at the top of the function is not optional: WP-Cron loads WordPress without the admin bootstrap, and without it the first real job dies with Call to undefined function download_url(). GET /v1/transcodes/{id}/download returns {"url": "..."} with a signed link that is valid for 10 minutes, which is comfortably longer than a sideload needs but short enough that you should not cache it in post meta. And the error branch reschedules instead of returning, so one network blip does not abandon a job that is still encoding fine.
Note what the completed branch does not do. wp_handle_sideload() writes a new file alongside the original, typically video-1.mp4, and update_attached_file() points the attachment record at it. The original upload is still sitting in the uploads folder.
Add your API key to wp-config.php:
define('FFMPEG_MICRO_API_KEY', 'your-api-key-here');
FFmpeg Micro also publishes an official PHP SDK, composer require ffmpeg-micro/ffmpeg-micro-php, which needs PHP 8.1 or later. Inside WordPress, the wp_remote_post() approach above is still the better fit: it goes through WordPress's own HTTP API, which respects site-level request filters and proxy settings, and it adds no Composer dependencies to a theme or plugin. The whole integration lives in functions.php or a small custom plugin, with no third-party WordPress plugin involved.
WooCommerce product video processing
If sellers upload product demo videos, the same two functions cover it. Hook the product save action and read the attachment ID from your own meta key: WooCommerce core has no product video field, so _product_video_id below stands for whatever meta key your theme or product-video plugin uses to store the video's attachment ID, and you replace it with yours. The snippet hands that attachment to ffmpeg_micro_process_video(), the upload hook's function.
add_action('woocommerce_process_product_meta', function ($product_id) {
$video_id = get_post_meta($product_id, '_product_video_id', true);
if ($video_id && strpos(get_post_mime_type($video_id), 'video/') === 0) {
ffmpeg_micro_process_video($video_id);
}
});
Product videos then stay compressed without asking sellers to pre-process anything, which matters on a catalog page loading six of them at once.
What the processing actually costs
Billing is metered on the input video, so you can price a WordPress upload before you ship the feature. One token buys 10 seconds of input, measured per second with no rounding up to the minute, and failed jobs are never billed. A 90-second product demo costs 9 tokens.
A new account gets 200 tokens at sign-up, roughly 33 minutes of video, with API access and unlimited API keys, and no card required. The Free tier caps input files at 100 MB, which is the number to check against your upload_max_filesize: a site accepting 500 MB uploads needs Starter at $19.99 a month, which raises the cap to 1,024 MB and grants 2,500 tokens. Current numbers are on the pricing page.
When not to do it this way
This integration is the right call for sites that want compressed MP4s in their own media library, served from their own host. It is the wrong call for two cases.
If you need adaptive bitrate playback, a player, and a CDN, a managed streaming platform is doing a different job than a transcoding API, and bolting HLS delivery onto the WordPress uploads directory will not end well. You can still generate the renditions through the API (MP4 to HLS walks through the ladder), but something has to serve them.
The other case is a site with no outbound HTTP at all, behind a strict egress firewall. The API fetches your media URL and your server fetches the result, so both directions need to work.
Common pitfalls
WordPress cron isn't real cron. wp_schedule_single_event() only fires on page visits, so on a low-traffic site a job can sit unpolled for hours. Set DISABLE_WP_CRON to true and have a system cron hit wp-cron.php every minute, or run wp cron event run --due-now from WP-CLI.
The original file stays on disk. wp_handle_sideload() writes the compressed video next to the original as video-1.mp4 rather than overwriting it, so a 40 MB upload that compresses to 8 MB leaves you using 48 MB. Capture the old path with get_attached_file() before you call update_attached_file(), then remove it with wp_delete_file() once the new file is in place.
Guessing at download timeouts. download_url() already defaults to a 300-second timeout, and its second argument sets that timeout in seconds, so download_url($url, 900) is what very large files want. Raise PHP's max_execution_time to match, or the cron request dies before the download finishes.
Silent failures. The code above writes to error_log() and nothing else, so a run of canceled jobs is invisible until someone notices the videos are still huge. Add a wp_mail() call in the terminal branch, or push the status into a monitoring service.
File permissions. The uploads directory needs write permission for the PHP user or wp_handle_sideload() returns an error string in $new_file['error'] and the attachment quietly keeps pointing at the original. The empty($new_file['error']) check is what stops that from corrupting the attachment record.
FAQ
Can I use FFmpeg Micro with WordPress on shared hosting?
Yes. All encoding runs on FFmpeg Micro's infrastructure, so the WordPress host only has to make outbound HTTPS requests. There is nothing to install, which makes this work on shared hosting, on managed WordPress hosts that block shell access, and in any environment that can run PHP.
How long does video processing take through the API?
Processing time through the FFmpeg Micro API depends on the video's length, resolution and the work requested, so poll the job for its status rather than assuming a duration. The WP-Cron callback above checks every 30 seconds until the status is completed, failed or canceled. Billing tracks the duration of the video processed, not how long the servers take.
What video formats does FFmpeg Micro support for output?
FFmpeg Micro outputs MP4, WebM, MOV and AVI for video, plus audio formats and JPEG, PNG, GIF or WebP stills. For WordPress, MP4 with H.264 (libx264) is the safe default because every browser and device plays it natively. VP9 or AV1 inside WebM gets you smaller files if your audience is on modern browsers.
Do I need to upload the video to FFmpeg Micro first?
You don't need to upload the video to FFmpeg Micro first if it is already publicly reachable. WordPress media URLs are public by default, so wp_get_attachment_url() can be passed straight to the API. For private or access-restricted files, use the three-step upload flow instead: request a presigned URL, PUT the file to cloud storage, then confirm the upload before submitting the transcode.
Should I use a preset or custom FFmpeg options?
Presets are the shorter way to write a job, and the example above uses options only because it needs conditional scaling. The preset form replaces the whole options array:
{
"inputs": [{"url": "https://example.com/video.mp4"}],
"outputFormat": "mp4",
"preset": {"quality": "medium", "resolution": "720p"}
}
The catch is that a preset resolution scales every video to that size, including videos that are already smaller, so a 640x360 upload comes back upscaled to 1280x720 and larger than it started. Options give full control over codecs, bitrates and filters, which is what you want when the input sizes vary.
Start processing WordPress videos
Every upload that skips compression costs you bandwidth on every view, and the fix is about 80 lines of PHP that your host cannot block. Grab a free API key at FFmpeg Micro, paste it into wp-config.php, and the next video a contributor uploads comes back compressed.
Last verified: October 2026. Tested in WordPress 6.9 against FFmpeg Micro v1.
About Javid Jamae
Founder & CEO at FFmpeg Micro
Javid is a software engineer, author, and entrepreneur with over 25 years of professional software development experience across enterprise, startup, and consulting environments. He founded FFmpeg Micro to make video processing accessible to developers through a simple, automation-first REST API.
You might also like

How to Use FFmpeg with PHP (No Installation Required)
Process video in PHP without installing FFmpeg. Complete guide with cURL and Guzzle examples for transcoding, resizing, and format conversion via API.

Add Video Processing to Your Vercel + Supabase App in 10 Minutes
Add video processing to a Vercel + Supabase app using FFmpeg Micro API. Upload, transcode, and store results in 10 minutes flat.

Getting Started with FFmpeg Micro: 5 API Examples
Learn how to use the FFmpeg Micro API with 5 practical examples: transcode video, resize to 720p, extract audio, add watermarks, and generate thumbnails.
Ready to process videos at scale?
Start using FFmpeg Micro's simple API today. No infrastructure required.
Get Started Free