clipwright-frames

MCP tool for still-frame extraction from video into images, OTIO markers, and a JSON manifest.

Extracts still frames from a video file using FFmpeg and writes:

• Image files (JPEG or PNG) to the specified output directory
• An OTIO timeline (frames.otio) with one zero-duration Marker per frame
• A JSON manifest (frames.json) listing each frame's path and timestamp

MCP Server Setup

Add clipwright-frames to your MCP client configuration:

{
  "mcpServers": {
    "clipwright-frames": {
      "command": "clipwright-frames",
      "args": []
    }
  }
}

Or using uvx without a global install:

{
  "mcpServers": {
    "clipwright-frames": {
      "command": "uvx",
      "args": ["--from", "clipwright-frames", "clipwright-frames"]
    }
  }
}

MCP Tool

clipwright_extract_frames

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

• data.frame_count: Number of frames extracted.
• data.mode: Extraction mode used ("interval", "scene", or "timestamps").
• data.format: Output image format used ("jpeg" or "png").
• artifacts[0]: The output OTIO timeline path (role: "timeline", format: "otio").
• artifacts[1]: The JSON manifest path (role: "manifest", format: "json").

Extraction Modes

interval (default)

Extracts one frame every interval_sec seconds throughout the video.

{
  "mode": "interval",
  "interval_sec": 10.0
}

scene

Extracts frames at scene boundaries detected by clipwright-scene. Requires an OTIO timeline produced by clipwright_detect_scenes.

{
  "mode": "scene",
  "scene_timeline": "/path/to/scenes.otio"
}

timestamps

Extracts frames at explicit timestamps (in seconds).

{
  "mode": "timestamps",
  "timestamps": [0.0, 5.5, 12.3, 30.0]
}

Options

ExtractFramesOptions fields:

Output Contract

All output is written to output_dir. The tool never modifies the input media file.

OTIO timeline (frames.otio)

An OTIO timeline with one zero-duration Marker per extracted frame on the V1 track.

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

JSON manifest (frames.json)

A JSON object with a frames array where each element describes one extracted frame:

{
  "count": 3,
  "mode": "interval",
  "format": "jpeg",
  "frames": [
    {
      "index": 0,
      "timestamp_sec": 0.0,
      "path": "/output/frame_00000.jpg"
    }
  ]
}

Prerequisites

FFmpeg (required)

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

export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
export CLIPWRIGHT_FFPROBE=/path/to/ffprobe

On Windows with winget:

winget install Gyan.FFmpeg

FFmpeg is used to seek to timestamps and extract frames. It is invoked as a subprocess and is never linked as a library.

Note: clipwright-frames also requires ffprobe (via inspect_media) for video-stream detection and duration probing, so CLIPWRIGHT_FFPROBE must be configured as well.

License

MIT