Usage Guide

This page is the CLI-focused reference for power users, pipeline TDs, and automation. For the end-user desktop workflow, start with the README and launch the UI with renderkit ui.

Install For CLI Use

From a source checkout:

uv sync
uv run renderkit --help

If RenderKit is already installed or you are using a release build that adds the executable to PATH, use renderkit directly.

Command Overview

renderkit --help
renderkit ui
renderkit convert-exr-sequence INPUT_PATTERN OUTPUT_PATH [OPTIONS]
renderkit batch-convert ROOT [OPTIONS]
renderkit replace-sequence-with-mp4 INPUT_PATTERN OUTPUT_MP4 [OPTIONS]
renderkit batch-replace ROOT_PATH [OPTIONS]
renderkit contact-sheet INPUT_PATTERN OUTPUT_PATH [OPTIONS]

INPUT_PATTERN accepts common sequence styles:

render.%03d.exr
render.%04d.exr
render.%05d.exr
render.####.exr
render.$F4.exr

Printf-style patterns support the padding width used by the sequence, such as %03d, %04d, %05d, or another %0Nd width.

Conversion Recipes

Basic Review Movie

renderkit convert-exr-sequence render.%04d.exr output.mp4 --fps 24

Frame Range

renderkit convert-exr-sequence render.%04d.exr output.mp4 --fps 24 --start-frame 1001 --end-frame 1100

Resolution Override

Set both width and height when overriding resolution:

renderkit convert-exr-sequence render.%04d.exr output.mp4 --width 1920 --height 1080

Color Space Preset

renderkit convert-exr-sequence render.%04d.exr output.mp4 --color-space linear_to_rec709

Available presets:

• linear_to_srgb
• linear_to_rec709
• srgb_to_linear
• no_conversion

Codec And Quality

H.264 is the default. Use H.265 or AV1 when the review target supports it.

renderkit convert-exr-sequence render.%04d.exr output.mp4 --codec libx265 --quality 8
renderkit convert-exr-sequence render.%04d.exr output.mp4 --codec libaom-av1 --quality 8

--quality uses a 0-10 scale where 10 is highest quality.

Specific EXR Layer

renderkit convert-exr-sequence render.%04d.exr diffuse.mp4 --layer diffuse

Burn-ins

renderkit convert-exr-sequence render.%04d.exr output.mp4 --burnin-frame --burnin-layer --burnin-fps

Tune the burn-in background:

renderkit convert-exr-sequence render.%04d.exr output.mp4 --burnin-frame --burnin-opacity 45

Multi-AOV Contact Sheet Movie

Use contact-sheet mode on conversion when you want an MP4 grid of EXR layers/AOVs:

renderkit convert-exr-sequence render.%04d.exr contact_sheet.mp4 --contact-sheet --cs-columns 4

Useful grid controls:

renderkit convert-exr-sequence render.%04d.exr contact_sheet.mp4 --contact-sheet --cs-columns 3 --cs-thumb-width 512 --cs-padding 8
renderkit convert-exr-sequence render.%04d.exr contact_sheet.mp4 --contact-sheet --cs-no-labels

Still Contact Sheet

Use the contact-sheet command when you want one image instead of a video:

renderkit contact-sheet render.%04d.exr contact_sheet.jpg --columns 4 --thumb-width 512

Frame-range and layer filters work here too:

renderkit contact-sheet render.%04d.exr contact_sheet.jpg --layer diffuse --start-frame 1001 --end-frame 1012

Profiling

For one-off profiling:

renderkit convert-exr-sequence render.%04d.exr output.mp4 --fps 24 --profile

Choose an output file or directory:

renderkit convert-exr-sequence render.%04d.exr output.mp4 --profile --profile-out ./profiles

Profiling writes .prof data and a readable .prof.txt summary.

Automation Patterns

PowerShell Batch

$shots = Get-ChildItem .\shots -Directory
foreach ($shot in $shots) {
    $pattern = Join-Path $shot.FullName "render.%04d.exr"
    $output = Join-Path $shot.FullName "review.mp4"
    uv --native-tls run renderkit convert-exr-sequence $pattern $output --fps 24 --overwrite --no-progress
}

Use --no-progress when capturing stdout or stderr from automation. RenderKit also disables progress bars automatically when stderr is not an interactive terminal.

