clipwright-reframe

MCP tool that annotates a reframe directive (target resolution / fit mode / anchor) to an OTIO timeline for aspect-ratio conversion and delivery-format preparation.

Overview

clipwright-reframe writes a reframe directive to metadata["clipwright"]["reframe"] in an OTIO timeline file. The directive is materialised by clipwright-render as an FFmpeg filter chain in a single render pass (design M3: separation of annotation and realisation).

Fit modes:

Prerequisites

• Python 3.11 or later
• clipwright core package (shared types, envelope, OTIO utils)
• No FFmpeg dependency at annotation time (FFmpeg is only required by clipwright-render at realisation time)
• For mode="track": the optional [track] extra (numpy), installed in a separate detection process. When numpy is not installed, track mode still works but degrades gracefully to a static centre crop (see Fallback behaviour).

MCP Tool: clipwright_reframe

Parameters

When mode="track" is selected, the tool runs motion-centroid detection automatically and writes the resulting keyframe track into the directive — the track field is produced by the tool, not a parameter you supply. anchor and pad_color are not used in this mode. The [track] extra (numpy) must be installed for tracking to take effect; if it is missing, the tool falls back to a static centre crop (see Fallback behaviour). The keyframe track is capped at 80 keyframes (an FFmpeg filter-expression length limit); the detector decimates the track to fit, and clipwright-render materialises the track it receives as-is.

Return value

{
  "ok": true,
  "summary": "Reframe directive written for video.mp4. target=1080x1920 mode=blur_pad anchor=center.",
  "data": {
    "target_w": 1080,
    "target_h": 1920,
    "mode": "blur_pad",
    "anchor": "center",
    "pad_color": "black"
  },
  "artifacts": [{"role": "timeline", "path": "out.otio", "format": "otio"}],
  "warnings": []
}

Error codes

Fallback behaviour

mode="track" is designed to never hard-fail (AI-first robustness). When the [track] extra (numpy) is not installed, or when motion-centroid detection fails for any reason, the tool does not return an error: it writes a static centre crop track instead, returns ok: true, and adds a warning explaining that tracking was disabled and how to enable it (install the [track] extra). A vertical video is therefore always produced. A multi-source timeline combined with track is also handled gracefully: the track is ignored and rendering falls back to the existing per-clip cover crop, with a warning.

Two-Phase Workflow

clipwright_reframe(media, output, options)   # Phase 1 — annotate
        │
        ▼  OTIO timeline with metadata["clipwright"]["reframe"]
clipwright_render(timeline, output_media)    # Phase 2 — realise
        │
        ▼  output video in target resolution/aspect ratio

clipwright-reframe can be combined with other directive tools in any order before the final render:

clipwright_detect_color  →  clipwright_reduce_noise  →  clipwright_reframe  →  clipwright_render

MCP Client Registration

Register clipwright-reframe as a standalone MCP server in your client configuration (.mcp.json / claude_desktop_config.json). No FFmpeg environment variables are required for the annotation step.

{
  "mcpServers": {
    "clipwright-reframe": {
      "command": "clipwright-reframe"
    }
  }
}

clipwright-render (which materialises the directive) still requires CLIPWRIGHT_FFMPEG.

Usage Examples

16:9 landscape → 9:16 vertical (blur-pad background)

# Via MCP call_tool
result = await session.call_tool("clipwright_reframe", {
    "media": "source.mp4",
    "output": "reframed.otio",
    "options": {
        "target_w": 1080,
        "target_h": 1920,
        "mode": "blur_pad",
        "anchor": "center"
    }
})
# Then render
render_result = await session.call_tool("clipwright_render", {
    "timeline": "reframed.otio",
    "output": "vertical.mp4"
})

16:9 → 9:16 vertical with subject tracking (mode="track")

Keeps a moving subject in the frame as the crop window follows the motion centroid. Requires the [track] extra (numpy); without it the same call still produces a vertical video via a static centre crop (with a warning).

# Phase 1 — annotate: motion-centroid detection runs automatically
result = await session.call_tool("clipwright_reframe", {
    "media": "source.mp4",
    "output": "tracked.otio",
    "options": {
        "target_w": 1080,
        "target_h": 1920,
        "mode": "track"
        # anchor / pad_color are not used in track mode
    }
})
# Phase 2 — realise: render applies the time-varying (subject-following) crop, then scale
render_result = await session.call_tool("clipwright_render", {
    "timeline": "tracked.otio",
    "output": "vertical_tracked.mp4"
})

Crop to 1:1 square (top-aligned)

result = await session.call_tool("clipwright_reframe", {
    "media": "source.mp4",
    "output": "square.otio",
    "options": {
        "target_w": 1080,
        "target_h": 1080,
        "mode": "crop",
        "anchor": "top"
    }
})

Pad to 4:3 with white bars (accumulate on existing timeline)

result = await session.call_tool("clipwright_reframe", {
    "media": "source.mp4",
    "timeline": "edited.otio",   # existing timeline from other tools
    "output": "edited_reframed.otio",
    "options": {
        "target_w": 1440,
        "target_h": 1080,
        "mode": "pad",
        "anchor": "center",
        "pad_color": "white"
    }
})

Installation

Within a uv workspace:

uv run --package clipwright-reframe clipwright-reframe

Or install from PyPI:

pip install clipwright-reframe
clipwright-reframe

To enable mode="track" (motion-centroid subject tracking), install the optional [track] extra (pulls in numpy):

pip install clipwright-reframe[track]

If the [track] extra is not installed, mode="track" still works but degrades to a static centre crop with a warning (see Fallback behaviour).

License

MIT — See LICENSE for details.