Media Processing

Transform your uploaded files using the full power of FFmpeg through simple HTTP requests. Whether you’re converting formats, resizing videos, extracting audio, or creating complex multi-media workflows, this guide takes you from basic to advanced processing techniques.

Prerequisites

You’ll need files already uploaded using the File Management workflow. Each file has a file_path you’ll reference in processing tasks.

Learning Path: Simple to Advanced

🎬 Basic Operations

Format conversion, simple transformations

⚙️ Intermediate

Filters, quality settings, multi-output

🚀 Advanced

Complex filters, multi-input workflows

The Processing Request

All processing happens through POST /ffmpeg/process with a JSON task definition:

const response = await fetch('https://api.ffmpeg-api.com/ffmpeg/process', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    task: {
      inputs: [{ file_path: 'dir_123/input.mp4' }],
      outputs: [{ file: 'output.mp4' }]
    }
  })
})
 
const result = await response.json()

Task Structure Overview

Required Fields

inputs[] → Array of input files with their file_path

outputs[] → Array of output specifications with file names

Optional Fields

inputs[].options[] → FFmpeg options applied before input

outputs[].options[] → FFmpeg options for output

outputs[].maps[] → Stream mapping for complex workflows

filter_complex → Advanced filter graphs for multi-input processing

🔍

Important Constraints: All input files must be in the same directory. Output filenames cannot conflict with existing input filenames.

Understanding the Response

Successful processing returns detailed results and usage information:

{
  "ok": true,
  "result": [
    {
      "file_name": "output.mp4",
      "size_bytes": 1234567,
      "download_url": "https://storage.example.com/result.mp4"
    }
  ],
  "usage": {
    "time_sec": 12.5,
    "input_size_gb": 0.098,
    "output_size_gb": 0.015,
    "gb_sec": 1.4125
  }
}

📁 Result Files

file_name → Output filename

size_bytes → File size in bytes

download_url → Direct download link

📊 Usage Stats

time_sec → Processing time

gb_sec → Billing units consumed

input_size_gb → Input file sizes

output_size_gb → Output file sizes

🎬 Level 1: Basic Operations

Start with simple, single-input transformations:

Format Conversion

Convert a GIF to MP4:

const task = {
  inputs: [
    { file_path: 'dir_123/animation.gif' }
  ],
  outputs: [
    { file: 'animation.mp4' }
  ]
}

Quality Control

Compress a video with specific quality settings:

const task = {
  inputs: [
    { file_path: 'dir_123/large-video.mp4' }
  ],
  outputs: [
    {
      file: 'compressed.mp4',
      options: ['-crf', '28', '-preset', 'medium']
    }
  ]
}

Extract Audio

Pull audio track from a video:

const task = {
  inputs: [
    { file_path: 'dir_123/movie.mp4' }
  ],
  outputs: [
    {
      file: 'soundtrack.mp3',
      options: ['-vn', '-acodec', 'mp3', '-ab', '192k']
    }
  ]
}

💡 Quick Reference: Common Output Options

Video Quality:

-crf 18 → High quality
-crf 23 → Good quality (default)
-crf 28 → Compressed

Audio Extraction:

-vn → No video
-acodec mp3 → MP3 format
-ab 192k → Audio bitrate

⚙️ Level 2: Intermediate Processing

Resize and Crop Videos

Resize to specific dimensions:

const task = {
  inputs: [
    { file_path: 'dir_123/fullhd-video.mp4' }
  ],
  outputs: [
    {
      file: 'mobile-video.mp4',
      options: [
        '-vf', 'scale=640:360',
        '-crf', '25'
      ]
    }
  ]
}

Trim Video Segments

Extract a 30-second clip starting at 1 minute:

const task = {
  inputs: [
    {
      file_path: 'dir_123/long-video.mp4',
      options: ['-ss', '60', '-t', '30']
    }
  ],
  outputs: [
    {
      file: 'highlight.mp4',
      options: ['-c:v', 'libx264', '-crf', '23']
    }
  ]
}

