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

Parameter Type Required Description
media string yes Input video file path.
output string yes Output OTIO timeline file path (must end in .otio).
options DetectScenesOptions no Detection options (see Options section).
timeline string no Existing OTIO timeline path to augment. When provided, markers are appended to the V1 track instead of creating a new timeline.

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:

Field Type Default Description
threshold float (0.0–1.0) 0.3 Scene change sensitivity. Lower = more sensitive. AI agents should use ~0.5 for major cuts only, ~0.1 for subtle transitions.
min_scene_duration float (≥ 0.0) 1.0 Minimum seconds between boundaries. Closer boundaries are merged (highest confidence kept). Set 0.0 to disable merging.
backend "ffmpeg" | "pyscenedetect" "ffmpeg" Detection backend. "ffmpeg" uses the built-in scdet filter. "pyscenedetect" uses the scenedetect CLI (requires install).

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.

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:

Key Type Description
kind string Always "scene_boundary".
scene_index int 0-based sequential index.
confidence float 0.0–1.0. FFmpeg: normalized scdet score. PySceneDetect: always 1.0.
backend string Backend that produced this boundary ("ffmpeg" or "pyscenedetect").
tool string Always "clipwright-scene".
version string Package version.

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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for satoh-y-0323 from gravatar.com satoh-y-0323

Credits

Author: satoh-y-0323

License

MIT

Requires

Python >=3.11

Provides Extra

pyscenedetect

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clipwright_scene-0.2.0.tar.gz (11.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

clipwright_scene-0.2.0-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

File details

Details for the file clipwright_scene-0.2.0.tar.gz.

File metadata

  • Download URL: clipwright_scene-0.2.0.tar.gz
  • Upload date:
  • Size: 11.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for clipwright_scene-0.2.0.tar.gz
Algorithm Hash digest
SHA256 db0e52c73c7bd3ab32396e0ab7d84f28b0cff1f4ec1822f2eaa835b399568651
MD5 ccda57317df466c63163c914c1467012
BLAKE2b-256 d7ed0a621a766e7367ced235d1351ae7bceb972e7c4e81be91f6f829aafaa05e

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_scene-0.2.0.tar.gz:

Publisher: publish.yml on satoh-y-0323/clipwright

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file clipwright_scene-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for clipwright_scene-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 79d7c015a2583898dcc6574563bf561239c08876d30fff9b617132c96ab3fb1b
MD5 d15aa8113b873991e3a39f9192f176cd
BLAKE2b-256 5fb530f8c569cfcdc5623ce8ec13bbf441a3108bd1860ca9cb8e6bec3c289cce

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_scene-0.2.0-py3-none-any.whl:

Publisher: publish.yml on satoh-y-0323/clipwright

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page