clipwright-text

MCP tool for annotating an OTIO timeline with text overlay markers. Text is not rendered here — clipwright-render reads the markers and applies drawtext filters when producing the output video.

Overview

clipwright-text is part of the clipwright suite. It is designed for AI agents, not humans — there is no GUI or interactive CLI. All interaction is via the MCP (Model Context Protocol) stdio transport.

Available Tools

Tool Description
clipwright_add_text Append a text_overlay marker to an OTIO timeline for later rendering.

How It Works

  1. AI calls clipwright_add_text(timeline, output, options) once per text overlay.
  2. The tool appends a text_overlay marker (name text_0, text_1, …) to the first video track of the timeline and writes a new .otio file to output.
  3. The input timeline is never modified (non-destructive).
  4. Repeated calls with identical options are idempotent — the second call returns applied=0 with a warning instead of duplicating the marker.
  5. After annotating, pass the output OTIO to clipwright-render which converts the markers into drawtext ffmpeg filters and bakes the text into the video.

MCP Client Registration

Claude Desktop (claude_desktop_config.json)

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

If clipwright-text is not on PATH, use the full path to the script or the Python interpreter:

{
  "mcpServers": {
    "clipwright-text": {
      "command": "/path/to/.venv/bin/clipwright-text",
      "args": []
    }
  }
}

clipwright_add_text Reference

Parameters

Parameter Type Required Description
timeline str Yes Path to the input .otio timeline file.
output str Yes Path for the new .otio output (must end in .otio, must differ from timeline).
options AddTextOptions Yes Text overlay options (see below).

AddTextOptions Fields

Field Type Default Description
text str — Text to display. Single-line; no newlines or control characters.
start_sec float — Start time in seconds (>= 0).
duration_sec float — Duration in seconds (> 0).
x str "(w-tw)/2" Horizontal position (ffmpeg drawtext expression).
y str "h-th-40" Vertical position (ffmpeg drawtext expression).
font_size int 48 Font size in points (> 0).
font_color str "white" Font color: named color, #RRGGBB, or name@alpha.
box bool False Draw a background box behind the text.
box_color str "black@0.5" Background box color.
fade_in_sec float 0.3 Fade-in duration (>= 0; fade_in + fade_out <= duration).
fade_out_sec float 0.3 Fade-out duration (>= 0).
font_path str | None None Absolute path to a .ttf/.otf font file. None lets clipwright-render resolve a platform default.

Return Value

{
  "ok": true,
  "summary": "Added text overlay \"Hello\" at 1.0s for 3.0s. Timeline now has 1 text overlay(s). Output: out.otio.",
  "data": {
    "applied": 1,
    "overlay_count": 1,
    "start_sec": 1.0,
    "duration_sec": 3.0
  },
  "artifacts": [
    { "role": "timeline", "path": "/abs/path/out.otio", "format": "otio" }
  ],
  "warnings": []
}

On error:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "...",
    "hint": "..."
  }
}

Requirements

License

MIT

Key dates

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

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

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_text-0.2.1.tar.gz (9.8 kB view details)

Uploaded Source

Built Distribution

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

clipwright_text-0.2.1-py3-none-any.whl (11.9 kB view details)

Uploaded Python 3

File details

Details for the file clipwright_text-0.2.1.tar.gz.

File metadata

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

File hashes

Hashes for clipwright_text-0.2.1.tar.gz
Algorithm Hash digest
SHA256 221d285f6f0f815d552b36b0e301562d8da38fce2d92c0311a666736420e4bae
MD5 2101b5abe2e917ca4c5860a54c6afba6
BLAKE2b-256 c34675091d82fd87de155bd9eb273b822a1e2d2b8f48ac30dda725854b658d4d

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_text-0.2.1.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_text-0.2.1-py3-none-any.whl.

File metadata

File hashes

Hashes for clipwright_text-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e72e577c86db851e7eeafeae390684f5e2db565a988594854824300a1944b4e0
MD5 d1b8f3c16cb8b07c12187c0818dae89d
BLAKE2b-256 037d3267b3769f368ecede1ad6bcef61dd04bf32fe54173f64ad40c25c1c07d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_text-0.2.1-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