Action Reference¶

This page catalogues all built-in actions available in K-Pipe pipelines. Actions are referenced by class name in kpipe-publish.toml or kpipe-load.toml.

For how to declare and configure actions in a pipeline, see Pipeline Configuration.

Universal actions¶

These actions have no DCC dependency and can be used in any pipeline.

CollectImageFiles¶

Phase: collect
Scans a list of file paths or directories for image files and stores them as a LayeredSequencePipelineData in the output slot. Directories are scanned non-recursively. Unrecognised file types are skipped with a warning.

Supported extensions: .exr, .png, .jpg, .jpeg, .tif, .tiff, .hdr, .tga, .bmp

Field	Default	Description
`slot`	`"main"`	Output slot (writes `LayeredSequencePipelineData`)
`slot_in_paths`	`"main"`	Input slot containing a `list[str \\| Path]` of files or directories

CollectPBRTextureSet¶

Phase: collect
Classifies images from a LayeredSequencePipelineData slot into a TextureSetPipelineData by inferring PBR map type and colorspace from filenames. Common naming conventions are recognised automatically (e.g. _BaseColor, _roughness, _nrm, _AmbientOcclusion). Typically chained after CollectImageFiles.

If multiple files resolve to the same map type, the first one is kept and a warning is logged. Files with unrecognised names are skipped.

The publish layer name is read from ctx.layer — set by the layer selector in the publish UI — and falls back to the main layer when empty.

Field	Default	Description
`slot`	`"main"`	Output slot (writes `TextureSetPipelineData`)
`slot_in_images`	`"main"`	Input slot (reads `LayeredSequencePipelineData`)

ExtractBurnIn¶

Phase: extract
Composites text burn-ins onto an image sequence using OpenImageIO Python bindings. Reads a SequencePipelineData or LayeredSequencePipelineData from the slot, writes burned-in frames to a sibling temp directory (original directory name + _burnin), and updates the sequence path so downstream integrate actions pick up the new frames automatically.

Requires the openimageio package (import OpenImageIO). Raises PublishError if the bindings are not available.

Text fields accept Python format strings. Available variables:

Variable	Value
`{project}`	Entity project name
`{entity}`	String representation of the entity
`{task}`	Pipeline task name
`{version}`	Sequence version number (int)
`{frame}`	Current frame number (int)
`{date}`	Today's date as `YYYY-MM-DD`

Standard Python format specifiers work: {version:03d}, {frame:04d}, etc.

Field	Default	Description
`slot`	`"main"`	Input/output slot — accepts `SequencePipelineData` or `LayeredSequencePipelineData`
`top_left`	`""`	Text rendered top-left. Empty = skip
`top_center`	`""`	Text rendered top-center
`top_right`	`""`	Text rendered top-right
`bottom_left`	`""`	Text rendered bottom-left
`bottom_center`	`""`	Text rendered bottom-center
`bottom_right`	`""`	Text rendered bottom-right
`font_size`	`30`	Font size in pixels
`font_path`	`""`	Path to a font file. Empty uses the OIIO default font
`color`	`(0.8, 0.8, 0.8)`	Text colour as an RGB tuple
`shadow`	`2`	Drop-shadow size in pixels. `0` = no shadow
`padding_x`	`30`	Horizontal padding from the image edge in pixels
`padding_y`	`10`	Vertical padding from the image edge in pixels

Example:

[[pipeline.render_blender_cycles.extract]]
action = "ExtractBlenderRender"
slot   = "main"

[[pipeline.render_blender_cycles.extract]]
action        = "ExtractBurnIn"
slot          = "main"
top_left      = "{project} | {entity} | {task}"
top_right     = "{date}"
bottom_left   = "v{version:03d}"
bottom_right  = "{frame:04d}"

[[pipeline.render_blender_cycles.integrate]]
action = "IntegrateMedia"
slot   = "main"

IntegrateMedia¶

Phase: integrate
Moves or copies extracted media from temp render directories into the versioned publish tree and writes product metadata. Handles image sequences, videos, layered sequences, and texture sets.