Multiple Output Files

Generate different versions from one input:

const task = {
  inputs: [
    { file_path: 'dir_123/source.mp4' }
  ],
  outputs: [
    {
      file: 'web-version.mp4',
      options: ['-vf', 'scale=1280:720', '-crf', '25']
    },
    {
      file: 'mobile-version.mp4',
      options: ['-vf', 'scale=640:360', '-crf', '28']
    },
    {
      file: 'audio-only.mp3',
      options: ['-vn', '-acodec', 'mp3']
    }
  ]
}

🚀 Level 3: Advanced Workflows

Multi-Input Processing

Combine separate video and audio:

const task = {
  inputs: [
    { file_path: 'dir_123/video.mp4' },
    { file_path: 'dir_123/audio.wav' }
  ],
  outputs: [
    {
      file: 'final.mp4',
      options: ['-c:v', 'copy', '-c:a', 'aac']
    }
  ]
}

Side-by-Side Video Comparison

Create split-screen view of two videos:

const task = {
  inputs: [
    { file_path: 'dir_123/before.mp4' },
    { file_path: 'dir_123/after.mp4' }
  ],
  filter_complex: '[0:v]scale=640:360[left];[1:v]scale=640:360[right];[left][right]hstack[out]',
  outputs: [
    {
      file: 'comparison.mp4',
      options: ['-c:v', 'libx264', '-crf', '23'],
      maps: ['[out]']
    }
  ]
}

Picture-in-Picture Overlay

Overlay a small video on top of a larger one:

const task = {
  inputs: [
    { file_path: 'dir_123/main-video.mp4' },
    { file_path: 'dir_123/overlay.mp4' }
  ],
  filter_complex: '[1:v]scale=320:180[overlay];[0:v][overlay]overlay=W-w-10:H-h-10[out]',
  outputs: [
    {
      file: 'picture-in-picture.mp4',
      options: ['-c:v', 'libx264', '-crf', '23'],
      maps: ['[out]', '0:a']
    }
  ]
}

Watermark Application

Add a logo watermark to a video:

const task = {
  inputs: [
    { file_path: 'dir_123/video.mp4' },
    { file_path: 'dir_123/logo.png' }
  ],
  filter_complex: '[0:v][1:v]overlay=W-w-10:10[out]',
  outputs: [
    {
      file: 'branded-video.mp4',
      options: ['-c:v', 'libx264', '-crf', '23'],
      maps: ['[out]', '0:a']
    }
  ]
}

Understanding Filter Complex

For advanced operations, filter_complex lets you create sophisticated processing pipelines:

// Filter syntax breakdown:

[0:v]scale=640:360[scaled];

│ │ │

Input Filter Output Label

Input References

[0:v] → Video from first input
[1:a] → Audio from second input
[2:v:0] → First video track from third input

Common Filters

scale=W:H → Resize video
hstack → Side-by-side layout
overlay=X:Y → Position overlay

Error Handling & Troubleshooting

❌ Error 400: “Invalid task format”

Check your task structure:

Ensure inputs and outputs are arrays
Verify all file_path values are strings
Options arrays should contain strings only
Output filenames must not conflict with inputs

❌ Error 500: “FFmpeg processing failed”

FFmpeg couldn’t process your command. Common causes:

Invalid FFmpeg options or syntax
Incompatible input/output formats
Complex filter syntax errors
Insufficient processing resources for large files

❌ Error 404: “File not found”

Referenced files don’t exist:

Verify file_path matches upload response exactly
Ensure all files are in the same directory
Check that files were successfully uploaded
List directory contents to confirm file presence

What’s Next?

📝 Advanced Examples

See complete, production-ready code examples for complex workflows.

📊 Monitor Usage

Understand how processing complexity affects your GB-seconds consumption.

Need more FFmpeg options? Check the Advanced Usage guide for comprehensive FFmpeg command reference and edge cases.

Files Examples