Operation Registry

The operation registry provides machine-readable metadata for all video operations in videopython. It allows downstream tools - including LLMs and AI agents - to discover available operations, their parameters, and capabilities without importing internal modules or parsing docstrings.

Every operation has an LLM-optimized description and rich JSON Schema constraints (minimum, maximum, enum, exclusive_minimum, etc.) so models can generate valid parameters on the first try. For a complete guide on using the registry in LLM workflows, see the LLM Integration Guide.

Quick Start

from videopython.base import get_operation_specs, get_operation_spec, OperationCategory

# List all registered operations
specs = get_operation_specs()
for op_id, spec in specs.items():
    print(f"{op_id}: {spec.description}")

# Look up a specific operation (by ID or alias)
spec = get_operation_spec("cut")
print(spec.to_json_schema())

# AI operations are registered when videopython.ai is imported
import videopython.ai
specs = get_operation_specs()
assert "face_crop" in specs

Operation Categories

Each operation belongs to one of four categories, defined by OperationCategory:

Category	Apply signature	Description
TRANSFORMATION	apply(video) -> Video	Modifies video structure (cut, resize, crop)
EFFECT	apply(video, start?, stop?) -> Video	Applies visual effects over a time range
TRANSITION	apply((video, video)) -> Video	Combines two videos with a transition
SPECIAL	Non-standard	Operations with unique signatures

Capability Tags

Operations are tagged with capability metadata used for filtering:

• changes_duration - Operation may change video duration
• changes_dimensions - Operation may change video dimensions
• changes_fps - Operation may change frame rate
• multi_source - Operation accepts additional video inputs
• multi_source_only - Operation requires multiple video inputs
• requires_transcript - Operation requires transcription data
• requires_faces - Operation requires face detection (AI)

from videopython.base import get_specs_by_tag, get_specs_by_category, OperationCategory

# Get all operations that change dimensions
dimension_ops = get_specs_by_tag("changes_dimensions")

# Get all effects
effects = get_specs_by_category(OperationCategory.EFFECT)

Registering Custom Operations

Use spec_from_class to register your own operations:

from videopython.base import Video, register, spec_from_class, OperationCategory

class MyCustomEffect:
    """Apply a custom visual effect."""
    def __init__(self, intensity: float = 0.5):
        self.intensity = intensity

    def apply(self, video: Video, start: float | None = None, stop: float | None = None) -> Video:
        ...

spec = spec_from_class(
    MyCustomEffect,
    op_id="my_custom_effect",
    category=OperationCategory.EFFECT,
    tags={"custom"},
)
register(spec)

spec_from_class introspects both the constructor and apply method signatures to build parameter schemas automatically. The video, videos, and transcription parameters are excluded from the apply schema by default. Use exclude_params / exclude_apply_params for non-JSON-serializable arguments and param_overrides / apply_param_overrides to add constraints like minimum/maximum.

JSON Schema Generation

Every OperationSpec can generate JSON Schemas for both constructor arguments and apply method arguments:

spec = get_operation_spec("cut")

# Constructor args schema
schema = spec.to_json_schema()
# {
#     "type": "object",
#     "properties": {
#         "start": {"type": "number", "description": "..."},
#         "end": {"type": "number", "description": "..."}
#     },
#     "required": ["start", "end"],
#     "additionalProperties": false
# }

# Apply args schema (e.g. for effects with start/stop)
spec = get_operation_spec("blur_effect")
apply_schema = spec.to_apply_json_schema()
# {
#     "type": "object",
#     "properties": {
#         "start": {"type": "number", ...},
#         "stop": {"type": "number", ...}
#     },
#     "required": [],
#     "additionalProperties": false
# }

Transformations and transitions typically have an empty apply schema (no extra arguments beyond the video input), while effects expose start/stop parameters.

Registered Operations

Base Operations

ID	Class	Category	Tags
cut_frames	CutFrames	transformation	changes_duration
cut	CutSeconds	transformation	changes_duration
resize	Resize	transformation	changes_dimensions
resample_fps	ResampleFPS	transformation	changes_fps
crop	Crop	transformation	changes_dimensions
speed_change	SpeedChange	transformation	changes_duration
picture_in_picture	PictureInPicture	transformation	multi_source
blur_effect	Blur	effect	--
zoom_effect	Zoom	effect	--
color_adjust	ColorGrading	effect	--
vignette	Vignette	effect	--
ken_burns	KenBurns	effect	--
full_image_overlay	FullImageOverlay	effect	--
instant_transition	InstantTransition	transition	multi_source_only
fade_transition	FadeTransition	transition	changes_duration, multi_source_only
blur_transition	BlurTransition	transition	changes_duration, multi_source_only
stack_videos	StackVideos	special	multi_source_only, changes_dimensions
reverse	Reverse	transformation	--
freeze_frame	FreezeFrame	transformation	changes_duration
silence_removal	SilenceRemoval	transformation	requires_transcript, changes_duration
fade	Fade	effect	--
volume_adjust	VolumeAdjust	effect	--
text_overlay	TextOverlay	effect	--
add_subtitles	TranscriptionOverlay	special	requires_transcript

AI Operations (require import videopython.ai)

ID	Class	Category	Tags
face_crop	FaceTrackingCrop	transformation	requires_faces, changes_dimensions
split_screen	SplitScreenComposite	transformation	requires_faces, multi_source, changes_dimensions