CLI Overview

Understanding MediaProc: The universal media processing toolkit for modern developers.

What is MediaProc?

MediaProc is a unified command-line interface for processing all types of media files. Instead of learning multiple tools like ImageMagick, FFmpeg, SoX, and others, MediaProc provides a single, consistent interface with a modern plugin architecture.

The Problem We Solve

Before Media\Proc

Modern applications often need to process different media types. Traditionally, this meant:

Multiple Tools, Multiple Syntaxes:

• Images: ImageMagick, GraphicsMagick, or Sharp
• Videos: FFmpeg with complex filter chains
• Audio: SoX, FFmpeg, or specialized tools
• Documents: Ghostscript, pdftk, libreoffice
• 3D Models: Blender, ImageMagick for textures

Result: Context switching, inconsistent APIs, steep learning curves, and fragile workflows.

After MediaProc

One Unified Interface:

Result: Consistent syntax, predictable behavior, one tool to learn, maintainable automation.

Key Features

1. Unified Interface

All plugins follow the same command structure:

mediaproc <plugin> <command> <input> [options]

Examples:

The pattern is always the same, making it intuitive and easy to remember.

2. Plugin Architecture

MediaProc is built on a plugin system. Install only what you need:

Official Plugins:

3. Battle-Tested Foundation

MediaProc doesn't reinvent the wheel. It provides a modern interface to industry-standard tools:

Powered by FFmpeg

• Video and audio processing
• Format conversion
• Codec support
• 20+ years of development

Powered by Sharp

• High-performance image processing
• Modern image formats (WebP, AVIF)
• Memory-efficient operations

Built with TypeScript

• Type-safe plugin development
• Excellent developer experience
• Modern async/await patterns

Architecture Overview

How It Works

Core Components:

1. CLI Core - Parses commands, loads plugins, handles errors
2. Plugins - Self-contained modules for specific media types
3. Processors - Low-level tools (FFmpeg, Sharp) that do the actual work

Why MediaProc Over Direct Tool Usage?

Example: Resizing an Image

Using Sharp directly (Node.js):

const sharp = require("sharp");

async function resizeImage() {
  try {
    await sharp("input.jpg")
      .resize(1920, 1080, {
        fit: "inside",
        withoutEnlargement: true,
      })
      .toFile("output.jpg");
  } catch (error) {
    console.error("Error:", error);
  }
}

Using ImageMagick:

convert input.jpg -resize 1920x1080\> -quality 90 output.jpg

Using MediaProc:

mediaproc image resize input.jpg --width 1920 --height 1080

Benefits:

• ✓ Consistent syntax across all operations
• ✓ Sensible defaults (quality, format, scaling)
• ✓ Clear, readable commands
• ✓ Excellent error messages
• ✓ Works the same on all platforms

Use Cases

1. Content Creation

Batch resize social media images:

Compress videos for web:

Normalize podcast audio:

2. CI/CD Automation

Optimize all images in build pipeline:

# .github/workflows/optimize-assets.yml
- name: Install MediaProc
  run: npm install -g @mediaproc/cli

- name: Add image plugin
  run: mediaproc add image

- name: Optimize images
  run: mediaproc image optimize assets/**/*.{jpg,png} --quality 85

3. Development Workflows

Generate responsive image sets:

Extract video thumbnails:

4. Data Processing

Extract metadata for ML training:

Batch transcode video datasets:

Command Structure

Anatomy of a MediaProc Command

mediaproc <plugin> <command> <input> [options]
   │        │         │         │        │
   │        │         │         │        └── Optional flags
   │        │         │         └────────── Input file(s)
   │        │         └──────────────────── Command to execute
   │        └────────────────────────────── Plugin name
   └─────────────────────────────────────── CLI entry point

Examples

Basic command:

mediaproc image resize photo.jpg --width 1920

Multiple inputs:

mediaproc image convert *.jpg --format webp

Multiple options:

mediaproc video transcode input.mp4 --codec h264 --bitrate 2M --fps 30

Output directory:

mediaproc image batch *.jpg --width 1920 -o processed/

Global Options

All commands support these global options:

Examples:

Performance Characteristics

MediaProc is designed for performance:

Multi-threading:

• Image processing uses Sharp's multi-threaded SIMD operations
• Video/audio processing leverages FFmpeg's multi-core support

Streaming:

• Large files are processed using streams (no full load into memory)
• Supports pipeline operations without intermediate files

Hardware Acceleration:

• GPU acceleration for video encoding (when available)
• SIMD optimizations for image operations

Benchmarks:

Comparison with Alternatives

vs. FFmpeg Directly

FFmpeg:

• ✓ Extremely powerful and flexible
• ✗ Complex syntax with many gotchas
• ✗ Inconsistent flag naming
• ✗ Poor error messages

MediaProc:

• ✓ Simple, consistent syntax
• ✓ Excellent error messages
• ✓ Sensible defaults
• ✓ Still uses FFmpeg under the hood

vs. ImageMagick

ImageMagick:

• ✓ Industry standard for decades
• ✗ Slower than modern alternatives
• ✗ Memory-intensive for large images
• ✗ Complex command syntax

MediaProc:

• ✓ Modern Sharp library (3-5x faster)
• ✓ Memory-efficient streaming
• ✓ Intuitive commands
• ✓ Better format support (WebP, AVIF)

vs. GUI Tools

GUI Tools (Photoshop, Premiere, etc.):

• ✓ User-friendly for one-off tasks
• ✗ Not automatable
• ✗ Expensive licensing
• ✗ Manual, time-consuming for batch operations

MediaProc:

• ✓ Fully scriptable and automatable
• ✓ Free and open source
• ✓ Batch processing built-in
• ✓ Perfect for CI/CD pipelines

Philosophy & Design Principles

1. Convention Over Configuration

Sensible defaults mean you rarely need to specify every option:

# Automatically preserves aspect ratio, chooses optimal quality
mediaproc image resize photo.jpg --width 1920

2. Fail Fast, Fail Clearly

Errors are descriptive and actionable:

3. Progressive Disclosure

Basic commands are simple; advanced options are available when needed:

Simple:

mediaproc video compress video.mp4

Advanced:

mediaproc video transcode video.mp4 \
  --codec h264 \
  --preset medium \
  --crf 23 \
  --hw-accel \
  --audio-codec aac \
  --audio-bitrate 192k

4. Composability

Commands work well in Unix pipelines and scripts:

# Find large images and compress them
find . -name "*.jpg" -size +2M | \
  xargs -I {} mediaproc image optimize {} --quality 80

Getting Started

Ready to try MediaProc? Follow the Installation Guide or jump into the Quick Start.

Learn More

• Plugin Architecture - How plugins work internally
• Troubleshooting - Common issues and solutions
• Community - Get help and contribute
• FFmpeg Official Docs
• Sharp API Docs
• Media Format Comparison (Wikipedia)