Render scripts

Required arguments

pixelflow <SCRIPT> -o <PATH>

• <SCRIPT> is path to script file.
• -o <PATH> selects output destination. PixelFlow chooses the stream format from the final clip format.
• -o - writes the selected stream to stdout.

Command reads script, indexes reachable source(...) nodes, validates final graph, and writes either Y4M or rawvideo output.

Flags

--set NAME=VALUE

Pass script parameters as named values.

--start N

Start render at zero-based frame index N.

--end N

Stop before frame index N.

--threads N

Set the maximum render worker thread count. N must be a positive non-zero integer. PixelFlow may use fewer workers when the render graph’s ordering or concurrency limits would leave extra workers idle.

--timings

Print a per-node timing report to stderr after render completes and before the final render status line. Each row reports the number of frames produced by that node and its cumulative exclusive execution time. Dependency waits and ordered commit waits are not counted in the node total.

--trace FILE

Write a Perfetto-compatible trace to FILE when the binary is built with the tracing Cargo feature. The trace captures runtime setup, source indexing, scheduler waits, dependency requests, cache behavior, executor prepare/commit work, selected expensive filter phases, frame plane allocation/deallocation events, output writes, and final flushes.

Builds without the tracing feature accept --trace FILE as a no-op and do not create the file. --trace always requires a file path, cannot use -, and cannot use the same path as -o, --props, or --logfile.

DHAT heap profiling

Use the dhat-heap Cargo feature when you need call stacks and lifetime data for all heap allocations, not only frame plane storage. DHAT writes dhat-heap.json when the process exits normally or after a runtime error path that reaches PixelFlow’s main error handler.

cargo run -p pixelflow-cli --release --features dhat-heap -- demo.pf -o out.y4m

Open dhat-heap.json in DHAT’s viewer. Frame plane allocations should include AlignedBuffer::new_zeroed in their stack.

--props FILE

Write frame properties to FILE as JSON after rendering completes. The output is an array with one object per rendered frame, in the same order as the video output. Frame ranges from --start and --end also apply to the props array.

Unset properties are written as null. Boolean, integer, float, string, and array values use their matching JSON types. Rational values are written as objects with numerator and denominator fields. Binary blob values are written as arrays of byte values.

--props always writes to a file. It cannot be combined with --info, cannot use -, and cannot use the same path as -o.

--loglevel LEVEL

Set the minimum PixelFlow log level. The default is warn, which emits warnings and errors. Accepted values are trace, debug, info, warn, and error.

--logfile PATH

Write PixelFlow log records to PATH instead of stderr. Progress bars, timing reports, and the final render status line still use stderr.

Examples

pixelflow demo.pf -o out.y4m
pixelflow demo.pf -o - > out.y4m
pixelflow demo.pf -o out.y4m --set width=1280 --set fps=24000/1001
pixelflow demo.pf -o out.y4m --start 100 --end 200
pixelflow demo.pf -o out.y4m --threads 4 --timings
pixelflow demo.pf -o out.y4m --trace trace.pftrace
cargo run -p pixelflow-cli --features tracing -- demo.pf -o out.y4m --trace trace.pftrace
cargo run -p pixelflow-cli --release --features dhat-heap -- demo.pf -o out.y4m
pixelflow demo.pf -o out.y4m --props props.json
pixelflow demo.pf -o out.y4m --loglevel info --logfile pixelflow.log

Output formats

PixelFlow auto-detects the final clip format:

• Integer Gray and YUV clips are written as Y4M.
• Planar RGB clips are written as FFmpeg-compatible rawvideo.

Rawvideo has no header. When piping or importing RGB output into ffmpeg, pass the pixel format, frame size, and frame rate explicitly. PixelFlow planar RGB maps to FFmpeg planar GBR names:

Example for a 1920x1080 RGB clip at 24000/1001 fps:

pixelflow rgb.pf -o - | ffmpeg -f rawvideo -pixel_format gbrp -video_size 1920x1080 -framerate 24000/1001 -i - out.mkv

Progress output

When stderr is connected to an interactive terminal, PixelFlow shows indexing and rendering progress with transient progress bars. Progress bars are hidden in non-interactive shells so CI logs and redirected diagnostics avoid transient progress output.

After a successful render, PixelFlow prints a final render status line to stderr:

Output 500 frames in 2.40 seconds (208.73 fps)

When rendering to stdout with -o -, stdout carries only the selected output stream. Indexing progress may still appear on interactive stderr, rendering progress is suppressed, and the final render status line still goes to stderr.