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.0.tar.gz (9.6 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.0-py3-none-any.whl (11.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: clipwright_text-0.2.0.tar.gz
  • Upload date:
  • Size: 9.6 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.0.tar.gz
Algorithm Hash digest
SHA256 fe12d1afa4f5fd2d0efb6c0d0dd0858e85891f296c62a4ab4193d0d8d5750731
MD5 eb9ca5730dd53aeff9d78c77b89cb4e7
BLAKE2b-256 ee59bd0c1eb937252e7bc44e9f784362e5a1ff887023d1b9a73a24a8311c4b42

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: clipwright_text-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 11.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for clipwright_text-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 be155a745a3b019712221cc6c19c48f3f025f2d1d6aa6e6169f9214ae88abad7
MD5 6f98330cadec0dbedd761d8ebcf0487e
BLAKE2b-256 c3a8c2b6422f1846d4b76e64168523f8d31fc4065e863826d27691c339762a7c

See more details on using hashes here.

Provenance

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