clipwright-color 0.1.0__tar.gz

clipwright_color-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.3
+Name: clipwright-color
+Version: 0.1.0
+Summary: MCP tool for video brightness detection and OTIO timeline color annotation generation. Measures average luma with ffmpeg signalstats and writes an eq color-correction directive to timeline-level metadata.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.2.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# clipwright-color
+
+MCP tool for video brightness detection and OTIO timeline color annotation generation.
+
+## Overview
+
+Measures average luma using the ffmpeg `signalstats` filter,
+writes a color correction directive (brightness offset, eq parameters) to timeline-level
+`metadata["clipwright"]["color"]`.
+
+Performs detection only (OTIO annotation); realization (eq filter application) is done once
+by `clipwright-render` (design M3: separation of detection and application).
+
+**Brightness derivation**:
+
+- Samples frames at a configurable interval using `fps=1/<interval>` and `signalstats=stat=brng`.
+- Computes mean luma (YAVG) across sampled frames.
+- Derives brightness offset as `clamp((target_luma - YAVG) / 255.0, -1.0, 1.0)`.
+- Contrast, saturation, and gamma are left at neutral defaults (1.0 / 1.0 / 1.0);
+  only brightness is auto-derived from the measured luma.
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg must exist on PATH or full path set in environment variable `CLIPWRIGHT_FFMPEG`.**
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_color`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input video file path (video stream required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.target_luma` | `float` | `128.0` | Target average luma on the 0-255 scale (default: mid-grey) |
+| `options.sample_interval_sec` | `float` | `1.0` | Frame sampling interval in seconds (ffmpeg fps=1/interval, must be > 0) |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append color directive to it) |
+
+### Return value
+
+The tool returns a ToolResult envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Color analysis complete. measured_luma=96.4 ...",
+  "data": {
+    "measured_luma": 96.4,
+    "brightness": 0.123,
+    "contrast": 1.0,
+    "saturation": 1.0,
+    "gamma": 1.0,
+    "target_luma": 128.0,
+    "sampled_frames": 12
+  },
+  "artifacts": [{"role": "timeline", "path": "out.otio", "format": "otio"}],
+  "warnings": []
+}
+```
+
+When measurement is not possible (`measured=None`, U-1), the color directive is not written
+but the timeline is still saved and a warning is returned.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `clipwright` | Shared types, envelope, errors, process.run |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+ffmpeg is invoked as a separate process (via PATH or environment variable) for license independence.
+
+## Detection and Render Two-Phase Flow
+
+1. **detect (this tool)**: `ffmpeg -i <media> -vf "fps=1/1,signalstats=stat=brng,metadata=print" -f null -`
+   extracts per-frame YAVG and saves the derived eq directive to OTIO annotation.
+2. **render (clipwright-render)**: reads `metadata["clipwright"]["color"]["eq"]` and applies
+   `eq=brightness=...:contrast=...:saturation=...:gamma=...` in the ffmpeg filter graph.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-color clipwright-color
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-color
+clipwright-color
+```

clipwright_color-0.1.0/README.md

