Type Safety

pycamtasia ships with py.typed, comprehensive enums, and TypedDicts so your editor and mypy can catch mistakes before runtime.

Enums for string constants

Instead of passing raw strings, use the typed enums from camtasia.types:

from camtasia.types import ClipType

# Filter clips by type
videos = [c for c in track.clips if c.clip_type == ClipType.VIDEO]

# Add a drop shadow effect
clip.add_drop_shadow()

# Add a dissolve transition between two clips
track.transitions.add_dissolve(clip_a, clip_b, duration_seconds=0.5)

Your editor will autocomplete the valid values and mypy will flag typos at check time.

Available enums

Enum	Purpose	Examples
ClipType	Clip media types	VIDEO, AUDIO, IMAGE, CALLOUT, GROUP
EffectName	Visual/audio effects	DROP_SHADOW, BLUR_REGION, COLOR_ADJUSTMENT
TransitionType	Transition styles	DISSOLVE, FADE, SLIDE_LEFT, GLITCH
BehaviorPreset	Animation presets	Motion behaviors for clips
BlendMode	Layer blend modes	Compositing modes
MaskShape	Mask geometries	Shape options for mask effects
CalloutShape	Callout shapes	Arrow, rectangle, etc.
ValidationLevel	Validation severity	Levels for project health checks
MediaType	Media categories	Audio, video, image classification

TypedDicts for structured data

When functions return or accept structured dictionaries, pycamtasia defines TypedDicts so you get key-completion and type checking:

from camtasia.types import DropShadowParams, ClipSummary

# TypedDict gives you autocomplete on keys
params: DropShadowParams = {
    "color": {"red": 0, "green": 0, "blue": 0, "alpha": 200},
    "angle": 315,
    "offset": 5,
    "blur": 10,
}

# ClipSummary from export functions
summary: ClipSummary  # has .name, .start, .duration, .clip_type, etc.

Literal types

Some parameters use Literal types for constrained values:

from camtasia.types import Alignment, ReportFormat

# Alignment: 0 (left), 1 (center), 2 (right)
caption.alignment: Alignment = 1

# ReportFormat: 'markdown' or 'json'
export_project_report(project, format="markdown")

Running mypy

pycamtasia is fully mypy-clean. Add it to your checks:

mypy --strict your_script.py

The py.typed marker means mypy will automatically pick up pycamtasia’s type information — no stubs needed.