clipwright-text 0.1.0__tar.gz

clipwright_text-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.3
+Name: clipwright-text
+Version: 0.1.0
+Summary: MCP tool for adding text overlays to an OTIO timeline.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.3.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: opentimelineio>=0.18
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/satoh-y-0323/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`)
+
+```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:
+
+```json
+{
+  "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
+
+```json
+{
+  "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:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "INVALID_INPUT",
+    "message": "...",
+    "hint": "..."
+  }
+}
+```
+
+## Requirements
+
+- Python >= 3.11
+- [opentimelineio](https://github.com/AcademySoftwareFoundation/OpenTimelineIO) >= 0.18
+- [mcp](https://github.com/modelcontextprotocol/python-sdk) >= 1.27.2
+- [clipwright](https://pypi.org/project/clipwright/) >= 0.3.0 (core library)
+
+## License
+
+MIT

clipwright_text-0.1.0/README.md

@@ -0,0 +1,128 @@
+# 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](https://github.com/satoh-y-0323/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`)
+
+```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:
+
+```json
+{
+  "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
+
+```json
+{
+  "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:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "INVALID_INPUT",
+    "message": "...",
+    "hint": "..."
+  }
+}
+```
+
+## Requirements
+
+- Python >= 3.11
+- [opentimelineio](https://github.com/AcademySoftwareFoundation/OpenTimelineIO) >= 0.18
+- [mcp](https://github.com/modelcontextprotocol/python-sdk) >= 1.27.2
+- [clipwright](https://pypi.org/project/clipwright/) >= 0.3.0 (core library)
+
+## License
+
+MIT

clipwright_text-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "clipwright-text"
+version = "0.1.0"
+description = "MCP tool for adding text overlays to an OTIO timeline."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "satoh-y-0323", email = "shoma.papa.0323@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "clipwright>=0.3.0",
+    "mcp[cli]>=1.27.2",
+    "opentimelineio>=0.18",
+    "pydantic>=2",
+]
+
+[project.scripts]
+clipwright-text = "clipwright_text.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.16",
+]
+
+[tool.uv.sources]
+clipwright = { workspace = true }
+
+# --- Ruff ---
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+# Allow E501 for English docstrings/comments in test files.
+# Allow I001 for test files authored in Red phase (import order is not our change).
+"tests/*.py" = ["E501", "I001"]
+
+[tool.ruff.format]
+
+# --- mypy ---
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+
+[[tool.mypy.overrides]]
+module = "opentimelineio.*"
+ignore_missing_imports = true
+
+# --- pytest ---
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -q"
+asyncio_mode = "strict"
+markers = [
+    "integration: integration test requiring actual ffmpeg/ffprobe binaries",
+    "slow: test with long execution time",
+]
+
+# --- coverage ---
+[tool.coverage.run]
+source = ["clipwright_text"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_text-0.1.0/src/clipwright_text/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-text: MCP tool for adding text overlays to an OTIO timeline."""
+
+__version__ = "0.1.0"

clipwright_text-0.1.0/src/clipwright_text/schemas.py

@@ -0,0 +1,91 @@
+"""schemas.py — Pydantic schema for AddTextOptions.
+
+Defines the options model for text overlay annotation. Core shared types
+(MediaRef, Artifact, ToolResult) are imported from clipwright.schemas and must
+not be redefined here (§6 convention contract).
+
+Value-range validation (start_sec>=0, duration_sec>0, etc.) is intentionally
+NOT enforced here via Pydantic constraints. It is validated manually inside
+_add_text_inner so that the error envelope carries a precise hint (decision OQ-1).
+AddTextOptions uses extra="forbid" so unknown keys are rejected at the schema
+boundary before business logic runs.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AddTextOptions(BaseModel):
+    """Options for adding a text overlay marker to an OTIO timeline.
+
+    text, start_sec, and duration_sec are required. All other fields are
+    optional with sensible defaults for a lower-third subtitle-style overlay.
+
+    Value-range validation (start_sec>=0, duration_sec>0, font_size>0, etc.)
+    is performed manually in _add_text_inner to produce precise error hints —
+    not via Pydantic constraints (decision OQ-1).
+
+    Color fields (font_color, box_color) accept named colors, #RRGGBB, or
+    name@alpha format. Validation against the allowlist is done in
+    _add_text_inner.
+    """
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+
+    text: str
+    """Text to display. Must be non-empty single-line (no newlines or control chars)."""
+
+    start_sec: float
+    """Start time in seconds from the beginning of the timeline. Must be >= 0."""
+
+    duration_sec: float
+    """Duration of the text overlay in seconds. Must be > 0."""
+
+    x: str = "(w-tw)/2"
+    """Horizontal position as an ffmpeg drawtext expression.
+
+    Default: horizontally centered.
+    """
+
+    y: str = "h-th-40"
+    """Vertical position as an ffmpeg drawtext expression. Default: lower-third."""
+
+    font_size: int = 48
+    """Font size in points. Must be > 0."""
+
+    font_color: str = "white"
+    """Font color. Named color, #RRGGBB, or name@alpha (e.g. white, #FFCC00, black@0.5).
+
+    Validated against the allowlist ^[A-Za-z0-9#@._-]+$ in _add_text_inner.
+    """
+
+    box: bool = False
+    """Whether to draw a background box behind the text."""
+
+    box_color: str = "black@0.5"
+    """Background box color. Named color, #RRGGBB, or name@alpha."""
+
+    fade_in_sec: float = 0.3
+    """Fade-in duration in seconds. Must be >= 0.
+
+    Sum of fade_in_sec + fade_out_sec must not exceed duration_sec.
+    """
+
+    fade_out_sec: float = 0.3
+    """Fade-out duration in seconds. Must be >= 0.
+
+    Sum of fade_in_sec + fade_out_sec must not exceed duration_sec.
+    """
+
+    font_path: Annotated[str | None, Field(max_length=4096)] = None
+    """Absolute path to a .ttf/.otf font file.
+
+    When None, clipwright-render resolves a platform default font.
+    Max length 4096 characters (OS path limit upper bound). Character-level
+    validation (single-quotes, newlines, control chars) is performed in
+    _validate_text_overlay_fields — keep in sync with render-side
+    _marker_to_text_overlay font_path validator.
+    """

clipwright_text-0.1.0/src/clipwright_text/server.py

@@ -0,0 +1,79 @@
+"""server.py — MCP server for clipwright-text text overlay annotation.
+
+Exposes a single MCP tool: clipwright_add_text.
+Delegates all business logic to text.add_text; no logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from clipwright.envelope import error_result
+from clipwright.schemas import ToolResult
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_text.schemas import AddTextOptions
+from clipwright_text.text import add_text
+
+mcp = FastMCP("clipwright-text")
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_add_text(
+    timeline: Annotated[str, Field(description="Input OTIO timeline file path.")],
+    output: Annotated[
+        str,
+        Field(
+            description=(
+                "Output OTIO file path where the annotated timeline is written. "
+                "Must end in .otio and differ from the input timeline path."
+            )
+        ),
+    ],
+    options: Annotated[
+        AddTextOptions | None,
+        Field(
+            description=(
+                "Text overlay options. text, start_sec, and duration_sec are "
+                "required; all other fields have sensible defaults."
+            )
+        ),
+    ] = None,
+) -> ToolResult:
+    """Add a text_overlay marker to an OTIO timeline.
+
+    Later rendering by clipwright-render converts the marker to a drawtext filter.
+    Writes a new OTIO timeline to output; the input timeline is never modified.
+    Idempotent: calling with identical options on an already-annotated timeline
+    produces applied=0 with a warning rather than duplicating the marker.
+    Multiple distinct calls accumulate markers (text_0, text_1, ...) which
+    clipwright-render reads to apply drawtext filters.
+    """
+    if options is None:
+        return error_result(
+            "INVALID_INPUT",
+            "options is required but was not provided.",
+            (
+                "Pass options with at least text, start_sec, and duration_sec "
+                '(e.g., {"text": "Hello", "start_sec": 1.0, "duration_sec": 3.0}).'
+            ),
+        )
+    return add_text(timeline=timeline, output=output, options=options)
+
+
+def main() -> None:
+    """Entry point for the clipwright-text MCP server (stdio transport)."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

clipwright_text-0.1.0/src/clipwright_text/text.py

@@ -0,0 +1,614 @@
+"""text.py — clipwright-text orchestration layer.
+
+Handles the full flow: input validation -> load timeline -> validate options
+-> idempotency check -> add text_overlay marker -> save timeline -> return envelope.
+
+Design decisions:
+- _add_text_inner() is the raising implementation; add_text() is the public
+  boundary that catches ClipwrightError and converts to error_result.
+- Value-range validation is performed manually (OQ-1) for precise error hints.
+- Color allowlist ^[A-Za-z0-9#@._-]+$ prevents filtergraph injection (FR-5/ADR-T7).
+- Idempotency: exact duplicate (all metadata fields match) -> no-op with warning.
+- Non-destructive: input OTIO bytes are never modified; output is always new.
+- Rate determination (OQ-2): first clip source_range -> existing text_overlay
+  marker rate -> fallback 1000.0 with warning.
+- Boundary check _check_output_within_timeline_dir is a local copy of the
+  clipwright-speed implementation to avoid cross-package imports.
+  When changing the logic here, ensure behaviour remains in sync with
+  clipwright-speed's _check_output_within_timeline_dir; the two functions must
+  enforce the same boundary contract.
+"""
+
+from __future__ import annotations
+
+import collections.abc
+import re
+from pathlib import Path
+from typing import Any
+
+import opentimelineio as otio
+from clipwright.envelope import error_result, ok_result
+from clipwright.errors import ClipwrightError, ErrorCode
+from clipwright.otio_utils import add_marker, get_markers, load_timeline, save_timeline
+from clipwright.schemas import RationalTimeModel, TimeRangeModel, ToolResult
+
+from clipwright_text import __version__
+from clipwright_text.schemas import AddTextOptions
+
+# ---------------------------------------------------------------------------
+# Color allowlist (shared with clipwright-render; keep in sync — ADR-T4/ADR-T7)
+# Permits: named colors, #RRGGBB, #RRGGBBAA, name@alpha.
+# Excludes: spaces, single-quotes, colon, comma (filtergraph separators).
+# clipwright-render counterpart: _COLOR_ALLOWLIST_RE in plan.py
+# ---------------------------------------------------------------------------
+_COLOR_PATTERN = re.compile(r"^[A-Za-z0-9#@._-]+$")
+
+# Control-character pattern for text / position expressions / font_path.
+# Includes: NUL-US (\x00-\x1f), DEL (\x7f), and line terminators (\n, \r).
+_CONTROL_CHAR_PATTERN = re.compile(r"[\x00-\x1f\x7f]")
+
+# Tolerance for float comparison in idempotency checks (rate-invariant).
+# Keep in sync with _is_duplicate_overlay float comparison logic.
+_IDEMPOTENCY_EPS: float = 1e-6
+
+
+# ===========================================================================
+# Path boundary helper (local copy; keep in sync with clipwright-speed)
+# ===========================================================================
+
+
+def _check_output_within_timeline_dir(timeline: Path, output: Path) -> None:
+    """Verify that output is within the timeline's parent directory tree.
+
+    Mirrors clipwright-speed _check_output_within_timeline_dir boundary contract.
+    Allows recursive subdirectories; raises PATH_NOT_ALLOWED only when the
+    resolved output is outside the timeline directory tree.
+
+    Intentionally re-implemented locally to avoid cross-package import of
+    clipwright-speed (NR-L-4: cross-package imports between satellite tools
+    create tight coupling and break independent packaging/deployment).
+    When changing the logic here, ensure the behaviour remains in sync with
+    clipwright-speed's _check_output_within_timeline_dir; the two functions
+    must enforce the same boundary contract.
+
+    Args:
+        timeline: Path to the input OTIO timeline file.
+        output: Output path to validate against the boundary.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED when output is outside the
+            timeline's parent directory tree.
+    """
+    try:
+        allowed_base = timeline.parent.resolve()
+        target_resolved = output.resolve()
+        target_str = str(target_resolved)
+        base_str = str(allowed_base)
+        if not (
+            target_str == base_str
+            or target_str.startswith(base_str + "/")
+            or target_str.startswith(base_str + "\\")
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.PATH_NOT_ALLOWED,
+                message="Output path points outside the project boundary.",
+                hint=(
+                    "Place the output file within the same directory as the "
+                    "OTIO timeline, or in a subdirectory of it."
+                ),
+            )
+    except ClipwrightError:
+        raise
+    except OSError:
+        # resolve() failed (network path, symlink loop, etc.): fall back to
+        # absolute()-based best-effort comparison.
+        try:
+            allowed_base_abs = str(timeline.parent.absolute())
+            target_abs = str(output.absolute())
+            if not (
+                target_abs == allowed_base_abs
+                or target_abs.startswith(allowed_base_abs + "/")
+                or target_abs.startswith(allowed_base_abs + "\\")
+            ):
+                raise ClipwrightError(
+                    code=ErrorCode.PATH_NOT_ALLOWED,
+                    message="Output path points outside the project boundary.",
+                    hint=(
+                        "Place the output file within the same directory as the "
+                        "OTIO timeline, or in a subdirectory of it."
+                    ),
+                )
+        except ClipwrightError:
+            raise
+        except OSError:
+            # Skip only when absolute() also fails (truly unresolvable path).
+            pass
+
+
+# ===========================================================================
+# Validation helpers
+# ===========================================================================
+
+
+def _validate_text_overlay_fields(options: AddTextOptions) -> None:
+    """Validate value-range, text content, color, and position expression fields.
+
+    Validation order (fixed to keep error messages deterministic — ADR-T4):
+      1. Value ranges (start_sec, duration_sec, font_size, fade_in_sec, fade_out_sec,
+         fade sum)
+      2. text content (empty, control characters)
+      3. Color allowlist (font_color, box_color)
+      4. Position expression control characters (x, y)
+
+    All violations raise ClipwrightError(INVALID_INPUT).
+
+    Args:
+        options: AddTextOptions to validate.
+
+    Raises:
+        ClipwrightError: INVALID_INPUT on the first validation failure.
+    """
+    # --- 1. Value ranges ---
+    if options.start_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Text start time must be 0 or greater.",
+            hint="Set start_sec to a non-negative value.",
+        )
+    if options.duration_sec <= 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Text duration must be greater than 0.",
+            hint="Set duration_sec to a positive number of seconds.",
+        )
+    if options.font_size <= 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Font size must be a positive integer.",
+            hint="Set font_size to a value greater than 0 (e.g. 48).",
+        )
+    if options.fade_in_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-in duration must be 0 or greater.",
+            hint="Set fade_in_sec to a non-negative value.",
+        )
+    if options.fade_out_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-out duration must be 0 or greater.",
+            hint="Set fade_out_sec to a non-negative value.",
+        )
+    if options.fade_in_sec + options.fade_out_sec > options.duration_sec:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-in plus fade-out exceeds the text duration.",
+            hint=(
+                "Reduce fade durations or increase duration_sec so fades fit within it."
+            ),
+        )
+
+    # --- 2. text content ---
+    if not options.text.strip():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Text must not be empty or whitespace-only.",
+            hint="Provide a non-empty text string to display.",
+        )
+    if _CONTROL_CHAR_PATTERN.search(options.text):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Text must not contain newlines or control characters.",
+            hint=(
+                "Remove line breaks and control characters; this version "
+                "supports single-line overlays only."
+            ),
+        )
+
+    # --- 3. Color allowlist (font_color, box_color) ---
+    if not _COLOR_PATTERN.match(options.font_color):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Color value is not in the allowed format.",
+            hint=(
+                "Use a named color, #RRGGBB, or name@alpha "
+                "(e.g. white, #FFCC00, black@0.5)."
+            ),
+        )
+    if not _COLOR_PATTERN.match(options.box_color):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Color value is not in the allowed format.",
+            hint=(
+                "Use a named color, #RRGGBB, or name@alpha "
+                "(e.g. white, #FFCC00, black@0.5)."
+            ),
+        )
+
+    # --- 4. Position expression control characters (x, y) ---
+    _pos_msg = "Position expression must not contain newlines or control characters."
+    _pos_hint = "Provide a single-line ffmpeg drawtext expression for x/y."
+    if _CONTROL_CHAR_PATTERN.search(options.x):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=_pos_msg,
+            hint=_pos_hint,
+        )
+    if _CONTROL_CHAR_PATTERN.search(options.y):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=_pos_msg,
+            hint=_pos_hint,
+        )
+
+    # --- 5. font_path: single-quote, newline, control characters ---
+    # Keep in sync with render-side _marker_to_text_overlay font_path validator
+    # (same rules: _CONTROL_CHAR_PATTERN + explicit single-quote check).
+    if options.font_path is not None:
+        if "'" in options.font_path:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="Font path must not contain single-quote characters.",
+                hint=(
+                    "Remove single-quotes from the font file path "
+                    "(they would corrupt filtergraph fontfile='...' quoting)."
+                ),
+            )
+        if _CONTROL_CHAR_PATTERN.search(options.font_path):
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="Font path must not contain newlines or control characters.",
+                hint="Remove newlines and control characters from the font file path.",
+            )
+
+
+# ===========================================================================
+# Idempotency helpers
+# ===========================================================================
+
+
+def _overlay_metadata_dict(options: AddTextOptions) -> dict[str, Any]:
+    """Build the clipwright metadata dict for a text_overlay marker.
+
+    Stores tool/version/kind plus all AddTextOptions fields so that
+    clipwright-render can reconstruct the overlay from the marker alone.
+
+    Args:
+        options: Validated AddTextOptions.
+
+    Returns:
+        Dict to store under marker.metadata["clipwright"].
+    """
+    return {
+        "tool": "clipwright-text",
+        "version": __version__,
+        "kind": "text_overlay",
+        "text": options.text,
+        "start_sec": options.start_sec,
+        "duration_sec": options.duration_sec,
+        "x": options.x,
+        "y": options.y,
+        "font_size": options.font_size,
+        "font_color": options.font_color,
+        "box": options.box,
+        "box_color": options.box_color,
+        "fade_in_sec": options.fade_in_sec,
+        "fade_out_sec": options.fade_out_sec,
+        "font_path": options.font_path,
+    }
+
+
+def _is_duplicate_overlay(marker: otio.schema.Marker, options: AddTextOptions) -> bool:
+    """Return True if marker is an exact duplicate of the given options.
+
+    Compares all AddTextOptions fields stored in marker.metadata["clipwright"]
+    against the current options. Uses approximate float comparison for seconds
+    fields to be rate-invariant (ADR-T1).
+
+    Args:
+        marker: An existing text_overlay marker to compare.
+        options: Current AddTextOptions to check for duplication.
+
+    Returns:
+        True if all fields match (complete duplicate -> no-op).
+    """
+    cw = marker.metadata.get("clipwright", {})
+    if not isinstance(cw, collections.abc.Mapping):
+        return False
+    if cw.get("kind") != "text_overlay":
+        return False
+
+    # String / bool / int fields: exact match
+    if cw.get("text") != options.text:
+        return False
+    if cw.get("x") != options.x:
+        return False
+    if cw.get("y") != options.y:
+        return False
+    if cw.get("font_size") != options.font_size:
+        return False
+    if cw.get("font_color") != options.font_color:
+        return False
+    if cw.get("box") != options.box:
+        return False
+    if cw.get("box_color") != options.box_color:
+        return False
+    if cw.get("font_path") != options.font_path:
+        return False
+
+    # Float fields: approximate comparison (rate-invariant tolerance)
+    def _approx_eq(a: object, b: float) -> bool:
+        if not isinstance(a, (int, float)):
+            return False
+        return abs(float(a) - b) <= _IDEMPOTENCY_EPS
+
+    if not _approx_eq(cw.get("start_sec"), options.start_sec):
+        return False
+    if not _approx_eq(cw.get("duration_sec"), options.duration_sec):
+        return False
+    if not _approx_eq(cw.get("fade_in_sec"), options.fade_in_sec):
+        return False
+    return _approx_eq(cw.get("fade_out_sec"), options.fade_out_sec)
+
+
+# ===========================================================================
+# Rate resolution (OQ-2)
+# ===========================================================================
+
+
+def _resolve_rate(
+    video_track: otio.schema.Track,
+) -> tuple[float, list[str]]:
+    """Determine the rate for RationalTime construction (OQ-2 priority order).
+
+    Priority:
+      1. source_range.rate of the first Clip in the V1 track.
+      2. marked_range.start_time.rate of the first existing text_overlay marker.
+      3. Fallback: 1000.0 with a warning.
+
+    Args:
+        video_track: The first Video track from the loaded timeline.
+
+    Returns:
+        Tuple of (rate: float, warnings: list[str]). warnings is non-empty only
+        when the fallback rate is used.
+    """
+    # Priority 1: first clip's source_range rate
+    for item in video_track:
+        if isinstance(item, otio.schema.Clip) and item.source_range is not None:
+            return float(item.source_range.start_time.rate), []
+
+    # Priority 2: existing text_overlay marker rate
+    for marker in video_track.markers:
+        cw = marker.metadata.get("clipwright", {})
+        if isinstance(cw, collections.abc.Mapping) and cw.get("kind") == "text_overlay":
+            return float(marker.marked_range.start_time.rate), []
+
+    # Priority 3: fallback
+    return 1000.0, [
+        "Could not determine timeline rate from clips or existing markers; "
+        "using fallback rate 1000.0. Consider providing a timeline with clips."
+    ]
+
+
+# ===========================================================================
+# Core implementation
+# ===========================================================================
+
+
+def _add_text_inner(
+    timeline: str,
+    output: str,
+    options: AddTextOptions,
+) -> ToolResult:
+    """Internal implementation of add_text. Raises ClipwrightError on failure.
+
+    Validation order:
+      1. output suffix == .otio
+      2. output parent directory exists
+      3. output boundary check (PATH_NOT_ALLOWED when outside timeline dir)
+      4. output != timeline
+      5. field validation (_validate_text_overlay_fields)
+      6. load timeline (FILE_NOT_FOUND / OTIO_ERROR propagate)
+      7. first TrackKind.Video track exists
+      8. rate determination (OQ-2)
+      9. idempotency check (exact duplicate -> no-op)
+     10. add marker (text_{n}, all metadata fields)
+     11. save timeline atomically
+     12. return ok_result
+
+    Args:
+        timeline: Input OTIO timeline file path.
+        output: Output OTIO file path.
+        options: Validated AddTextOptions.
+
+    Returns:
+        ToolResult from ok_result.
+
+    Raises:
+        ClipwrightError: On any validation or I/O failure.
+    """
+    out = Path(output)
+    inp = Path(timeline)
+
+    # --- Step 1: output suffix validation ---
+    if out.suffix.lower() != ".otio":
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path must have a .otio extension.",
+            hint="Change the output file extension to .otio (e.g., 'result.otio').",
+        )
+
+    # --- Step 2: output parent directory exists ---
+    if not out.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message="Output directory does not exist.",
+            hint="Create the output directory before calling clipwright_add_text.",
+        )
+
+    # --- Step 3: output boundary check ---
+    _check_output_within_timeline_dir(inp, out)
+
+    # --- Step 4: output != timeline ---
+    if out.resolve() == inp.resolve():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path must differ from the input timeline path.",
+            hint=(
+                "Provide a distinct output path (e.g., append '_text' before .otio)."
+            ),
+        )
+
+    # --- Step 5: field validation ---
+    _validate_text_overlay_fields(options)
+
+    # --- Step 6: load timeline ---
+    if not inp.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"Timeline file not found: {inp.name}",
+            hint="Verify the timeline path and ensure the file exists.",
+        )
+    timeline_obj = load_timeline(timeline)
+
+    # --- Step 7: find first Video track ---
+    video_track: otio.schema.Track | None = None
+    for track in timeline_obj.tracks:
+        if track.kind == otio.schema.TrackKind.Video:
+            video_track = track
+            break
+
+    if video_track is None:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message="No video track found in the timeline.",
+            hint=(
+                "clipwright_add_text requires a timeline with at least one "
+                "video track to attach text overlay markers."
+            ),
+        )
+
+    # --- Step 8: rate determination (OQ-2) ---
+    rate, rate_warnings = _resolve_rate(video_track)
+
+    # --- Step 9: idempotency check ---
+    existing_markers = get_markers(timeline_obj, kind="text_overlay")
+    for existing in existing_markers:
+        if _is_duplicate_overlay(existing, options):
+            # Exact duplicate: save a copy of the timeline and return no-op result
+            save_timeline(timeline_obj, output)
+            overlay_count = len(existing_markers)
+            return ok_result(
+                summary=(
+                    f'Text overlay "{options.text}" at {options.start_sec}s for '
+                    f"{options.duration_sec}s already exists; no marker added. "
+                    f"Timeline has {overlay_count} text overlay(s). "
+                    f"Output: {out.name}."
+                ),
+                data={
+                    "applied": 0,
+                    "overlay_count": overlay_count,
+                    "start_sec": options.start_sec,
+                    "duration_sec": options.duration_sec,
+                },
+                artifacts=[
+                    {
+                        "role": "timeline",
+                        "path": str(out.resolve()),
+                        "format": "otio",
+                    }
+                ],
+                warnings=["Identical text overlay already exists; no marker added."],
+            )
+
+    # --- Step 10: add marker ---
+    # Count existing text_overlay markers to determine name index
+    n = len(existing_markers)
+    marker_name = f"text_{n}"
+
+    # Build marked_range using the resolved rate
+    marked_range = TimeRangeModel(
+        start_time=RationalTimeModel(
+            value=options.start_sec * rate,
+            rate=rate,
+        ),
+        duration=RationalTimeModel(
+            value=options.duration_sec * rate,
+            rate=rate,
+        ),
+    )
+
+    add_marker(
+        video_track,
+        marked_range=marked_range,
+        name=marker_name,
+        color=None,
+        metadata=_overlay_metadata_dict(options),
+    )
+
+    # --- Step 11: save timeline ---
+    save_timeline(timeline_obj, output)
+
+    # --- Step 12: build result ---
+    overlay_count = n + 1
+    out_resolved = out.resolve()
+    text_preview = options.text[:40] + "..." if len(options.text) > 40 else options.text
+    summary = (
+        f'Added text overlay "{text_preview}" at {options.start_sec}s for '
+        f"{options.duration_sec}s. "
+        f"Timeline now has {overlay_count} text overlay(s). "
+        f"Output: {out.name}."
+    )
+
+    all_warnings = list(rate_warnings)
+
+    return ok_result(
+        summary=summary,
+        data={
+            "applied": 1,
+            "overlay_count": overlay_count,
+            "start_sec": options.start_sec,
+            "duration_sec": options.duration_sec,
+        },
+        artifacts=[
+            {
+                "role": "timeline",
+                "path": str(out_resolved),
+                "format": "otio",
+            }
+        ],
+        warnings=all_warnings if all_warnings else None,
+    )
+
+
+def add_text(
+    timeline: str,
+    output: str,
+    options: AddTextOptions | None,
+) -> ToolResult:
+    """Add a text_overlay marker to an OTIO timeline.
+
+    Non-destructive: does not modify the input timeline file.
+    Idempotent: calling with the same options on an already-annotated timeline
+    produces applied=0 and a warning rather than duplicating the marker.
+
+    Args:
+        timeline: Input OTIO timeline file path.
+        output: Output OTIO file path (must end in .otio, must differ from timeline).
+        options: AddTextOptions with required text/start_sec/duration_sec and
+            optional style fields. None returns INVALID_INPUT.
+
+    Returns:
+        ToolResult from ok_result or error_result.
+    """
+    if options is None:
+        return error_result(
+            "INVALID_INPUT",
+            "options is required but was not provided.",
+            "Pass an AddTextOptions with at least text, start_sec, and duration_sec.",
+        )
+    try:
+        return _add_text_inner(timeline, output, options)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)