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:
Latest release

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.2.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.2-py3-none-any.whl (11.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: clipwright_text-0.2.2.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.2.tar.gz
Algorithm Hash digest
SHA256 d32fa69da3ccd069660b1a380b271f4a2f132d52e383598a438cca77bbbff72c
MD5 f730c78de2ac78f93b86a8ef6a12cc8c
BLAKE2b-256 5733d8532a52d70cf2e96934743a2b27339798c9a06beb00f3a705613503099a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for clipwright_text-0.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 2223a7e9fc31859c264396ba5a109a6928ed79db1612ab130bbe0245e0f847da
MD5 820e9e94c96d3ab8bbc986aaffd41235
BLAKE2b-256 03bc08906c067920aed6bebfa5ae66e3661f789a7d9c844753303041c153b3fa

See more details on using hashes here.

Provenance

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