Skip to content

README.md

Latest commit

 

History

History
149 lines (107 loc) · 3.8 KB

README.md

File metadata and controls

149 lines (107 loc) · 3.8 KB
Raw

@mediaproc/pipeline

Declarative YAML workflow runner for MediaProc, built on top of the Orbyt engine.

This plugin provides:

  • pipeline execution for one or multiple workflow files
  • schema and MediaProc-specific validation
  • execution plan explanation (including optional dependency graph)
  • multiple output formats for CLI and automation usage

What This Plugin Does

The pipeline plugin wraps Orbyt workflow execution and adds MediaProc-specific behavior:

  • creates an engine with MediaProcAdapter pre-registered
  • validates workflow actions in mediaproc.<plugin>.<command> format
  • validates input paths for MediaProc steps
  • supports execution modes for multi-workflow runs:
    • sequential
    • parallel
    • mixed

Commands

The plugin exposes three commands:

  • run <file>
  • validate <file>
  • explain <file>

<file> supports a single YAML path or comma-separated paths for run.

run

Execute one or more pipelines.

mediaproc-pipeline run ./workflows/image.yaml
mediaproc-pipeline run ./a.yaml,./b.yaml --mode parallel --max-concurrency 4

Options:

  • --dry-run validate and preview without executing steps
  • -v, --var <key=value...> set workflow input variables (repeatable)
  • --continue-on-error continue when individual steps fail
  • --mode <mode> sequential|parallel|mixed
  • --max-concurrency <n> limit parallel workflows
  • --mixed-batch-size <n> workflows per wave in mixed mode
  • -f, --format <format> human|json|verbose|null
  • --verbose detailed per-step output
  • --silent minimal output
  • --no-color disable ANSI colors

validate

Validate pipeline syntax and MediaProc constraints without execution.

mediaproc-pipeline validate ./workflows/image.yaml

Options:

  • -f, --format <format> human|json|verbose|null
  • --verbose show per-step validation summary
  • --silent minimal output
  • --no-color disable ANSI colors

explain

Show execution plan and dependency interpretation without running steps.

mediaproc-pipeline explain ./workflows/image.yaml
mediaproc-pipeline explain ./workflows/image.yaml --graph

Options:

  • -f, --format <format> human|json|verbose
  • --graph print ASCII dependency graph
  • --verbose detailed plan/config output
  • --silent minimal output
  • --no-color disable ANSI colors

Example Workflow

name: image-pipeline
version: "1.0"

inputs:
 inputDir:
  type: string
  default: ./input

steps:
 - id: optimize
  action: mediaproc.image.optimize
  input:
   input: ${inputs.inputDir}

 - id: convert
  action: mediaproc.image.convert
  needs: [optimize]
  input:
   input: ${inputs.inputDir}

Run with variables:

mediaproc-pipeline run ./workflows/image.yaml --var inputDir=./assets

Output Formats

  • human: default readable CLI output
  • verbose: detailed workflow and step event stream
  • json: machine-friendly structured output
  • null: suppresses formatted output (useful for scripts)

Plugin Registration (Embedded Mode)

When used as a plugin inside a parent CLI, register(program) attaches:

  • pipeline run
  • pipeline validate
  • pipeline explain

Standalone mode (mediaproc-pipeline) exposes the same command set without the pipeline prefix.

Architecture Notes

  • Engine creation: createOrbytEngine() registers MediaProcAdapter.
  • Validation path:
    • Orbyt workflow/schema validation
    • MediaProc workflow validator (action format + input path checks)
  • Event bridging:
    • Orbyt workflow/step events are mapped into CLI formatter events.

Troubleshooting

  • Workflow file not found: verify relative/absolute path passed to command.
  • Action parse errors: ensure action uses mediaproc.<plugin>.<command>.
  • Input path validation failures: ensure input exists and is readable.
  • Circular dependency on explain: fix needs relationships between steps.