@@ -0,0 +1,101 @@
+# clipwright-color
+
+MCP tool for video brightness detection and OTIO timeline color annotation generation.
+
+## Overview
+
+Measures average luma using the ffmpeg `signalstats` filter,
+writes a color correction directive (brightness offset, eq parameters) to timeline-level
+`metadata["clipwright"]["color"]`.
+
+Performs detection only (OTIO annotation); realization (eq filter application) is done once
+by `clipwright-render` (design M3: separation of detection and application).
+
+**Brightness derivation**:
+
+- Samples frames at a configurable interval using `fps=1/<interval>` and `signalstats=stat=brng`.
+- Computes mean luma (YAVG) across sampled frames.
+- Derives brightness offset as `clamp((target_luma - YAVG) / 255.0, -1.0, 1.0)`.
+- Contrast, saturation, and gamma are left at neutral defaults (1.0 / 1.0 / 1.0);
+  only brightness is auto-derived from the measured luma.
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg must exist on PATH or full path set in environment variable `CLIPWRIGHT_FFMPEG`.**
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_color`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input video file path (video stream required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.target_luma` | `float` | `128.0` | Target average luma on the 0-255 scale (default: mid-grey) |
+| `options.sample_interval_sec` | `float` | `1.0` | Frame sampling interval in seconds (ffmpeg fps=1/interval, must be > 0) |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append color directive to it) |
+
+### Return value
+
+The tool returns a ToolResult envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Color analysis complete. measured_luma=96.4 ...",
+  "data": {
+    "measured_luma": 96.4,
+    "brightness": 0.123,
+    "contrast": 1.0,
+    "saturation": 1.0,
+    "gamma": 1.0,
+    "target_luma": 128.0,
+    "sampled_frames": 12
+  },
+  "artifacts": [{"role": "timeline", "path": "out.otio", "format": "otio"}],
+  "warnings": []
+}
+```
+
+When measurement is not possible (`measured=None`, U-1), the color directive is not written
+but the timeline is still saved and a warning is returned.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `clipwright` | Shared types, envelope, errors, process.run |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+ffmpeg is invoked as a separate process (via PATH or environment variable) for license independence.
+
+## Detection and Render Two-Phase Flow
+
+1. **detect (this tool)**: `ffmpeg -i <media> -vf "fps=1/1,signalstats=stat=brng,metadata=print" -f null -`
+   extracts per-frame YAVG and saves the derived eq directive to OTIO annotation.
+2. **render (clipwright-render)**: reads `metadata["clipwright"]["color"]["eq"]` and applies
+   `eq=brightness=...:contrast=...:saturation=...:gamma=...` in the ffmpeg filter graph.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-color clipwright-color
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-color
+clipwright-color
+```

