CUTLASS.PY DOCS

API starter reference

A compact reference for the public Cutlass.py classes, functions, catalogs, and exceptions.

View markdown Open in ChatGPT Open in Claude Open in Cursor

Project

Project(name, fps=30, canvas="auto", background=None)
Project.load(path) -> Project

Key methods and properties:

Member	Purpose
`import_media(path)`	Probe a video or audio source and add it to the media pool.
`add_track(kind, name="", index=None)`	Add an explicit track.
`track(name)`	Look up a track by name.
`get_frame(t)`	Render an RGBA NumPy frame at timeline second `t`.
`export(path)`	Export the timeline to MP4 and return frames written.
`save(path)`	Save a `.cutlass` project document.
`duration`, `size`, `fps`	Read-only project facts.

Track

track.add(content, start, duration=None) -> Clip
track.append(content, duration=None) -> Clip

Track members:

name
kind
enabled
muted
locked
clips
clip_at(t)
end
remove()

Generated content such as Text and Solid requires an explicit duration.

Clip

Clip timing and structure:

start
end
duration
track
media
source_start
source_duration

Clip edit methods:

right = clip.split(at=7.0)
clip.trim(start=5.0, end=9.0)
clip.move(start=2.0)
clip.delete()
clip.ripple_delete()

Visual properties:

position
anchor
scale
rotation
opacity

Audio and media properties:

volume
fade_in
fade_out
speed
reversed
set_speed(factor, reverse=False)
crop(...)

Content descriptors

Construct content descriptors freely, then place them with track.add.

Text("Title", size=140, color="white")
Solid("#202840")
Rect(width=400, height=300, color="#ff0055")
Ellipse(width=200, height=200, color="white")
Polygon(6, width=220, height=220)
Star(5, inner_ratio=0.5)
Line(length=200, thickness=8)
Arrow(width=240, height=120)
Heart(width=220, height=200)

Catalogs and errors

Discovery functions:

cutlass.effects()
cutlass.transitions()

Primary exception types:

Exception	When it appears
`CutlassError`	Base error and stale handles.
`OverlapError`	Placement collides on the same track.
`TrackKindError`	Content does not match the target track kind.
`MediaError`	Probe, decode, source-window, or still-image failures.
`RenderError`	GPU render or encode failure.