Skip to content

clip-state

Clip lifecycle state machine. Tracks a single clip from discovery through completed inference.

Bases: Enum

Processing lifecycle state of a single clip.

COMPLETE = 'COMPLETE' class-attribute instance-attribute

Inference has run and all output frames are written.

ERROR = 'ERROR' class-attribute instance-attribute

A stage failed. ClipEntry.error_message contains the detail.

EXTRACTING = 'EXTRACTING' class-attribute instance-attribute

Video source present but frame sequence not yet extracted.

RAW = 'RAW' class-attribute instance-attribute

Frame sequence present, no alpha hint.

READY = 'READY' class-attribute instance-attribute

Alpha hint present — clip can be submitted for inference.

A single clip with its processing state.

Construct via :func:from_clip (preferred) or directly for testing.

Attributes:

Name Type Description
clip Clip

Scanner output — resolved paths and alpha presence.
state ClipState

Current lifecycle state.
manifest object | None

Loader output, set after load() succeeds. None until the clip has been loaded.
in_out_range InOutRange | None

Optional sub-clip range. None means process all frames.
warnings list[str]

Non-fatal messages accumulated during scanning or processing.
error_message str | None

Set when state is ERROR.

has_outputs property

True if the Output directory contains at least one written frame.

is_processing property

True while a GPU job is actively working on this clip.

name property

Human-readable clip name.

output_dir property

Absolute path to the Output subdirectory.

root property

Absolute path to the clip folder.

completed_frame_count()

Number of frames that have all enabled outputs written.

completed_stems()

Frame stems that have outputs in every enabled output subdirectory.

Checks alpha/, fg/, comp/, and processed/ — whichever exist under Output/. Returns the intersection so a stem is only counted when all present output types have written it.

Returns:

Type Description
set[str]

Set of stem strings (e.g. {'frame_000001', 'frame_000002'}).

from_clip(clip) classmethod

Create a ClipEntry from a scanner Clip and resolve its initial state.

Parameters:

Name Type Description Default
clip Clip

Clip produced by the scanner stage.

 required

Returns:

Type Description
ClipEntry

ClipEntry with state resolved from what is present on disk.

refresh_state()

Re-resolve state from disk.

Call this after an external operation (alpha generation, inference) completes to bring the entry back in sync with the filesystem. Does nothing if is_processing is True.

set_error(message)

Transition to ERROR and record a message.

Parameters:

Name Type Description Default
message str

Human-readable description of the failure.

 required

set_processing(value)

Acquire or release the processing lock.

The job queue sets this to True before dispatching a job and False when the job completes or fails. Filesystem watchers should skip reclassification while this is True.

Parameters:

Name Type Description Default
value bool

True to lock, False to release.

 required

transition_to(new_state)

Attempt a validated state transition.

Parameters:

Name Type Description Default
new_state ClipState

Target state.

 required

Raises:

Type Description
InvalidStateTransitionError

If the transition is not in the table.

Inclusive in/out frame range for sub-clip processing.

Both indices are zero-based and inclusive.

Attributes:

Name Type Description
in_point int

First frame index to process.
out_point int

Last frame index to process (inclusive).

frame_count property

Number of frames in the range.

contains(index)

True if in_point <= index <= out_point.

to_frame_range()

Convert to a half-open (start, end) tuple for ClipManifest.frame_range.