clipwright_color-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "clipwright-color"
+version = "0.1.0"
+description = "MCP tool for video brightness detection and OTIO timeline color annotation generation. Measures average luma with ffmpeg signalstats and writes an eq color-correction directive to timeline-level metadata."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "satoh-y-0323", email = "shoma.papa.0323@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "clipwright>=0.2.0",
+    "mcp[cli]>=1.27.2",
+    "pydantic>=2",
+]
+
+[project.scripts]
+clipwright-color = "clipwright_color.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 }
+
+[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]
+"tests/*.py" = ["E501"]
+
+[tool.ruff.format]
+
+[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
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -q"
+markers = [
+    "integration: integration test requiring actual ffmpeg/ffprobe binaries",
+    "slow: test with long execution time",
+    "e2e: e2e test using actual ffmpeg binary",
+]
+
+[tool.coverage.run]
+source = ["clipwright_color"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_color-0.1.0/src/clipwright_color/__init__.py

@@ -0,0 +1,5 @@
+"""clipwright-color — Video brightness detection and OTIO color annotation."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

clipwright_color-0.1.0/src/clipwright_color/analyze.py

@@ -0,0 +1,140 @@
+"""analyze.py — ffmpeg signalstats measurement for clipwright-color.
+
+Actual ffmpeg 8.1.1 Windows output format (verified in e2e env):
+  metadata=print emits per sampled frame on stderr with
+  [Parsed_metadata_N @ addr] prefix:
+    [Parsed_metadata_2 @ 000002139b615380] lavfi.signalstats.YMIN=9
+    [Parsed_metadata_2 @ 000002139b615380] lavfi.signalstats.YAVG=125.951
+    [Parsed_metadata_2 @ 000002139b615380] lavfi.signalstats.YMAX=242
+
+The parser (_parse_signalstats) accepts a single text blob so the source stream
+(stderr vs stdout) is a one-line switch (ADR-CO-6). Default: result.stderr.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from clipwright.errors import ClipwrightError
+from clipwright.process import resolve_tool, run
+from pydantic import ValidationError
+
+from clipwright_color.schemas import BrightnessMeasured, DetectColorOptions
+
+# ffmpeg execution timeout (seconds).
+# Measurement-only pass; same budget as loudness.
+_TIMEOUT_SECONDS: float = 300.0
+
+# Regex patterns for signalstats per-frame output lines (ADR-CO-6 / §4.2).
+# The [Parsed_metadata_N @ addr] prefix is ignored; we match the key=value portion.
+_YAVG_RE = re.compile(r"lavfi\.signalstats\.YAVG=(-?\d+\.?\d*)")
+_YMIN_RE = re.compile(r"lavfi\.signalstats\.YMIN=(-?\d+\.?\d*)")
+_YMAX_RE = re.compile(r"lavfi\.signalstats\.YMAX=(-?\d+\.?\d*)")
+
+
+def _parse_signalstats(text: str) -> dict[str, Any] | None:
+    """Parse signalstats metadata output and return aggregated measurements.
+
+    Extracts YAVG (mean across frames), YMIN (min across frames), YMAX (max across
+    frames), and sampled_frames count. Returns None when no YAVG lines are found
+    or when BrightnessMeasured validation fails (inf/nan/out-of-range -> None, U-1).
+
+    Args:
+        text: Single text blob from ffmpeg signalstats output (stderr or stdout).
+
+    Returns:
+        Dict with yavg/ymin/ymax/sampled_frames, or None on failure.
+    """
+    yavg_vals = [float(m) for m in _YAVG_RE.findall(text)]
+    if not yavg_vals:
+        return None
+
+    yavg = sum(yavg_vals) / len(yavg_vals)
+    ymin_vals = [float(m) for m in _YMIN_RE.findall(text)]
+    ymax_vals = [float(m) for m in _YMAX_RE.findall(text)]
+
+    raw: dict[str, Any] = {
+        "yavg": yavg,
+        "ymin": min(ymin_vals) if ymin_vals else None,
+        "ymax": max(ymax_vals) if ymax_vals else None,
+        "sampled_frames": len(yavg_vals),
+    }
+
+    try:
+        validated = BrightnessMeasured(**raw)
+    except ValidationError:
+        # inf/nan or out-of-range -> degrade to None (parity with U-1)
+        return None
+
+    return validated.model_dump()
+
+
+def measure_brightness(
+    media: Path,
+    options: DetectColorOptions,
+) -> dict[str, Any]:
+    """Measure video brightness using ffmpeg signalstats (architecture-report §4).
+
+    Runs ffmpeg with signalstats=stat=brng,metadata=print to extract per-frame
+    luma statistics. Parses YAVG (mean), YMIN (min), YMAX (max) from stderr.
+
+    Args:
+        media: Path to the input media file (video stream required).
+        options: DetectColorOptions with sample_interval_sec and target_luma.
+
+    Returns:
+        {
+            "measured": dict | None,  # BrightnessMeasured fields, or None (U-1).
+            "warnings": list[str],
+        }
+
+    Raises:
+        clipwright.errors.ClipwrightError:
+            DEPENDENCY_MISSING / SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT.
+    """
+    ffmpeg_bin = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+
+    interval = options.sample_interval_sec
+    # -vf is a single argv element (CWE-78 / NFR-2 / ADR-CO-6).
+    # interval is a validated Pydantic float (gt=0) so {interval:g} cannot inject
+    # filtergraph syntax.
+    vf = f"fps=1/{interval:g},signalstats=stat=brng,metadata=print"
+
+    cmd: list[str] = [
+        ffmpeg_bin,
+        "-hide_banner",
+        "-i",
+        str(media),
+        "-vf",
+        vf,
+        "-f",
+        "null",
+        "-",
+    ]
+
+    warnings: list[str] = []
+
+    try:
+        result = run(cmd, timeout=_TIMEOUT_SECONDS)
+    except ClipwrightError as exc:
+        # Prevent absolute paths / raw stderr from leaking into the error message.
+        # Re-raise with fixed wording + from None to avoid chaining __cause__ (CWE-209).
+        raise ClipwrightError(
+            code=exc.code,
+            message="ffmpeg signalstats command failed.",
+            hint="Check the ffmpeg version and arguments.",
+        ) from None
+
+    # Default: read from result.stderr (ADR-CO-6; parser accepts single text blob).
+    measured = _parse_signalstats(result.stderr)
+
+    if measured is None:
+        warnings.append(
+            "Could not retrieve signalstats YAVG values."
+            " color directive will not be written (U-1)."
+            " ffmpeg stderr did not contain lavfi.signalstats.YAVG fields."
+        )
+
+    return {"measured": measured, "warnings": warnings}

clipwright_color-0.1.0/src/clipwright_color/color.py

@@ -0,0 +1,447 @@
+"""color.py — clipwright-color orchestration layer (architecture-report §5).
+
+Flow (7 steps):
+  1. Output validation (extension, parent dir, output==media,
+     output==timeline, same directory as media)
+  2. inspect_media: require video stream (audio NOT required; FR-2 Constraint)
+  3. Timeline resolution (None -> create new / path -> load + validate)
+  4. measure_brightness
+  5. Derive brightness offset and annotate ColorDirective
+     (measured=None -> skip directive + warning, U-1)
+  6. save_timeline (atomic)
+  7. ok_result with summary / data / artifacts
+
+Design decisions:
+- Audio NOT required (Constraint, FR-2); color requires video stream only.
+- output must be in the same directory as media (DC-AS-002).
+- measured=None: skip directive, still save timeline + return warning (U-1 parity).
+- brightness = clamp((target_luma - yavg) / 255.0, -1.0, 1.0).
+- Mirrors loudness.py helper structure (_same_path / _add_full_clip /
+  _load_and_validate_timeline / _check_source_within_timeline_dir).
+"""
+
+from __future__ import annotations
+
+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.media import inspect_media
+from clipwright.otio_utils import (
+    get_clipwright_metadata,
+    load_timeline,
+    new_timeline,
+    save_timeline,
+    set_clipwright_metadata,
+)
+from clipwright.schemas import RationalTimeModel, ToolResult
+from pydantic import ValidationError
+
+import clipwright_color
+from clipwright_color.analyze import measure_brightness
+from clipwright_color.schemas import (
+    BrightnessMeasured,
+    ColorDirective,
+    DetectColorOptions,
+    EqParams,
+)
+
+
+def detect_color(
+    media: str,
+    output: str,
+    options: DetectColorOptions,
+    timeline: str | None,
+) -> ToolResult:
+    """Public API for color detection. Converts ClipwrightError to ok=False envelope.
+
+    Args:
+        media: Input video file path (video stream required).
+        output: Output OTIO timeline file path (.otio, same directory as media).
+        options: DetectColorOptions.
+        timeline: Existing timeline path (None = create new).
+
+    Returns:
+        ok_result or error_result ToolResult.
+    """
+    try:
+        return _detect_color_inner(media, output, options, timeline)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _detect_color_inner(
+    media: str,
+    output: str,
+    options: DetectColorOptions,
+    timeline: str | None,
+) -> ToolResult:
+    """Internal implementation of detect_color. Raises ClipwrightError directly."""
+    media_path = Path(media)
+    output_path = Path(output)
+
+    # --- 1. Output validation ---
+
+    if output_path.suffix.lower() != ".otio":
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output file must use the .otio extension.",
+            hint="Set the output file extension to .otio.",
+        )
+
+    if not output_path.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="output directory does not exist.",
+            hint="Create the output directory first, then re-run.",
+        )
+
+    # Prohibit output == media (non-destructive)
+    if _same_path(output_path, media_path):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path and input media path are the same.",
+            hint="Change the output file path to differ from the input media.",
+        )
+
+    # Prohibit output == timeline (non-destructive)
+    if timeline is not None and _same_path(output_path, Path(timeline)):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path and input timeline path are the same.",
+            hint="Change the output file path to differ from the input timeline.",
+        )
+
+    # output must be in the same directory as media (DC-AS-002)
+    try:
+        media_resolved_dir = media_path.resolve().parent
+        output_resolved_dir = output_path.resolve().parent
+    except OSError:
+        media_resolved_dir = media_path.absolute().parent
+        output_resolved_dir = output_path.absolute().parent
+
+    if media_resolved_dir != output_resolved_dir:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                "Output file must be placed in the same directory as the media file."
+            ),
+            hint="Change the output path to the same directory as the media file.",
+        )
+
+    # --- 2. inspect_media: video required, audio NOT required ---
+
+    if not media_path.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"File not found: {media_path.name}",
+            hint="Check that the input media file path is correct.",
+        )
+
+    media_info = inspect_media(media)
+
+    has_video = any(s.codec_type == "video" for s in media_info.streams)
+    # NOTE: no has_audio check — color does not require audio (Constraint, FR-2).
+
+    if not has_video:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message=f"No video stream found: {media_path.name}",
+            hint="Provide a media file that contains a video stream.",
+        )
+
+    # Retrieve duration (total seconds for the full-length clip in _add_full_clip)
+    duration_sec: float = 0.0
+    if media_info.duration is not None:
+        duration_sec = media_info.duration.value / media_info.duration.rate
+
+    # --- 3. Timeline resolution ---
+
+    if timeline is None:
+        tl = new_timeline(media_path.name)
+        _add_full_clip(tl, media_path, duration_sec, media_info.duration)
+    else:
+        tl = _load_and_validate_timeline(
+            timeline, media_path, duration_sec, media_info.duration
+        )
+
+    # --- 4. measure_brightness ---
+
+    analysis = measure_brightness(media_path, options)
+    measured_raw: dict[str, Any] | None = analysis["measured"]
+    warnings: list[str] = list(analysis["warnings"])
+
+    # --- 5. Derive brightness offset and annotate ColorDirective ---
+    # (U-1: skip when measured is None)
+
+    final_luma: float | None = None
+    final_brightness: float | None = None
+    final_frames: int = 0
+    summary: str
+
+    if measured_raw is None:
+        # U-1: measurement not possible — skip directive, still save timeline
+        warnings.append(
+            "Could not retrieve brightness measurement."
+            " color directive will not be written (U-1)."
+        )
+        summary = (
+            f"Color analysis of {media_path.name} attempted but no YAVG could be"
+            f" measured. color directive was not written (U-1)."
+        )
+    else:
+        try:
+            measured_obj = BrightnessMeasured(**measured_raw)
+        except ValidationError:
+            # CWE-209: do not expose ValidationError details externally
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="Validation of brightness measured values failed.",
+                hint="Check the return value of measure_brightness.",
+            ) from None
+
+        brightness: float = _clamp(
+            (options.target_luma - measured_obj.yavg) / 255.0, -1.0, 1.0
+        )
+
+        directive = ColorDirective(
+            tool="clipwright-color",
+            version=clipwright_color.__version__,
+            kind="color",
+            target_luma=options.target_luma,
+            measured=measured_obj,
+            eq=EqParams(brightness=brightness),  # contrast/saturation/gamma neutral
+        )
+
+        existing_meta = get_clipwright_metadata(tl)
+        existing_meta["color"] = directive.model_dump()
+        set_clipwright_metadata(tl, existing_meta)
+
+        final_luma = measured_obj.yavg
+        final_brightness = brightness
+        final_frames = measured_obj.sampled_frames
+        summary = (
+            f"Color analysis of {media_path.name} complete."
+            f" measured_luma={final_luma:.1f}"
+            f" (over {final_frames} frame(s)),"
+            f" target_luma={options.target_luma:.1f},"
+            f" computed brightness offset={brightness:+.3f}."
+            f" color directive written to {output_path.name}."
+        )
+
+    # --- 6. save_timeline (atomic) ---
+
+    save_timeline(tl, str(output_path))
+
+    return ok_result(
+        summary,
+        data={
+            "measured_luma": final_luma,
+            "brightness": final_brightness,
+            "contrast": 1.0,
+            "saturation": 1.0,
+            "gamma": 1.0,
+            "target_luma": options.target_luma,
+            "sampled_frames": final_frames,
+        },
+        artifacts=[{"role": "timeline", "path": str(output_path), "format": "otio"}],
+        warnings=warnings,
+    )
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    """Clamp value to [lo, hi] range."""
+    return max(lo, min(hi, value))
+
+
+def _same_path(a: Path, b: Path) -> bool:
+    """Return True if both paths refer to the same entity (DC-GP-005 / B-4).
+
+    Falls back to string comparison on OSError.
+    """
+    try:
+        return a.resolve() == b.resolve()
+    except OSError:
+        return str(a) == str(b)
+
+
+def _add_full_clip(
+    tl: otio.schema.Timeline,
+    media_path: Path,
+    duration_sec: float,
+    duration_rt: RationalTimeModel | None,
+) -> None:
+    """Add one full-length keep clip to V1/A1 tracks of the timeline (new creation).
+
+    target_url is set to the absolute path of media_path.resolve() (DC-AS-002).
+
+    Args:
+        duration_rt: Pydantic model RationalTimeModel (not OTIO RationalTime).
+            Used to obtain the rate. Falls back to rate=1000.0 when None.
+    """
+    try:
+        target_url = str(media_path.resolve())
+    except OSError:
+        target_url = str(media_path.absolute())
+
+    rate = duration_rt.rate if duration_rt is not None else 1000.0
+
+    source_range = otio.opentime.TimeRange(
+        start_time=otio.opentime.RationalTime(0.0, rate),
+        duration=otio.opentime.RationalTime(duration_sec * rate, rate),
+    )
+    ref = otio.schema.ExternalReference(target_url=target_url)
+
+    for track in tl.tracks:
+        clip = otio.schema.Clip(
+            name=media_path.name,
+            media_reference=ref,
+            source_range=source_range,
+        )
+        track.append(clip)
+
+
+def _load_and_validate_timeline(
+    timeline_path: str,
+    media_path: Path,
+    duration_sec: float,
+    duration_rt: RationalTimeModel | None,
+) -> otio.schema.Timeline:
+    """Load an existing timeline and validate its consistency (B-4 / B-5).
+
+    Validates:
+    - The target_url of V1 clips matches media_path
+    - Single source (all clips share the same target_url)
+    - Exactly one Video-kind track (B-5)
+
+    If V1 is empty, adds a full-length keep clip and continues.
+
+    Raises:
+        ClipwrightError: INVALID_INPUT / OTIO_ERROR.
+    """
+    tl = load_timeline(timeline_path)
+
+    # Exactly one Video-kind track (B-5)
+    video_tracks = [t for t in tl.tracks if t.kind == otio.schema.TrackKind.Video]
+    if len(video_tracks) != 1:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                f"Invalid number of Video tracks in timeline: {len(video_tracks)}"
+                " (only 1 is supported)"
+            ),
+            hint="Specify a timeline with exactly one Video track.",
+        )
+
+    v1 = video_tracks[0]
+
+    clips = [item for item in v1 if isinstance(item, otio.schema.Clip)]
+
+    if not clips:
+        _add_full_clip(tl, media_path, duration_sec, duration_rt)
+        return tl
+
+    urls: set[str] = set()
+    for clip in clips:
+        ref = clip.media_reference
+        if isinstance(ref, otio.schema.ExternalReference):
+            urls.add(ref.target_url)
+
+    # Boundary check: target_url must be within timeline parent dir (SR L-2)
+    tl_path = Path(timeline_path)
+    for url in urls:
+        _check_source_within_timeline_dir(tl_path, url)
+
+    if len(urls) > 1:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message="Timeline contains clips from multiple sources.",
+            hint="Specify a timeline with a single source (same media file).",
+        )
+
+    # Validate target_url == media_path (B-4: resolve() normalization)
+    if urls:
+        target_url = next(iter(urls))
+        try:
+            tl_source = Path(target_url).resolve()
+            media_resolved = media_path.resolve()
+        except OSError:
+            tl_source = Path(target_url).absolute()
+            media_resolved = media_path.absolute()
+
+        if tl_source != media_resolved:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message=(
+                    f"Timeline source file does not match input media."
+                    f" timeline source: {Path(target_url).name}"
+                    f" / media: {media_path.name}"
+                ),
+                hint=(
+                    "Specify the same media file used when the timeline was created."
+                ),
+            )
+
+    return tl
+
+
+def _check_source_within_timeline_dir(timeline_path: Path, source: str) -> None:
+    """Validate that the source path is within the timeline parent directory (SR L-2).
+
+    Guards against malicious OTIO embedding arbitrary paths in target_url.
+
+    Args:
+        timeline_path: Path to the OTIO timeline file.
+        source: Media source path obtained from OTIO target_url.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED (source outside timeline parent dir).
+    """
+    try:
+        allowed_base = timeline_path.parent.resolve()
+        source_resolved = Path(source).resolve()
+        source_str = str(source_resolved)
+        base_str = str(allowed_base)
+        if not (
+            source_str == base_str
+            or source_str.startswith(base_str + "/")
+            or source_str.startswith(base_str + "\\")
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.PATH_NOT_ALLOWED,
+                message="Source file points outside the timeline directory boundary.",
+                hint=(
+                    "Use a source file located within the same directory"
+                    " as the OTIO timeline."
+                ),
+            )
+    except ClipwrightError:
+        raise
+    except OSError:
+        # Fallback to absolute() comparison when resolve() fails (e.g. broken symlink).
+        # Prevents silently skipping boundary validation, reducing CWE-22 risk.
+        try:
+            allowed_base_abs = str(timeline_path.parent.absolute())
+            source_abs = str(Path(source).absolute())
+            if not (
+                source_abs == allowed_base_abs
+                or source_abs.startswith(allowed_base_abs + "/")
+                or source_abs.startswith(allowed_base_abs + "\\")
+            ):
+                raise ClipwrightError(
+                    code=ErrorCode.PATH_NOT_ALLOWED,
+                    message=(
+                        "Source file points outside the timeline directory boundary."
+                    ),
+                    hint=(
+                        "Use a source file located within the same directory"
+                        " as the OTIO timeline."
+                    ),
+                )
+        except ClipwrightError:
+            raise
+        except OSError:
+            # absolute() also failed (truly unresolvable path) — best-effort skip
+            pass

