Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI

Current command model

pixelflow supports three top-level workflows: rendering a script, printing final-output metadata for a script with --info, and printing version information with the version subcommand. Normal render invocation requires script path and -o output path. --info requires a script path but does not require -o.

Logging

The CLI writes PixelFlow log records at warn and error level to stderr by default. Use --loglevel LEVEL to lower or raise the minimum level. Accepted levels are trace, debug, info, warn, and error.

Use --logfile PATH to write log records to a file instead of stderr. This redirects only PixelFlow log records; render output, --info metadata, progress bars, timing reports, final render status line, and fatal top-level errors keep their documented stdout/stderr behavior.

Tracing

When built with the tracing Cargo feature, --trace FILE writes a Perfetto-compatible trace that can be opened in https://ui.perfetto.dev/. Trace output is separate from stdout, stderr diagnostics, log records, progress bars, timing reports, rendered video bytes, and props JSON.

Builds without the tracing feature accept the flag as a no-op so the same command line can be used with tracing and non-tracing binaries.

Plugin directories

pixelflow scans conventional platform plugin directories by default. Set PF_PLUGIN_DIRS to replace that list entirely. The same directory list is used for compiled plugins and script plugins.

PF_PLUGIN_DIRS uses the operating system path-list rules. In typical shell usage:

PF_PLUGIN_DIRS=/opt/pixelflow/plugins:$HOME/pixelflow/plugins pixelflow script.pf -o out.y4m

On Windows, use ; between entries instead of :. Empty path-list entries are ignored. Set PF_PLUGIN_DIRS to an empty value to disable plugin directory scanning.

Info pipeline

pixelflow --info <SCRIPT> reads and evaluates the script, indexes reachable FFMS2 sources so source media is concrete, validates the graph topology, prints final output clip dimensions, frame count, constant frame rate, and PixelFlow format name to stdout, then exits before executor construction and frame rendering.

Render pipeline

Current CLI flow is:

  1. read script source,
  2. evaluate script through pixelflow_script::ScriptEngine,
  3. index reachable FFMS2 sources,
  4. validate final graph,
  5. build built-in executors for reachable built-in filters,
  6. verify all reachable graph nodes have executors,
  7. render ordered frames to Y4M or rawvideo based on the final clip format.

Output limits

Current CLI output accepts only final clips with:

  • fixed format,
  • fixed resolution,
  • finite frame count,
  • constant frame rate, and
  • either Y4M-compatible integer Gray/YUV format or planar RGB format.

Convert unsupported final clips explicitly before rendering.