clipwright-render

MCP tool to realize OTIO timelines with FFmpeg.

Clipwright is a toolkit centered on "separation of detection (detect) and application (render)". detect-type tools only return annotations to OTIO without modifying media, and this single clipwright-render tool performs all realization in one pass (completes segment extraction, concatenation, and trimming in a single transcode pass).

Prerequisites

This tool targets materials and timelines that meet the following conditions. Inputs outside these conditions return errors.

Out of Scope (Planned for Future)

• VFR / resolution-changing materials
• Multiple source file concatenation
• Subtitle burn-in
• Transitions
• 2+ video tracks in timeline

FFmpeg Setup

FFmpeg / FFprobe are not bundled with this package. Install in your environment.

# macOS (Homebrew)
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

If ffmpeg / ffprobe are on PATH, it works as-is. In environments where PATH cannot be modified, explicitly specify paths with environment variables.

export CLIPWRIGHT_FFMPEG=/usr/local/bin/ffmpeg
export CLIPWRIGHT_FFPROBE=/usr/local/bin/ffprobe

About license: This wrapper package itself is MIT licensed. Since FFmpeg binaries are not bundled, FFmpeg's LGPL / GPL redistribution obligations do not apply to this wrapper. Verify FFmpeg's own license (LGPL v2.1 / GPL v2) in your environment.

Installation

uv sync

MCP Client Registration

Add the following to your MCP client configuration (e.g. .mcp.json):

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

If ffmpeg / ffprobe are not on PATH, pass them as environment variables:

{
  "mcpServers": {
    "clipwright-render": {
      "command": "clipwright-render",
      "args": [],
      "env": {
        "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg",
        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
      }
    }
  }
}

Usage

MCP Tool (clipwright_render)

Invoked from Claude / agents via MCP.

{
  "tool": "clipwright_render",
  "arguments": {
    "timeline": "/path/to/timeline.otio",
    "output": "/path/to/output.mp4",
    "dry_run": false,
    "options": {
      "video_codec": "libx264",
      "audio_codec": "aac",
      "width": 1920,
      "height": 1080,
      "fps": 29.97,
      "crf": 23,
      "overwrite": false
    }
  }
}

Arguments

RenderOptions

width / height must both be specified or both null. Specifying only one is an error.

Hardware Encoder Behaviour

• hw_encoder="auto": probe-then-test detection — checks ffmpeg -encoders, runs a 1-frame throwaway encode to -f null -, picks the first vendor that succeeds. Falls back to libx264 with a warnings[] entry if no hardware encoder is usable. Render always completes.
• hw_encoder="nvenc" (or any explicit vendor): if the encoder fails to initialise, returns UNSUPPORTED_OPERATION with an actionable hint.
• hw_encoder="none" (default): uses the software encoder path unchanged (backward compatible).

Hardware Encoder Verification Status

Note: hardware encoders trade some size/quality fidelity for speed. NVENC default rate control produced a notably smaller file than libx264 -crf 21 at comparable subjective quality during verification (not a rigorous quality-matched comparison).

Return Value (Success)

{
  "ok": true,
  "summary": "2 clips → 45.2 sec / 42.1 MB / outputs/out.mp4",
  "data": {
    "output_path": "/path/to/output.mp4",
    "duration_sec": 45.2,
    "size_bytes": 44150784,
    "clip_count": 2
  },
  "artifacts": ["/path/to/output.mp4"],
  "warnings": []
}

Return Value (dry_run)

{
  "ok": true,
  "summary": "dry_run: 2 segments / estimated 45.2 sec / approx 42.1 MB",
  "data": {
    "dry_run": true,
    "clip_count": 2,
    "estimated_duration_sec": 45.2,
    "estimated_size_bytes": 44150784,
    "ffmpeg_args": ["ffmpeg", "-i", "source.mp4", "-filter_complex", "..."]
  },
  "artifacts": [],
  "warnings": []
}

estimated_size_bytes is calculated from source bitrate obtained by FFprobe and output duration. If bitrate cannot be obtained, it is null with reason in warnings. If any of video_codec / width / height / fps / crf are specified, estimation based on source bitrate may differ significantly from actual, so warnings includes a note.

Return Value (Error)

{
  "ok": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "Timeline file not found: /path/to/timeline.otio",
    "hint": "Verify the file path"
  }
}

Main error codes:

Testing

Unit Tests (FFmpeg Not Required)

uv run --package clipwright-render pytest clipwright-render/tests/ -m "not integration"

Integration Tests (FFmpeg Required)

Tests that verify single-source concatenation and output using actual FFmpeg. Automatically skipped in environments without FFmpeg.

Set environment variables before running:

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

uv run --package clipwright-render pytest clipwright-render/tests/ -m integration

Integration tests skip if CLIPWRIGHT_FFMPEG / CLIPWRIGHT_FFPROBE are not set. Set these variables when running in CI.

License

This wrapper package itself is MIT licensed.

Since FFmpeg binaries are not bundled, FFmpeg's LGPL v2.1 / GPL v2 redistribution obligations do not apply to this package.