clipwright-stabilize 0.1.0__tar.gz

clipwright_stabilize-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.3
+Name: clipwright-stabilize
+Version: 0.1.0
+Summary: MCP tool for video shake detection using ffmpeg vidstabdetect (requires ffmpeg with libvidstab). Generates a .trf analysis file and writes a stabilize directive to OTIO timeline metadata for use with clipwright-render.
+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-stabilize
+
+MCP tool for video shake detection and OTIO timeline stabilize annotation generation.
+
+## Overview
+
+Runs ffmpeg `vidstabdetect` to generate a `.trf` transform file,
+estimates shake severity from the binary TRF1 data (best-effort heuristic),
+and writes a stabilize directive to timeline-level
+`metadata["clipwright"]["stabilize"]`.
+
+Performs detection only (OTIO annotation); realization (vidstabtransform application)
+is done once by `clipwright-render` (design M3: separation of detection and application).
+
+**Severity estimation**:
+
+- Reads the binary TRF1 file produced by vidstabdetect.
+- Scans all IEEE-754 little-endian doubles, computes mean absolute value.
+- Normalises by a pinned heuristic constant (`_NORM_PX = 30.0 px`) to derive a
+  severity in `[0.0, 1.0]`.
+- Returns `severity=null` when the file cannot be parsed (non-fatal; render does not
+  use severity).
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg compiled with `--enable-libvidstab` must exist on PATH or full path set**
+  **in environment variable `CLIPWRIGHT_FFMPEG`.**
+  Standard distribution builds (apt, brew, choco) may NOT include libvidstab.
+  Use a build that explicitly enables the vidstab filter.
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg-with-libvidstab
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_shake`
+
+### 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.shakiness` | `int` | `5` | vidstabdetect shakiness 1-10 (higher = assume more shake) |
+| `options.accuracy` | `int` | `15` | vidstabdetect accuracy 1-15 (higher = more accurate / slower) |
+| `options.smoothing` | `int` | `30` | vidstabtransform smoothing window in frames 0-1000 |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append stabilize directive) |
+
+### Return value
+
+The tool returns a ToolResult envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Shake analysis of video.mp4 complete. severity=0.312, shakiness=5, smoothing=30. Stabilize directive and video.stabilize.trf written; apply with clipwright-render.",
+  "data": {
+    "severity": 0.312,
+    "shakiness": 5,
+    "accuracy": 15,
+    "smoothing": 30,
+    "trf_basename": "video.stabilize.trf"
+  },
+  "artifacts": [
+    {"role": "timeline", "path": "out.otio", "format": "otio"},
+    {"role": "analysis", "path": "video.stabilize.trf", "format": "trf"}
+  ],
+  "warnings": []
+}
+```
+
+When libvidstab is not compiled into the ffmpeg build, the tool returns
+`UNSUPPORTED_OPERATION` with installation guidance (no path or raw stderr exposed).
+
+## 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 "vidstabdetect=result=<stem>.stabilize.trf:shakiness=<n>:accuracy=<n>" -f null -`
+   generates `.trf` and saves the stabilize directive to OTIO annotation.
+2. **render (clipwright-render)**: reads `metadata["clipwright"]["stabilize"]` and applies
+   `vidstabtransform=input=<basename>:smoothing=<n>` in the ffmpeg filter graph
+   using `cwd=<trf parent directory>` for Windows-safe relative path resolution.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-stabilize clipwright-stabilize
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-stabilize
+clipwright-stabilize
+```

clipwright_stabilize-0.1.0/README.md

@@ -0,0 +1,109 @@
+# clipwright-stabilize
+
+MCP tool for video shake detection and OTIO timeline stabilize annotation generation.
+
+## Overview
+
+Runs ffmpeg `vidstabdetect` to generate a `.trf` transform file,
+estimates shake severity from the binary TRF1 data (best-effort heuristic),
+and writes a stabilize directive to timeline-level
+`metadata["clipwright"]["stabilize"]`.
+
+Performs detection only (OTIO annotation); realization (vidstabtransform application)
+is done once by `clipwright-render` (design M3: separation of detection and application).
+
+**Severity estimation**:
+
+- Reads the binary TRF1 file produced by vidstabdetect.
+- Scans all IEEE-754 little-endian doubles, computes mean absolute value.
+- Normalises by a pinned heuristic constant (`_NORM_PX = 30.0 px`) to derive a
+  severity in `[0.0, 1.0]`.
+- Returns `severity=null` when the file cannot be parsed (non-fatal; render does not
+  use severity).
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg compiled with `--enable-libvidstab` must exist on PATH or full path set**
+  **in environment variable `CLIPWRIGHT_FFMPEG`.**
+  Standard distribution builds (apt, brew, choco) may NOT include libvidstab.
+  Use a build that explicitly enables the vidstab filter.
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg-with-libvidstab
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_shake`
+
+### 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.shakiness` | `int` | `5` | vidstabdetect shakiness 1-10 (higher = assume more shake) |
+| `options.accuracy` | `int` | `15` | vidstabdetect accuracy 1-15 (higher = more accurate / slower) |
+| `options.smoothing` | `int` | `30` | vidstabtransform smoothing window in frames 0-1000 |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append stabilize directive) |
+
+### Return value
+
+The tool returns a ToolResult envelope:
+
+```json
+{
+  "ok": true,
+  "summary": "Shake analysis of video.mp4 complete. severity=0.312, shakiness=5, smoothing=30. Stabilize directive and video.stabilize.trf written; apply with clipwright-render.",
+  "data": {
+    "severity": 0.312,
+    "shakiness": 5,
+    "accuracy": 15,
+    "smoothing": 30,
+    "trf_basename": "video.stabilize.trf"
+  },
+  "artifacts": [
+    {"role": "timeline", "path": "out.otio", "format": "otio"},
+    {"role": "analysis", "path": "video.stabilize.trf", "format": "trf"}
+  ],
+  "warnings": []
+}
+```
+
+When libvidstab is not compiled into the ffmpeg build, the tool returns
+`UNSUPPORTED_OPERATION` with installation guidance (no path or raw stderr exposed).
+
+## 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 "vidstabdetect=result=<stem>.stabilize.trf:shakiness=<n>:accuracy=<n>" -f null -`
+   generates `.trf` and saves the stabilize directive to OTIO annotation.
+2. **render (clipwright-render)**: reads `metadata["clipwright"]["stabilize"]` and applies
+   `vidstabtransform=input=<basename>:smoothing=<n>` in the ffmpeg filter graph
+   using `cwd=<trf parent directory>` for Windows-safe relative path resolution.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-stabilize clipwright-stabilize
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-stabilize
+clipwright-stabilize
+```

clipwright_stabilize-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "clipwright-stabilize"
+version = "0.1.0"
+description = "MCP tool for video shake detection using ffmpeg vidstabdetect (requires ffmpeg with libvidstab). Generates a .trf analysis file and writes a stabilize directive to OTIO timeline metadata for use with clipwright-render."
+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-stabilize = "clipwright_stabilize.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", "I001"]
+
+[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/libvidstab",
+    "slow: test with long execution time",
+    "e2e: e2e test using actual ffmpeg binary with libvidstab",
+]
+
+[tool.coverage.run]
+source = ["clipwright_stabilize"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_stabilize-0.1.0/src/clipwright_stabilize/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

clipwright_stabilize-0.1.0/src/clipwright_stabilize/analyze.py

@@ -0,0 +1,207 @@
+"""analyze.py — ffmpeg vidstabdetect execution for clipwright-stabilize.
+
+Runs ffmpeg with the vidstabdetect filter to generate a .trf transform file,
+then estimates shake severity from the binary TRF1 file contents.
+
+Key design decisions:
+- cwd + relative basename is the only Windows-safe approach for vid.stab
+  result= / input= paths (P-2/P-3: Windows absolute paths are not escaped by
+  the filtergraph parser used by libvidstab).
+- _TIMEOUT_SECONDS is pinned at 300.0 for the initial release (F-5).
+- _estimate_severity is heuristic/best-effort; parse failure returns None (F-2/F-3).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import struct
+from pathlib import Path
+from typing import Any
+
+from clipwright.errors import ClipwrightError, ErrorCode
+from clipwright.process import resolve_tool, run
+
+from clipwright_stabilize.schemas import DetectShakeOptions
+
+# ffmpeg execution timeout (seconds). vidstabdetect scans every frame so
+# it takes longer than a measurement-only pass. Pinned for initial release (F-5).
+_TIMEOUT_SECONDS: float = 300.0
+
+# TRF1 binary file magic header.
+_TRF_MAGIC = b"TRF1"
+
+# Normalisation constant for severity estimation (heuristic / pinned — F-2/F-3).
+# Mean absolute pixel displacement at or above this value maps to severity=1.0.
+# Chosen based on typical camera shake magnitudes; adjust after e2e calibration.
+_NORM_PX: float = 30.0
+
+# Regex for detecting libvidstab filter absence in error messages (P-4 / §4-B).
+_UNSUPPORTED_RE = re.compile(r"Unknown filter|No such filter", re.IGNORECASE)
+
+# Maximum .trf file size accepted by _estimate_severity (OOM DoS guard — SR-MEM-001).
+# Files larger than this are treated as unparseable (best-effort, return None).
+_TRF_MAX_BYTES: int = 100 * 1024 * 1024  # 100 MB
+
+# Sanitise filtergraph-unsafe characters from a trf stem (SR-INJ-002).
+# vid.stab result=/input= cannot be safely escaped with backslash sequences;
+# instead we replace any character that is not alphanumeric, '-', or '_' with '_'.
+# An empty result falls back to "media" to guarantee a non-empty basename.
+_TRF_STEM_SANITIZE_RE = re.compile(r"[^A-Za-z0-9\-_]")
+
+
+def _estimate_severity(trf_path: Path) -> float | None:
+    """Best-effort severity in 0.0-1.0 from a binary TRF1 file.
+
+    The .trf body contains a TRF1 magic followed by IEEE-754 doubles describing
+    per-frame transforms (translation x/y, rotation, zoom). We scan all
+    little-endian doubles, take the mean absolute value of finite doubles,
+    and normalise by _NORM_PX (heuristic / pinned constant — F-2/F-3).
+    Any parse anomaly (magic mismatch, empty body, all non-finite, struct error,
+    OSError) returns None (render does not use severity).
+
+    Args:
+        trf_path: Path to the .trf binary file.
+
+    Returns:
+        Severity in [0.0, 1.0], or None when the file cannot be parsed.
+    """
+    try:
+        blob = trf_path.read_bytes()
+    except OSError:
+        return None
+
+    if len(blob) > _TRF_MAX_BYTES:
+        return None  # best-effort; oversized .trf treated as unparseable
+
+    if not blob.startswith(_TRF_MAGIC):
+        return None
+
+    body = blob[len(_TRF_MAGIC) :]
+    n = len(body) // 8
+    if n == 0:
+        return None
+
+    try:
+        unpacked = struct.unpack_from(f"<{n}d", body, 0)
+    except struct.error:
+        return None
+
+    finite = [abs(v) for v in unpacked if math.isfinite(v)]
+    if not finite:
+        return None
+
+    mean_abs: float = sum(finite) / len(finite)
+    # Normalise mean pixel displacement to 0..1 (_NORM_PX is a pinned heuristic
+    # constant; see ADR-ST-3). Values above _NORM_PX clamp to 1.0.
+    severity: float = mean_abs / _NORM_PX
+    if not math.isfinite(severity):
+        return None
+
+    return max(0.0, min(1.0, severity))
+
+
+def run_vidstabdetect(
+    media_path: Path,
+    output_path: Path,
+    options: DetectShakeOptions,
+) -> dict[str, Any]:
+    """Run ffmpeg vidstabdetect to generate a .trf file and estimate severity.
+
+    Uses cwd + relative trf basename (P-2/P-3): Windows absolute paths cannot be
+    safely used in vidstab filtergraph result= / input= parameters.
+
+    Args:
+        media_path: Input video file (absolute path).
+        output_path: Output .otio path; trf is written to output_path.parent.
+        options: DetectShakeOptions with shakiness / accuracy / smoothing.
+
+    Returns:
+        {
+            "trf_path": str,           # absolute path of the generated .trf file
+            "severity": float | None,  # 0.0-1.0 best-effort, None when unparseable
+            "warnings": list[str],
+        }
+
+    Raises:
+        ClipwrightError: DEPENDENCY_MISSING / UNSUPPORTED_OPERATION /
+            SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT (sanitised messages, CWE-209).
+    """
+    ffmpeg_bin = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+
+    trf_dir = output_path.parent
+    # Sanitise stem: replace filtergraph-unsafe chars with '_' (SR-INJ-002).
+    # cwd+relative basename approach (ADR-ST-1/P-2/P-3) is preserved.
+    sanitized_stem = _TRF_STEM_SANITIZE_RE.sub("_", media_path.stem) or "media"
+    trf_name = f"{sanitized_stem}.stabilize.trf"  # relative basename (cwd-based)
+    trf_abs = trf_dir / trf_name
+
+    # -vf is a single argv element (CWE-78).
+    # shakiness / accuracy are validated int values from Pydantic — no injection risk.
+    vf = (
+        f"vidstabdetect=result={trf_name}"
+        f":shakiness={options.shakiness}"
+        f":accuracy={options.accuracy}"
+    )
+    cmd: list[str] = [
+        ffmpeg_bin,
+        "-hide_banner",
+        "-i",
+        str(media_path.resolve()),  # absolute input path (cwd-independent)
+        "-vf",
+        vf,
+        "-f",
+        "null",
+        "-",
+    ]
+
+    try:
+        run(cmd, timeout=_TIMEOUT_SECONDS, cwd=str(trf_dir))
+    except ClipwrightError as exc:
+        # libvidstab not compiled into this ffmpeg build — stderr contains
+        # "Unknown filter" or "No such filter" (P-4 / §4-B).
+        if exc.code == ErrorCode.SUBPROCESS_FAILED and _UNSUPPORTED_RE.search(
+            exc.message
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.UNSUPPORTED_OPERATION,
+                message=(
+                    "This ffmpeg build does not support the vidstabdetect filter."
+                ),
+                hint=(
+                    "Install an ffmpeg build compiled with libvidstab "
+                    "(--enable-libvidstab), then retry."
+                ),
+            ) from None  # CWE-209: cut __cause__ to avoid leaking abs paths / stderr
+
+        # All other failures (SUBPROCESS_FAILED without filter keyword,
+        # SUBPROCESS_TIMEOUT, DEPENDENCY_MISSING) — sanitise and re-raise.
+        raise ClipwrightError(
+            code=exc.code,
+            message="ffmpeg vidstabdetect command failed.",
+            hint="Check the ffmpeg version and that libvidstab is enabled.",
+        ) from None  # CWE-209: cut __cause__
+
+    # Defensive check: rc=0 but .trf was not generated (frames parity — §4-D).
+    if not trf_abs.exists():
+        raise ClipwrightError(
+            code=ErrorCode.SUBPROCESS_FAILED,
+            message="ffmpeg succeeded but the .trf output file was not generated.",
+            hint=(
+                "Check that libvidstab is enabled and the output directory is writable."
+            ),
+        )
+
+    warnings: list[str] = []
+    severity = _estimate_severity(trf_abs)
+    if severity is None:
+        warnings.append(
+            "Could not estimate shake severity from the .trf file;"
+            " severity recorded as null."
+        )
+
+    return {
+        "trf_path": str(trf_abs.resolve()),
+        "severity": severity,
+        "warnings": warnings,
+    }

clipwright_stabilize-0.1.0/src/clipwright_stabilize/schemas.py

@@ -0,0 +1,47 @@
+"""schemas.py — Pydantic models for clipwright-stabilize.
+
+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 DetectShakeOptions(BaseModel):
+    """Options for clipwright_detect_shake.
+
+    shakiness: vidstabdetect shakiness (1-10). Higher = assume more shake.
+    accuracy:  vidstabdetect accuracy (1-15). Higher = more accurate / slower.
+    smoothing: vidstabtransform smoothing window (frames, 0-1000). Consumed by
+        clipwright-render at apply time; recorded here for round-trip.
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    shakiness: Annotated[int, Field(ge=1, le=10)] = 5
+    accuracy: Annotated[int, Field(ge=1, le=15)] = 15
+    smoothing: Annotated[int, Field(ge=0, le=1000)] = 30
+
+
+class StabilizeDirective(BaseModel):
+    """Directive written to timeline metadata["clipwright"]["stabilize"].
+
+    Generated by clipwright-stabilize and read/validated by clipwright-render.
+    scope is timeline-level / single-source only (per-source deferred). severity
+    is best-effort (None when the binary .trf could not be parsed).
+    """
+
+    model_config = {"extra": "forbid", "allow_inf_nan": False}
+
+    tool: Annotated[str, Field(max_length=64)] = "clipwright-stabilize"
+    version: Annotated[str, Field(max_length=64)]
+    kind: Literal["stabilize"]
+    trf_path: str  # absolute path (record only; render splits to dir/basename)
+    severity: float | None = None  # 0.0-1.0 best-effort, None when unparseable
+    shakiness: Annotated[int, Field(ge=1, le=10)]
+    accuracy: Annotated[int, Field(ge=1, le=15)]
+    smoothing: Annotated[int, Field(ge=0, le=1000)]

clipwright_stabilize-0.1.0/src/clipwright_stabilize/server.py

@@ -0,0 +1,108 @@
+"""server.py — clipwright-stabilize MCP server + CLI entry point.
+
+Thin wrapper that delegates business logic to stabilize.py.
+ClipwrightError conversion is handled in stabilize.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_stabilize.schemas import DetectShakeOptions
+from clipwright_stabilize.stabilize import detect_shake
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-stabilize")
+
+
+# ===========================================================================
+# clipwright_detect_shake MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=False,  # .trf binary + .otio are generated as side-products
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_detect_shake(
+    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[
+        DetectShakeOptions | None,
+        Field(
+            description=(
+                "Shake detection options (shakiness / accuracy / smoothing)."
+                " Defaults to shakiness=5 / accuracy=15 / smoothing=30 when omitted."
+            )
+        ),
+    ] = None,
+    timeline: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Existing OTIO timeline file path."
+                " When specified, the stabilize directive is appended to that timeline."
+                " A new timeline is created when omitted."
+            )
+        ),
+    ] = None,
+) -> ToolResult:
+    """Analyze video shake and generate an OTIO timeline with a stabilize directive.
+
+    The input media file is never modified (non-destructive, readOnly).
+    Requires an ffmpeg build compiled with --enable-libvidstab.
+    Runs ffmpeg vidstabdetect to generate a .trf transform file and writes a
+    stabilize directive to timeline-level metadata["clipwright"]["stabilize"].
+    Returns paths of the resulting timeline.otio and analysis.trf in artifacts.
+    The .trf is consumed by clipwright-render (vidstabtransform) to apply stabilization.
+
+    Delegates business logic to stabilize.detect_shake.
+    Uses default DetectShakeOptions() when options is None.
+    """
+    resolved_options = options if options is not None else DetectShakeOptions()
+    return detect_shake(
+        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-stabilize = "clipwright_stabilize.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

clipwright_stabilize-0.1.0/src/clipwright_stabilize/stabilize.py

@@ -0,0 +1,428 @@
+"""stabilize.py — detect_shake 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)
+  3. Timeline resolution (None -> create new / path -> load + validate)
+  4. run_vidstabdetect (generate .trf + estimate severity)
+  5. Build StabilizeDirective and annotate timeline metadata
+     (severity=None -> still write directive, differs from color measured=None skip)
+  6. save_timeline (atomic)
+  7. ok_result with summary / data / artifacts (both .otio and .trf paths verified)
+
+Design decisions:
+- Audio NOT required; shake detection requires video stream only.
+- severity=None does NOT skip directive (trf was generated and can still be applied).
+- output must be in the same directory as media (DC-AS-002).
+- Mirrors color.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
+
+import clipwright_stabilize
+from clipwright_stabilize.analyze import run_vidstabdetect
+from clipwright_stabilize.schemas import DetectShakeOptions, StabilizeDirective
+
+
+def detect_shake(
+    media: str,
+    output: str,
+    options: DetectShakeOptions,
+    timeline: str | None,
+) -> ToolResult:
+    """Public API for shake 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: DetectShakeOptions with shakiness / accuracy / smoothing.
+        timeline: Existing timeline path (None = create new).
+
+    Returns:
+        ok_result or error_result ToolResult.
+    """
+    try:
+        return _detect_shake_inner(media, output, options, timeline)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _detect_shake_inner(
+    media: str,
+    output: str,
+    options: DetectShakeOptions,
+    timeline: str | None,
+) -> ToolResult:
+    """Internal implementation of detect_shake. 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 ---
+    # inspect_media raises FILE_NOT_FOUND internally (color.py parity — no pre-check).
+
+    media_info = inspect_media(media)
+
+    has_video = any(s.codec_type == "video" for s in media_info.streams)
+    # NOTE: no has_audio check — stabilize does not require audio.
+
+    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 for _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. run_vidstabdetect (generates .trf + estimates severity) ---
+
+    analysis: dict[str, Any] = run_vidstabdetect(media_path, output_path, options)
+    warnings: list[str] = list(analysis["warnings"])
+
+    # --- 5. Build StabilizeDirective and annotate timeline metadata ---
+    # severity=None is allowed — directive is always written when trf is generated.
+
+    directive = StabilizeDirective(
+        tool="clipwright-stabilize",
+        version=clipwright_stabilize.__version__,
+        kind="stabilize",
+        trf_path=str(Path(analysis["trf_path"]).resolve()),
+        severity=analysis["severity"],
+        shakiness=options.shakiness,
+        accuracy=options.accuracy,
+        smoothing=options.smoothing,
+    )
+    existing_meta = get_clipwright_metadata(tl)
+    existing_meta["stabilize"] = directive.model_dump()
+    set_clipwright_metadata(tl, existing_meta)
+
+    # --- 6. save_timeline (atomic) ---
+
+    save_timeline(tl, str(output_path))
+
+    # --- 7. ok_result: verify both paths exist, build summary and artifacts ---
+
+    trf_abs = Path(analysis["trf_path"]).resolve()
+    otio_abs = output_path.resolve()
+
+    # Post-save sanity check (frames parity — both artifacts must be on disk).
+    if not otio_abs.exists():
+        raise ClipwrightError(
+            code=ErrorCode.INTERNAL,
+            message="Timeline file was not created after save_timeline.",
+            hint="Check that the output directory is writable.",
+        )
+    if not trf_abs.exists():
+        raise ClipwrightError(
+            code=ErrorCode.SUBPROCESS_FAILED,
+            message="The .trf analysis file is no longer present after vidstabdetect.",
+            hint="Check that the output directory was not modified during analysis.",
+        )
+
+    trf_basename = trf_abs.name
+    sev = analysis["severity"]
+    sev_str = f"{sev:.3f}" if sev is not None else "unavailable"
+
+    summary = (
+        f"Shake analysis of {media_path.name} complete."
+        f" severity={sev_str},"
+        f" shakiness={options.shakiness},"
+        f" smoothing={options.smoothing}."
+        f" Stabilize directive and {trf_basename} written;"
+        f" apply with clipwright-render."
+    )
+
+    return ok_result(
+        summary,
+        data={
+            "severity": analysis["severity"],
+            "shakiness": options.shakiness,
+            "accuracy": options.accuracy,
+            "smoothing": options.smoothing,
+            "trf_basename": trf_basename,
+        },
+        artifacts=[
+            {
+                "role": "timeline",
+                "path": str(otio_abs),
+                "format": "otio",
+            },
+            {
+                "role": "analysis",
+                "path": str(trf_abs),
+                "format": "trf",
+            },
+        ],
+        warnings=warnings if warnings else None,
+    )
+
+
+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)
+
+    # Reject multi-source timelines first (UNSUPPORTED_OPERATION — color.py order).
+    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).",
+        )
+
+    # 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)
+
+    # 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).
+        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