Field	Default	Description
`slot`	`"main"`	Input slot — accepts `SequencePipelineData`, `VideoPipelineData`, `LayeredSequencePipelineData`, or `TextureSetPipelineData`
`remap_frames`	`false`	Remap frame numbers from `original_frame_range` to `frame_range` (1-based) on copy
`keep_files`	`true`	Copy files instead of moving them, leaving the source intact
`source_name`	`null`	Optional string recorded in the publish metadata as the source identifier

CleanMedia¶

Phase: integrate
Deletes the temp render folder(s) left behind by extract actions. Typically placed as the last integrate step. Safe to run even if the folder is already gone.

Field	Default	Description
`slot`	`"main"`	Slot containing pipeline data whose temp path to delete
`ignore_missing`	`true`	If `false`, raises an error when the temp folder does not exist

Blender actions¶

CollectBlenderCollection¶

Phase: collect
Collects all objects from a named Blender collection, or the current selection, into a slot as a list of objects.

Field	Default	Description
`slot`	`"main"`	Output slot (writes `list[bpy.types.Object]`)
`collection_name`	`""`	Name of the collection to collect. Takes priority over `use_selection`
`use_selection`	`false`	If `true` and `collection_name` is empty, collects currently selected objects

One of collection_name or use_selection must be set; neither raises a ValidationError.

CollectBlenderSingleFrame¶

Phase: collect
Collects a single frame number from the active Blender scene as SequencePipelineData. The output frame_range is always 1–1; original_frame_range holds the actual scene frame number, which IntegrateMedia uses when remap_frames = true.

Field	Default	Description
`slot`	`"main"`	Output slot (writes `SequencePipelineData`)
`use_current_frame`	`false`	`false` uses `scene.frame_start`; `true` uses `scene.frame_current`

CollectBlenderCamera¶

Phase: collect
Collects a camera object from the active Blender scene into a slot for use by ExtractBlenderRender.

Field	Default	Description
`slot`	`"camera"`	Output slot (writes `bpy.types.Object`)
`camera_name`	`""`	Name of a specific camera object. If empty, uses the scene's active camera

CollectBlenderStoryboardFrames¶

Phase: collect
Collects per-shot frame ranges from VSE storyboard strips into a LayeredSequencePipelineData. Each shot marker becomes one SequencePipelineData entry, with the layer set to {sequence}_{shot}.

Reads use_selected from ctx.settings — if true, only selected strips are processed.

Field	Default	Description
`slot`	`"main"`	Output slot (writes `LayeredSequencePipelineData`)

ExtractBlenderRender¶

Phase: extract
Renders frames from a SequencePipelineData (from slot_in_sequence) to a temp render path, using the camera from slot_in_camera. Saves and restores scene camera, render path, frame range, and file format after rendering.

Field	Default	Description
`slot_in_sequence`	`"main"`	Input slot (reads `SequencePipelineData`)
`slot_in_camera`	`"camera"`	Input slot (reads `bpy.types.Object` camera)
`slot`	`"main"`	Output slot (writes updated `SequencePipelineData` with path/format filled in)
`file_format`	`"PNG"`	Blender file format identifier. See table below

Supported file_format values:

Value	Extension
`PNG`	`.png`
`JPEG`	`.jpg`
`OPEN_EXR`	`.exr`
`OPEN_EXR_MULTILAYER`	`.exr`
`TIFF`	`.tif`
`BMP`	`.bmp`
`CINEON`	`.cin`
`DPX`	`.dpx`

ExtractBlenderSequencerFrames¶

Phase: extract
Renders frame ranges from the Blender VSE (OpenGL render) to temp render paths. Handles both a single SequencePipelineData and a LayeredSequencePipelineData (renders each layer separately). Saves and restores scene render settings after rendering.

Field	Default	Description
`slot_in_sequence`	`"main"`	Input slot (reads `SequencePipelineData` or `LayeredSequencePipelineData`)
`slot`	`"main"`	Output slot (writes the same data with path/format filled in)
`file_format`	`"PNG"`	Blender file format identifier (same values as `ExtractBlenderRender`)
`shading_type`	`"MATERIAL"`	VSE viewport shading. One of `WIREFRAME`, `SOLID`, `MATERIAL`, `RENDERED`

Blender load actions¶

Load actions are used in kpipe-load.toml and run as ordered [[pipeline.<key>.load]] steps.

