Usage Modes

DevPixelForge (dpf) communicates over JSON via stdin/stdout. You choose the mode that best fits your workload.

Comparison

Mode	Command	Best for
One-shot	`dpf process --job '{...}'`	Single operations, simple scripts
Stdin pipe	`echo '{...}' \| dpf`	Shell pipelines, CI steps
Streaming	`dpf --stream`	Multiple operations with low latency
Batch	`dpf batch --file jobs.json`	Parallel job processing

Modes

One-shot
Stdin pipe
Streaming
Batch

Spawn the binary once per job. The process exits after returning a single JSON result. Use this for infrequent or isolated operations.

./dpf/target/release/dpf process \
  --job '{"operation":"resize","input":"image.png","output_dir":"out","widths":[320,640]}'

Example job — resize to multiple widths:

{
  "operation": "resize",
  "input": "image.png",
  "output_dir": "out",
  "widths": [320, 640, 1024],
  "format": "webp",
  "quality": 85
}

Response:

{
  "success": true,
  "operation": "resize",
  "outputs": [
    { "path": "out/320-image.webp", "format": "webp", "width": 320, "height": 213, "size_bytes": 12480 },
    { "path": "out/640-image.webp", "format": "webp", "width": 640, "height": 427, "size_bytes": 28160 },
    { "path": "out/1024-image.webp", "format": "webp", "width": 1024, "height": 683, "size_bytes": 52320 }
  ],
  "elapsed_ms": 42
}

Pipe a JSON job directly into dpf over stdin. Useful in shell scripts and CI pipelines where you build the job dynamically.

echo '{"operation":"optimize","inputs":["image.png"],"output_dir":"out"}' | ./dpf/target/release/dpf

Example job — convert PNG to JPEG:

{
  "operation": "convert",
  "input": "photo.png",
  "output": "out/photo.jpg",
  "format": "jpeg",
  "quality": 90
}

Piped form:

echo '{"operation":"convert","input":"photo.png","output":"out/photo.jpg","format":"jpeg","quality":90}' \
  | ./dpf/target/release/dpf

Start the engine once with --stream. It reads one JSON job per line from stdin and writes one JSON result per line to stdout. The process stays alive, so you avoid binary-spawn overhead on every request.

./dpf/target/release/dpf --stream

Send jobs line by line:

{"operation":"resize","input":"a.png","output_dir":"out","widths":[320]}
{"operation":"optimize","inputs":["b.png"],"output_dir":"out"}
{"operation":"watermark","input":"c.png","output":"out/c.png","text":"© 2024"}

Each line produces one JSON result on stdout before the next job is read.Example job — add a text watermark:

{
  "operation": "watermark",
  "input": "hero.png",
  "output": "out/hero-branded.png",
  "text": "© 2024",
  "position": "bottom-right",
  "opacity": 0.8,
  "font_size": 24,
  "color": "#FFFFFF"
}

The Go StreamClient wraps the streaming mode and handles the stdin/stdout protocol for you. See the Streaming Client guide for details.

Pass a JSON file containing an array of jobs. dpf processes them in parallel using Rayon and returns a single aggregated result.

./dpf/target/release/dpf batch --file jobs.json

Example jobs.json:

{
  "operation": "batch",
  "jobs": [
    {
      "operation": "resize",
      "input": "hero.png",
      "output_dir": "out/responsive",
      "widths": [320, 640, 1024]
    },
    {
      "operation": "optimize",
      "inputs": ["hero.png"],
      "output_dir": "out/optimized"
    },
    {
      "operation": "convert",
      "input": "hero.png",
      "output": "out/hero.avif",
      "format": "avif"
    }
  ],
  "parallel": true
}

See the Batch Processing guide for the full Go API and real-world patterns.

Get Started

Usage Guide

Development

Comparison

Modes

Build docs developers (and LLMs) love

Get Started

Usage Guide

Development

​Comparison

​Modes

Build docs developers (and LLMs) love

Comparison

Modes