clipwright-scene

MCP tool for shot boundary detection.

Detects scene cuts in video files using FFmpeg's scdet filter (built-in, no extra install) or PySceneDetect (optional, more accurate). Boundaries are written as zero-duration OTIO markers on the V1 track of an output timeline.

MCP Tool

clipwright_detect_scenes

Return value: Standard ToolResult envelope — { ok, summary, data, artifacts, warnings }.

• data.scene_count: Number of scene boundaries detected.
• data.backend: Backend used ("ffmpeg" or "pyscenedetect").
• data.total_duration_sec: Total duration of the media in seconds.
• artifacts[0]: The output .otio file path (role: "timeline", format: "otio").

Options

DetectScenesOptions fields:

Prerequisites

FFmpeg (required)

FFmpeg must be available on PATH or specified via the CLIPWRIGHT_FFMPEG environment variable:

export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg

On Windows with winget:

winget install Gyan.FFmpeg

PySceneDetect (optional)

Required only when options.backend = "pyscenedetect". Install via pip:

pip install scenedetect

Or install the optional extra:

pip install "clipwright-scene[pyscenedetect]"

Note: PySceneDetect performs a full video decode and is significantly slower than the FFmpeg backend. It may produce more accurate results for content-based detection. Verified with PySceneDetect 0.7+.

Output

The output is an OTIO timeline file containing zero-duration Marker objects on the V1 track. Each marker represents a detected shot boundary (an instantaneous point event, not an interval).

Marker metadata

Each marker's metadata["clipwright"] contains:

Augment mode

Provide an existing .otio file via the timeline parameter to append scene markers to a previously created timeline (e.g., one produced by clipwright-transcribe or clipwright-silence). No clips are added or removed; only markers are appended.