clipwright_color-0.1.0/src/clipwright_color/schemas.py

@@ -0,0 +1,97 @@
+"""schemas.py — Pydantic models for clipwright-color.
+
+Common types (MediaRef / Artifact / ToolResult) are imported from core (clipwright)
+and are never redefined here.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class DetectColorOptions(BaseModel):
+    """Options for clipwright_detect_color.
+
+    target_luma: target average luma (0-255 scale). Default 128 (mid-grey).
+    sample_interval_sec: ffmpeg fps=1/interval downsampling step (seconds, >0).
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    target_luma: Annotated[
+        float,
+        Field(
+            default=128.0,
+            ge=0.0,
+            le=255.0,
+            allow_inf_nan=False,
+            description="Target average luma on the 0-255 scale. Default 128.",
+        ),
+    ] = 128.0
+
+    sample_interval_sec: Annotated[
+        float,
+        Field(
+            default=1.0,
+            gt=0.0,
+            le=3600.0,
+            allow_inf_nan=False,
+            description=(
+                "Frame sampling interval in seconds (ffmpeg fps=1/interval)."
+                " Must be > 0. Default 1.0."
+            ),
+        ),
+    ] = 1.0
+
+
+class BrightnessMeasured(BaseModel):
+    """Raw signalstats measurement (writer side).
+
+    yavg is the mean of per-frame lavfi.signalstats.YAVG values.
+    ymin/ymax are optional aggregates (min of YMIN, max of YMAX) for diagnostics.
+    sampled_frames is the number of frames that produced a YAVG value.
+    inf/nan are rejected; the caller degrades to measured=None (parity with
+    loudness U-1).
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    yavg: Annotated[float, Field(ge=0.0, le=255.0)]
+    ymin: Annotated[float, Field(ge=0.0, le=255.0)] | None = None
+    ymax: Annotated[float, Field(ge=0.0, le=255.0)] | None = None
+    sampled_frames: Annotated[int, Field(ge=0)]
+
+
+class EqParams(BaseModel):
+    """eq filter parameters consumed by clipwright-render (writer side).
+
+    Defaults are neutral so the full eq string can always be applied
+    unconditionally on the render side. Ranges match ffmpeg eq filter limits.
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    brightness: Annotated[float, Field(ge=-1.0, le=1.0)] = 0.0
+    contrast: Annotated[float, Field(ge=0.0, le=2.0)] = 1.0
+    saturation: Annotated[float, Field(ge=0.0, le=2.0)] = 1.0
+    gamma: Annotated[float, Field(ge=0.1, le=10.0)] = 1.0
+
+
+class ColorDirective(BaseModel):
+    """Directive written to timeline metadata["clipwright"]["color"].
+
+    Generated by clipwright-color and read/validated by clipwright-render.
+    scope is timeline-level only (per_clip deferred). measured is optional
+    (None when measurement failed; parity with loudness U-1).
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    tool: Annotated[str, Field(max_length=64)] = "clipwright-color"
+    version: Annotated[str, Field(max_length=64)]
+    kind: Literal["color"]
+    target_luma: Annotated[float, Field(ge=0.0, le=255.0, allow_inf_nan=False)]
+    measured: BrightnessMeasured | None = None
+    eq: EqParams

clipwright_color-0.1.0/src/clipwright_color/server.py

@@ -0,0 +1,106 @@
+"""server.py — clipwright-color MCP server + CLI entry point.
+
+Thin wrapper that delegates business logic to color.py.
+ClipwrightError conversion is handled in color.py; no double conversion here.
+
+Transport defaults to stdio (mcp.run(transport="stdio")).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from clipwright.schemas import ToolResult
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_color.color import detect_color
+from clipwright_color.schemas import DetectColorOptions
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-color")
+
+
+# ===========================================================================
+# clipwright_detect_color MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_detect_color(
+    media: Annotated[
+        str,
+        Field(description="Input video file path (video stream required)."),
+    ],
+    output: Annotated[
+        str,
+        Field(
+            description=(
+                "Output OTIO timeline file path (.otio extension)."
+                " Must be placed in the same directory as the media file."
+            )
+        ),
+    ],
+    options: Annotated[
+        DetectColorOptions | None,
+        Field(
+            description=(
+                "Color detection options (target_luma / sample_interval_sec)."
+                " Defaults to target_luma=128 / sample_interval_sec=1.0 when omitted."
+            )
+        ),
+    ] = None,
+    timeline: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Existing OTIO timeline file path."
+                " When specified, the color directive is appended to that timeline."
+                " A new timeline is created when omitted."
+            )
+        ),
+    ] = None,
+) -> ToolResult:
+    """Analyze video brightness and generate an OTIO timeline with a color directive.
+
+    The input media file is never modified (non-destructive, readOnly).
+    Measures average luma with ffmpeg signalstats and writes a color directive
+    to timeline-level metadata["clipwright"]["color"].
+    Returns the path of the resulting timeline.otio in artifacts.
+
+    Delegates business logic to color.detect_color.
+    Uses default DetectColorOptions() when options is None.
+    """
+    resolved_options = options if options is not None else DetectColorOptions()
+    return detect_color(
+        media=media,
+        output=output,
+        options=resolved_options,
+        timeline=timeline,
+    )
+
+
+# ===========================================================================
+# Entry point (MCP stdio launch)
+# ===========================================================================
+
+
+def main() -> None:
+    """CLI entry point. Launches the MCP server over stdio.
+
+    Registered in pyproject.toml [project.scripts] as:
+    clipwright-color = "clipwright_color.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()