Builders

class camtasia.builders.TimelineBuilder(project)[source]

Bases: object

High-level builder for assembling Camtasia timelines.

Provides a cursor-based API for sequentially placing clips with automatic timing management.

Usage:

builder = TimelineBuilder(project) builder.add_audio_sequence([‘intro.wav’, ‘main.wav’], pause=1.0) builder.add_background_image(‘bg.png’) builder.add_title(‘My Video’, duration=5.0)

property cursor: float

Current timeline position in seconds.

advance(seconds)[source]

Move cursor forward by seconds.

Return type:

TimelineBuilder

seek(seconds)[source]

Set cursor to an absolute position.

Return type:

TimelineBuilder

add_audio(file_path, *, track_name='Audio', duration=None)[source]

Import and place an audio file at the cursor position.

Advances the cursor by the clip duration.

Return type:

BaseClip

add_pause(seconds)[source]

Add a pause (advance cursor without placing a clip).

Return type:

TimelineBuilder

add_image(file_path, *, track_name='Content', duration=5.0)[source]

Import and place an image at the cursor position.

Does NOT advance the cursor (images are visual overlays).

Return type:

BaseClip

add_title(text, *, track_name='Titles', duration=5.0, subtitle='')[source]

Add a title card at the cursor position.

Does NOT advance the cursor.

Return type:

BaseClip

camtasia.builders.build_from_screenplay(project, screenplay, audio_dir, *, audio_track_name='Audio', default_pause=1.0, vo_file_resolver=None)[source]

Build a timeline from a parsed screenplay.

Places voiceover audio clips sequentially with pauses between them. Uses the TimelineBuilder cursor for automatic timing.

Note

Pauses are placed after all VO blocks in each section rather than interleaved with individual VO blocks. This is a design limitation of the current section-based iteration.

Parameters:

  • project (Project) – Target project.

  • screenplay (Screenplay) – Parsed Screenplay object.

  • audio_dir (str | Path) – Directory containing VO audio files.

  • audio_track_name (str) – Name for the audio track.

  • default_pause (float) – Default pause between VO blocks (seconds).

  • vo_file_resolver (Optional[Callable[[VOBlock], str | Path | None]]) – Optional callback to resolve VO block to audio file path. If None, looks for files matching the VO ID pattern.

Return type:

ScreenplayBuildResult

Returns:

Summary dict with counts.

class camtasia.builders.TileLayout(project, track_prefix='Tile')[source]

Bases: object

Place images in a grid layout on the timeline.

add_grid(image_paths, start_seconds, end_seconds, grid=(2, 2), stagger_seconds=0.0, scale=1.0, fade_in_seconds=0.5)[source]

Place images in a grid layout.

Parameters:

  • image_paths (list[Path | str]) – Images to place in the grid.

  • start_seconds (float) – When the first tile appears.

  • end_seconds (float) – When all tiles disappear.

  • grid (tuple[int, int]) – (rows, cols) grid dimensions.

  • stagger_seconds (float) – Delay between each tile appearing.

  • scale (float) – Scale factor for each tile.

  • fade_in_seconds (float) – Fade-in duration for each tile.

Return type:

list[BaseClip]

property tiles: list[BaseClip]

All placed tile clips.

class camtasia.builders.timeline_builder.TimelineBuilder(project)[source]

Bases: object

High-level builder for assembling Camtasia timelines.

Provides a cursor-based API for sequentially placing clips with automatic timing management.

Usage:

builder = TimelineBuilder(project) builder.add_audio_sequence([‘intro.wav’, ‘main.wav’], pause=1.0) builder.add_background_image(‘bg.png’) builder.add_title(‘My Video’, duration=5.0)

property cursor: float

Current timeline position in seconds.

advance(seconds)[source]

Move cursor forward by seconds.

Return type:

TimelineBuilder

seek(seconds)[source]

Set cursor to an absolute position.

Return type:

TimelineBuilder

add_audio(file_path, *, track_name='Audio', duration=None)[source]

Import and place an audio file at the cursor position.

Advances the cursor by the clip duration.

Return type:

BaseClip

add_pause(seconds)[source]

Add a pause (advance cursor without placing a clip).

Return type:

TimelineBuilder

add_image(file_path, *, track_name='Content', duration=5.0)[source]

Import and place an image at the cursor position.

Does NOT advance the cursor (images are visual overlays).

Return type:

BaseClip

add_title(text, *, track_name='Titles', duration=5.0, subtitle='')[source]

Add a title card at the cursor position.

Does NOT advance the cursor.

Return type:

BaseClip

Build a timeline from a parsed screenplay.

camtasia.builders.screenplay_builder.build_from_screenplay(project, screenplay, audio_dir, *, audio_track_name='Audio', default_pause=1.0, vo_file_resolver=None)[source]

Build a timeline from a parsed screenplay.

Places voiceover audio clips sequentially with pauses between them. Uses the TimelineBuilder cursor for automatic timing.

Note

Pauses are placed after all VO blocks in each section rather than interleaved with individual VO blocks. This is a design limitation of the current section-based iteration.

Parameters:

  • project (Project) – Target project.

  • screenplay (Screenplay) – Parsed Screenplay object.

  • audio_dir (str | Path) – Directory containing VO audio files.

  • audio_track_name (str) – Name for the audio track.

  • default_pause (float) – Default pause between VO blocks (seconds).

  • vo_file_resolver (Optional[Callable[[VOBlock], str | Path | None]]) – Optional callback to resolve VO block to audio file path. If None, looks for files matching the VO ID pattern.

Return type:

ScreenplayBuildResult

Returns:

Summary dict with counts.