Bash Batch

for shot in shots/*; do
  renderkit convert-exr-sequence "$shot/render.%04d.exr" "$shot/review.mp4" --fps 24 --overwrite
done

Recursive Batch Convert

Use batch-convert when RenderKit should discover sequences recursively and write review MP4s plus audit manifests:

renderkit batch-convert G:\Projects\Data_folder --ext exr --out _review_mp4s --fps 24 --overwrite

By default, relative output and manifest paths are resolved under ROOT. Existing MP4s are skipped unless --overwrite is set. The command keeps processing after per-sequence failures and exits nonzero if any sequence failed.

Extension matching is case-insensitive, so --ext exr also finds .EXR frames. Output names are built from the relative folder path and sequence prefix. If multiple discovered sequences would write the same MP4 path in one run, RenderKit appends a numeric suffix such as _2.

Default manifests:

• _review_mp4s/renderkit_batch_manifest.csv
• _review_mp4s/renderkit_batch_results.jsonl

Each manifest record includes the source pattern, output path, frame count, frame range, output size, status, and error text. Use the JSONL file for automation that tails results while a batch is running, and the CSV file for review in spreadsheets or asset-management tools.

Verify Review MP4s

Use ffprobe when you need an independent readability check before publish or cleanup:

$reviews = Get-ChildItem G:\Projects\Data_folder\_review_mp4s -Filter *.mp4 -Recurse
foreach ($review in $reviews) {
    ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 $review.FullName | Out-Null
    if ($LASTEXITCODE -ne 0) {
        throw "ffprobe failed for $($review.FullName)"
    }
}

replace-sequence-with-mp4 --verify and batch-replace --verify run the same kind of MP4 readability check before replacement cleanup.

Compare Work And Publish Folders

Before replacing source EXRs, compare the work render tree against the publish tree so missing or extra sequence groups are visible. This PowerShell helper compares sequence keys by relative folder, filename prefix, extension, and frame padding:

function Get-RenderSequenceKeys($root) {
    Get-ChildItem $root -Recurse -File -Filter *.exr |
        ForEach-Object {
            if ($_.BaseName -match '^(.*?)(\d+)$') {
                $relativeDir = [System.IO.Path]::GetRelativePath($root, $_.DirectoryName)
                "$relativeDir\$($Matches[1])%0$($Matches[2].Length)d$($_.Extension.ToLower())"
            }
        } |
        Sort-Object -Unique
}

$workSequences = Get-RenderSequenceKeys "G:\Projects\shot\work"
$publishSequences = Get-RenderSequenceKeys "G:\Projects\shot\publish"
Compare-Object $workSequences $publishSequences

Rows marked <= exist only in the work folder. Rows marked => exist only in the publish folder. Run the comparison before destructive cleanup and keep the command output with the batch manifests when the result needs to be audited.

Safe Sequence Replacement

Use replace-sequence-with-mp4 after review movies have been approved and source frames can be replaced by the MP4. Start with a dry run:

renderkit replace-sequence-with-mp4 render.%04d.exr G:\reviews\render.mp4 --verify --delete-source --dry-run

When the dry run looks correct, remove --dry-run:

renderkit replace-sequence-with-mp4 render.%04d.exr G:\reviews\render.mp4 --verify --delete-source

The command detects the exact frames in INPUT_PATTERN, copies the replacement MP4 into the source sequence folder, optionally verifies the MP4 with ffprobe, and writes a JSONL audit record. When --delete-source is used without --dry-run, RenderKit verifies the copied MP4 before deleting source frames. Dry runs still require the replacement MP4 to exist, so the preflight cannot report a missing movie as replaceable.

Safety behavior:

• RenderKit only deletes frame files that are detected from INPUT_PATTERN.
• The audit report path is checked before copy or delete work begins.
• --dry-run writes an audit record but does not copy the MP4 or delete frames.
• --verify checks the replacement MP4 with ffprobe; non-dry-run deletion also verifies the copied MP4 before removing source frames.
• If verification, copying, deletion, or audit writing fails, the command exits with an error.

By default, the audit file is written next to the source sequence:

renderkit-replacement-audit.jsonl

Audit records are JSON objects with these fields:

Field	Description
timestamp	UTC timestamp for the attempt.
source_pattern	Sequence pattern passed to the command.
source_frames	Exact source frame files detected for replacement.
source_count	Number of detected source frames.
replacement_mp4	MP4 path supplied to the command.
copied_mp4	Destination MP4 path in the source sequence folder.
deleted_frames	Frames deleted, or frames that would be deleted during dry-run cleanup.
deleted_count	Number of deleted frames.
reclaimed_bytes	Bytes reclaimed by deletion, or bytes that would be reclaimed in a dry run.
dry_run	Whether the command avoided copy/delete work.
verified	Whether MP4 verification ran successfully.
copied	Whether RenderKit copied the MP4 into the source sequence folder.

Batch Replacement Cleanup

Use batch-replace when a folder tree contains EXR sequences and a review folder contains matching MP4s generated by batch-convert:

renderkit batch-replace G:\Projects\Data_folder --mp4-dir _review_mp4s --verify --delete-source --dry-run

--mp4-dir is relative to ROOT_PATH unless it is absolute. For each detected EXR sequence, RenderKit derives the expected MP4 name with the same relative-folder naming used by batch-convert, such as render.%04d.exr to render.mp4 at the root or shot_a/render.%04d.exr to shot_a_render.mp4 in a nested folder. It then runs the same verification and audit workflow as replace-sequence-with-mp4 and appends results to:

renderkit-batch-replace-audit.jsonl

Before using batch-replace, confirm the approved MP4s still use the names produced by batch-convert. If review movies were renamed by hand, use explicit replace-sequence-with-mp4 calls or stage renamed MP4s in --mp4-dir.

convert-exr-sequence Options

Option	Description	Default
INPUT_PATTERN	File pattern with a frame placeholder.	Required
OUTPUT_PATH	Output video file path.	Required
--prefetch-workers	Number of frame prefetch workers; use 1 to disable concurrent prefetch.	2
--fps	Frame rate. If omitted, RenderKit attempts auto-detection.	Auto-detect
--quality	Visual quality on a 0-10 scale.	10
--color-space	linear_to_srgb, linear_to_rec709, srgb_to_linear, or no_conversion.	linear_to_srgb
--width	Output width. Must be paired with --height.	Source width
--height	Output height. Must be paired with --width.	Source height
--codec	FFmpeg codec, commonly libx264, libx265, or libaom-av1.	libx264
--layer	EXR layer/AOV to extract.	None
--start-frame	Start frame number.	First frame
--end-frame	End frame number.	Last frame
--overwrite	Overwrite output file if it exists.	False
--burnin-frame	Burn in frame number.	False
--burnin-layer	Burn in layer name.	False
--burnin-fps	Burn in frame rate.	False
--burnin-opacity	Burn-in background opacity from 0-100.	30
--contact-sheet	Enable multi-AOV grid movie mode.	False
--cs-columns	Contact sheet columns.	4
--cs-thumb-width	Width of each contact sheet layer cell.	Source resolution
--cs-padding	Spacing between contact sheet cells.	4
--cs-no-labels	Disable layer name labels.	False
--profile	Enable cProfile output for this conversion.	False
--profile-out	Output .prof path or directory.	Temp dir
--no-progress	Disable progress bars for stable captured logs.	False

batch-convert Options

Option	Description	Default
ROOT	Directory tree to scan recursively.	Required
--ext	Frame extension to discover, with or without a leading dot.	exr
--out	Output directory for generated MP4 files. Relative paths resolve under ROOT.	_review_mp4s
--prefetch-workers	Number of frame prefetch workers; use 1 to disable concurrent prefetch.	2
--fps	Frame rate. If omitted, RenderKit attempts auto-detection per sequence.	Auto-detect
--quality	Visual quality on a 0-10 scale.	10
--color-space	linear_to_srgb, linear_to_rec709, srgb_to_linear, or no_conversion.	linear_to_srgb
--width	Output width. Must be paired with --height.	Source width
--height	Output height. Must be paired with --width.	Source height
--codec	FFmpeg codec, commonly libx264, libx265, or libaom-av1.	libx264
--layer	EXR layer/AOV to extract.	None
--overwrite	Overwrite output files if they exist.	False
--manifest-csv	CSV manifest path. Relative paths resolve under ROOT.	OUTPUT_DIR/renderkit_batch_manifest.csv
--manifest-jsonl	JSONL results path. Relative paths resolve under ROOT.	OUTPUT_DIR/renderkit_batch_results.jsonl
--no-progress	Disable progress bars for stable captured logs.	False

replace-sequence-with-mp4 Options

Option	Description	Default
INPUT_PATTERN	Source sequence pattern with a frame placeholder.	Required
OUTPUT_MP4	Replacement MP4 to copy into the source sequence folder.	Required
--delete-source	Delete source frames after the replacement MP4 is verified.	False
--verify	Verify the replacement MP4 with ffprobe before replacing frames.	False
--dry-run	Print and audit planned changes without copying or deleting files.	False
--audit-report	JSONL audit report path.	Source folder renderkit-replacement-audit.jsonl

batch-replace Options

Option	Description	Default
ROOT_PATH	Directory tree to scan for EXR sequences.	Required
--mp4-dir	Directory containing replacement MP4s. Relative paths resolve under ROOT_PATH.	_review_mp4s
--delete-source	Delete source frames after each replacement MP4 is verified.	False
--verify	Verify each replacement MP4 with ffprobe before replacing frames.	False
--dry-run	Print and audit planned changes without copying or deleting files.	False
--audit-report	JSONL audit report path.	ROOT_PATH/renderkit-batch-replace-audit.jsonl

contact-sheet Options

Option	Description	Default
INPUT_PATTERN	File pattern with a frame placeholder.	Required
OUTPUT_PATH	Output image path.	Required
--columns	Number of grid columns.	4
--thumb-width	Width of each thumbnail.	Source resolution
--padding	Padding between thumbnails.	4
--no-labels	Disable layer labels below thumbnails.	False
--font-size	Label font size.	16
--layer	EXR layer/AOV to extract.	None
--start-frame	Start frame number.	First frame
--end-frame	End frame number.	Last frame
--overwrite	Overwrite output file if it exists.	False

Environment Variables

• IMAGEIO_FFMPEG_EXE: Path to a custom ffmpeg binary; overrides the bundled or PATH ffmpeg.
• RENDERKIT_FFMPEG_LOG: FFmpeg report logging. Use 0 to disable, 1 for a temp log, or a full file path.
• RENDERKIT_PROFILE: Enable cProfile output for UI/CLI when set to 1, true, or yes.
• RENDERKIT_PROFILE_OUT: Output .prof path or directory.
• RENDERKIT_LOG_PATH: Override RenderKit log file path.
• RENDERKIT_LOG_LEVEL: Logging level, such as DEBUG, INFO, or WARNING.
• QT_BACKEND: Force a Qt backend. PySide6 is the supported backend.

Operational Notes

• FPS auto-detection logs a warning when metadata probing is unavailable or image metadata cannot be read, then falls back to the configured/default FPS behavior.
• OCIO conversions use RenderKit's bundled OCIO config.
• OCIO conversion failures include diagnostics in the RenderKit log, including role and color-space resolution details, available color-space samples, and bundled LUT/config checks where possible.

Desktop UI From The CLI

renderkit ui

The hidden renderkit gui alias also launches the desktop UI for older scripts, but renderkit ui is the public command.

Python API

Use the API when integrating RenderKit into another tool instead of shelling out.

from renderkit import RenderKit

processor = RenderKit()
processor.convert_exr_sequence_to_mp4(
    input_pattern="render.%04d.exr",
    output_path="output.mp4",
    fps=24.0,
    quality=10,
    codec="libx264",
)

For complex setups, build an explicit config:

from renderkit import RenderKit
from renderkit.core.config import ContactSheetConfig, ConversionConfigBuilder
from renderkit.processing.color_space import ColorSpacePreset

config = (
    ConversionConfigBuilder()
    .with_input_pattern("render.%04d.exr")
    .with_output_path("output.mp4")
    .with_fps(24.0)
    .with_color_space_preset(ColorSpacePreset.OCIO_CONVERSION)
    .with_explicit_input_color_space("ACES - ACEScg")
    .with_resolution(3840, 2160)
    .with_codec("libx264")
    .with_contact_sheet(
        True,
        ContactSheetConfig(columns=4, padding=10, show_labels=True),
    )
    .build()
)

processor = RenderKit()
processor.convert_with_config(config)