The version and layer to load, and the reference id, are not step fields — they are provided on the pipeline context (ctx.version, ctx.layer, ctx.ref_id) by Session.load_product().

LoadBlenderMedia¶

Loads a published image, image sequence, or video as a Blender image datablock. The datablock is tagged with a kpipe_ref_id custom property linking it back to the reference entry in the sidecar file; if a datablock tagged with the same reference already exists it is reloaded in place rather than duplicated. Datablock names are purely cosmetic ("{entity} {product_type} [{layer}]") — identity always lives in the custom property, so the 63-character name limit and Blender's .001 dedup suffixes are harmless.

Field	Default	Description
`source`	`"AUTO"`	`AUTO` detects from metadata; or set explicitly to `SEQUENCE`, `MOVIE`, or `FILE`

AUTO detection rules: if frame-end > frame-start in the publish metadata → SEQUENCE; if the file extension is a known video format → MOVIE; otherwise → FILE.

LoadBlenderTextureSet¶

Loads all maps in a published texture set (layer = material name, ctx.layer) as individual Blender image datablocks, applying the colorspace stored in publish metadata. Colorspaces can be overridden per map via colorspace_override. Every created datablock is tagged with kpipe_ref_id (so the full set can be found and removed as a unit) and kpipe_map (the map name, e.g. base_color) custom properties; datablock names are cosmetic ("{entity} {product_type} [{layer}] {map}").

Field	Default	Description
`colorspace_override`	`{}`	Dict mapping map name to a Blender colorspace string, overriding stored metadata

SetupBlenderPBRMaterial¶

Wires texture-set datablocks into a Principled BSDF material node tree. Runs as a second [[load]] step after LoadBlenderTextureSet: it finds all image datablocks tagged with the current ctx.ref_id, identifies each map via the kpipe_map custom property, and connects it to the matching BSDF socket (normal maps get a Normal Map node in between).

The material is named after ctx.layer (the published texture-set layer name). If that is empty, the active material on the selected object is used; when neither yields a name the step is skipped (or raises if skip_no_mat = false).

Field	Default	Description
`normal_strength`	`1.0`	Strength value on the Normal Map node
`skip_no_mat`	`true`	Skip silently when no material name can be resolved instead of raising

Kitsu actions¶

IntegrateKitsuImage¶

Phase: integrate
Uploads a rendered still image as a preview revision on the current Kitsu task. Picks the first image file found in the render directory of the SequencePipelineData slot. Reads note from ctx.settings and attaches it as the revision comment.

Field	Default	Description
`slot`	`"main"`	Input slot (reads `SequencePipelineData`)
`task_status`	`""`	Short name of the Kitsu task status to set on upload (e.g. `"wfa"`). Empty = no change
`set_as_main`	`true`	Whether to set the uploaded preview as the entity's main thumbnail

IntegrateKitsuVideo¶

Phase: integrate
Uploads a rendered video as a preview revision on the current Kitsu task. Reads note from ctx.settings and attaches it as the revision comment.

Field	Default	Description
`slot`	`"main"`	Input slot (reads `VideoPipelineData`)
`task_status`	`""`	Short name of the Kitsu task status to set on upload (e.g. `"wfa"`). Empty = no change
`set_as_main`	`true`	Whether to set the uploaded preview as the entity's main thumbnail
`normalize_movie`	`true`	Let Kitsu re-encode the video for streaming. Set to `false` for pre-encoded files

K-Pipe GUI¶

Actions provided by the kpipe_gui package. They are registered automatically when kpipe_gui is imported.

CollectPublisherPaths¶

Phase: collect
Reads the file paths added in the K-Pipe Publisher tool and writes them to a slot as a list[PurePosixPath]. The publisher injects the dropped paths into ctx.settings["source_files"] before calling run_publish(). Raises PublishError if no files were provided.

Typically the first collect step in a publisher pipeline, feeding its output slot into a downstream action such as CollectImageFiles.

Field	Default	Description
`slot`	`"main"`	Output slot (writes `list[PurePosixPath]`)

Example:

[[pipeline.my_publisher_pipeline.collect]]
action = "CollectPublisherPaths"
slot   = "source_files"

[[pipeline.my_publisher_pipeline.collect]]
action = "CollectImageFiles"
slot_in_paths = "source_files"
slot          = "images"