clipwright-noise 0.1.1__tar.gz

clipwright_noise-0.1.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.3
+Name: clipwright-noise
+Version: 0.1.1
+Summary: MCP tool for noise detection and OTIO timeline annotation generation. Measures noise floor with ffmpeg astats and writes denoise instructions to timeline.otio.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.1.1
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# clipwright-noise
+
+MCP tool for noise detection and OTIO timeline annotation generation.
+
+## Overview
+
+Measures audio noise floor using ffmpeg `astats` filter,
+writes denoise instructions (backend, parameters) to timeline-level `metadata["clipwright"]["denoise"]`.
+
+Performs detection only (OTIO annotation); realization (ffmpeg filter application) is done once by `clipwright-render`
+(design M3: separation of detection and application).
+
+**Initial render support**:
+- `afftdn` backend: render application supported (`clipwright-render` injects afftdn filter).
+- `deepfilternet` backend: annotation only. render application not yet supported (planned in future version).
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg / ffprobe must exist on PATH or full paths set in environment variables `CLIPWRIGHT_FFMPEG` / `CLIPWRIGHT_FFPROBE`.**
+
+Add ffmpeg to PATH directly or specify via environment variables:
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_noise`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input media file path (video + audio required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.backend` | `"afftdn" \| "deepfilternet"` | `"afftdn"` | denoise backend |
+| `options.strength` | `"light" \| "medium" \| "strong"` | `"medium"` | afftdn nr mapping (light=6/medium=12/strong=24 dB) |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append to it) |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `clipwright` | Shared types, envelope, errors, process.run |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+ffmpeg / ffprobe are invoked as separate processes (via PATH or environment variables) for license independence.
+DeepFilterNet binary is not bundled in initial version; render-side dependency planned.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-noise clipwright-noise
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-noise
+clipwright-noise
+```

clipwright_noise-0.1.1/README.md

@@ -0,0 +1,67 @@
+# clipwright-noise
+
+MCP tool for noise detection and OTIO timeline annotation generation.
+
+## Overview
+
+Measures audio noise floor using ffmpeg `astats` filter,
+writes denoise instructions (backend, parameters) to timeline-level `metadata["clipwright"]["denoise"]`.
+
+Performs detection only (OTIO annotation); realization (ffmpeg filter application) is done once by `clipwright-render`
+(design M3: separation of detection and application).
+
+**Initial render support**:
+- `afftdn` backend: render application supported (`clipwright-render` injects afftdn filter).
+- `deepfilternet` backend: annotation only. render application not yet supported (planned in future version).
+
+## Prerequisites
+
+- Python 3.11 or later
+- **ffmpeg / ffprobe must exist on PATH or full paths set in environment variables `CLIPWRIGHT_FFMPEG` / `CLIPWRIGHT_FFPROBE`.**
+
+Add ffmpeg to PATH directly or specify via environment variables:
+
+```bash
+export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
+export CLIPWRIGHT_FFPROBE=/path/to/ffprobe
+```
+
+## MCP Tool
+
+`clipwright_detect_noise`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input media file path (video + audio required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.backend` | `"afftdn" \| "deepfilternet"` | `"afftdn"` | denoise backend |
+| `options.strength` | `"light" \| "medium" \| "strong"` | `"medium"` | afftdn nr mapping (light=6/medium=12/strong=24 dB) |
+| `timeline` | `string \| null` | `null` | Existing OTIO timeline path (if specified, append to it) |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `clipwright` | Shared types, envelope, errors, process.run |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+ffmpeg / ffprobe are invoked as separate processes (via PATH or environment variables) for license independence.
+DeepFilterNet binary is not bundled in initial version; render-side dependency planned.
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-noise clipwright-noise
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-noise
+clipwright-noise
+```

clipwright_noise-0.1.1/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "clipwright-noise"
+version = "0.1.1"
+description = "MCP tool for noise detection and OTIO timeline annotation generation. Measures noise floor with ffmpeg astats and writes denoise instructions to timeline.otio."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "satoh-y-0323", email = "shoma.papa.0323@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "clipwright>=0.1.1",
+    "mcp[cli]>=1.27.2",
+    "pydantic>=2",
+]
+
+[project.scripts]
+clipwright-noise = "clipwright_noise.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "clipwright-render",
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.16",
+]
+
+# Resolve clipwright (core) and clipwright-render within workspace by path reference
+[tool.uv.sources]
+clipwright = { workspace = true }
+clipwright-render = { 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
+"tests/*.py" = ["E501"]
+
+[tool.ruff.format]
+# Default ruff formatter is OK
+
+# --- 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
+
+# opentimelineio has no stubs, ignored with mypy strict
+[[tool.mypy.overrides]]
+module = "opentimelineio.*"
+ignore_missing_imports = true
+
+# --- pytest ---
+[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",
+]
+
+# --- coverage ---
+[tool.coverage.run]
+source = ["clipwright_noise"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_noise-0.1.1/src/clipwright_noise/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-noise: Noise detection → OTIO timeline annotation generation MCP tool."""
+
+__version__ = "0.1.1"

clipwright_noise-0.1.1/src/clipwright_noise/analyze.py

@@ -0,0 +1,149 @@
+"""analyze.py — Noise floor measurement and parameter calculation via ffmpeg astats.
+
+Design reference: §2.3.
+
+Measures audio RMS/Noise_floor using the astats filter,
+then calculates denoise parameters per backend.
+Falls back to nf=-50.0 when measurement is unavailable,
+returning a warning (design B-6).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from clipwright.process import resolve_tool, run
+
+# strength → afftdn nr (dB) mapping (design §2.1 fixed values)
+_STRENGTH_TO_NR: dict[str, float] = {
+    "light": 6.0,
+    "medium": 12.0,
+    "strong": 24.0,
+}
+
+# nf fallback value (when astats measurement is unavailable; design B-6)
+_NF_FALLBACK: float = -50.0
+
+# nf clamp range (aligned with AfftdnParams constraints)
+_NF_MIN: float = -80.0
+_NF_MAX: float = -20.0
+
+# astats execution timeout (seconds)
+_TIMEOUT_SECONDS: float = 60.0
+
+
+def _parse_noise_floor(stderr: str) -> float | None:
+    """Extract the noise floor value (dB) from astats stderr.
+
+    Priority:
+    1. `Noise floor dB:` field (actual ffmpeg astats output format)
+    2. `RMS level dB:` field (fallback)
+
+    Returns None if extraction fails.
+    """
+    # Prefer Noise floor dB (actual ffmpeg astats output format: "Noise floor dB: -X.X")
+    m = re.search(r"Noise floor dB:\s*(-?\d+\.?\d*)", stderr)
+    if m:
+        try:
+            return float(m.group(1))
+        except ValueError:
+            pass
+
+    # Fall back to RMS level dB (actual ffmpeg astats output: "RMS level dB: -X.X")
+    m = re.search(r"RMS level dB:\s*(-?\d+\.?\d*)", stderr)
+    if m:
+        try:
+            return float(m.group(1))
+        except ValueError:
+            pass
+
+    return None
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    """Clamp value to the range [lo, hi]."""
+    return max(lo, min(hi, value))
+
+
+def measure_noise(
+    media_path: Path,
+    strength: str,
+    backend: str,
+) -> dict[str, Any]:
+    """Analyze media audio with astats and return denoise parameters per backend.
+
+    Args:
+        media_path: Path to the input media file (video + audio).
+        strength: DetectNoiseOptions.strength ("light"/"medium"/"strong").
+        backend: "afftdn" or "deepfilternet".
+
+    Returns:
+        {
+            "params": dict (AfftdnParams-equivalent or {}),
+            "measured_noise_floor_db": float | None,
+            "warnings": list[str],
+        }
+
+    Raises:
+        clipwright.errors.ClipwrightError: DEPENDENCY_MISSING / SUBPROCESS_FAILED /
+            SUBPROCESS_TIMEOUT.
+    """
+    # Resolve the ffmpeg binary (B-1: PATH-independent via resolve_tool)
+    ffmpeg_bin = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+
+    # Measure noise floor for the entire duration with astats
+    # (metadata=1:reset=0 for global stats)
+    cmd = [
+        ffmpeg_bin,
+        "-i",
+        str(media_path),
+        "-af",
+        "astats=metadata=1:reset=0",
+        "-f",
+        "null",
+        "-",
+    ]
+
+    warnings: list[str] = []
+
+    # run raises ClipwrightError (SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT, etc.),
+    # which propagates directly to the caller.
+    result = run(
+        cmd,
+        timeout=_TIMEOUT_SECONDS,
+    )
+
+    # astats statistics are written to stderr (run returns CompletedProcess)
+    stderr_text = result.stderr
+
+    measured = _parse_noise_floor(stderr_text)
+
+    if backend == "afftdn":
+        nr = _STRENGTH_TO_NR.get(strength, _STRENGTH_TO_NR["medium"])
+
+        if measured is not None:
+            nf = _clamp(measured, _NF_MIN, _NF_MAX)
+        else:
+            nf = _NF_FALLBACK
+            warnings.append(
+                f"Noise floor measurement failed; using default nf={_NF_FALLBACK}."
+                " The astats output did not contain"
+                " Noise floor dB / RMS level dB fields."
+            )
+
+        params: dict[str, Any] = {"nr": nr, "nf": nf, "nt": "w"}
+    else:
+        # deepfilternet: params fixed to {} (first release; design DC-AM-002)
+        if measured is None:
+            warnings.append(
+                "Noise floor measurement failed; measured_noise_floor_db will be None."
+            )
+        params = {}
+
+    return {
+        "params": params,
+        "measured_noise_floor_db": measured,
+        "warnings": warnings,
+    }

clipwright_noise-0.1.1/src/clipwright_noise/noise.py

@@ -0,0 +1,364 @@
+"""noise.py — clipwright-noise orchestration layer (design §1.1).
+
+Flow:
+  1. Output validation (extension, parent dir, output==media,
+     output==timeline, same dir)
+  2. inspect_media: video + audio required check (ADR-N8)
+  3. Timeline resolution (None → new / path → load + validate)
+  4. measure_noise: measure noise floor via astats → calculate params
+  5. Partial update of denoise directive into timeline-level metadata
+  6. save_timeline → return ok_result
+
+Design decisions:
+- FILE_NOT_FOUND / SUBPROCESS_FAILED messages use basename only (DC-GP-005).
+- output must be in the same directory as media (MUST; DC-AS-002).
+- source==media comparison is normalized with Path.resolve() (DC-AS-003 / B-4).
+- Timeline validation: exactly one Video-kind track (B-5).
+"""
+
+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
+
+import clipwright_noise
+from clipwright_noise.analyze import measure_noise
+from clipwright_noise.schemas import DenoiseDirective, DetectNoiseOptions
+
+
+def detect_noise(
+    media: str,
+    output: str,
+    options: DetectNoiseOptions,
+    timeline: str | None,
+) -> dict[str, Any]:
+    """Public API for noise detection. Converts ClipwrightError to ok=False.
+
+    Args:
+        media: Input media file path (video + audio required).
+        output: Output OTIO timeline file path (.otio; same directory as media).
+        options: DetectNoiseOptions.
+        timeline: Existing timeline path (None = create new).
+
+    Returns:
+        ok_result or error_result envelope dict.
+    """
+    try:
+        return _detect_noise_inner(media, output, options, timeline)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _detect_noise_inner(
+    media: str,
+    output: str,
+    options: DetectNoiseOptions,
+    timeline: str | None,
+) -> dict[str, Any]:
+    """Internal implementation of detect_noise. 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=f"Unsupported output extension: {output_path.suffix!r}",
+            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; M5)
+    if _same_path(output_path, media_path):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path and input media path are identical.",
+            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 identical.",
+            hint="Change the output file path to differ from the input timeline.",
+        )
+
+    # output must be in same directory as media (MUST; 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=(
+                "The output file must be 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 + audio required (ADR-N8 / DC-AS-003) ---
+
+    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)
+    has_audio = any(s.codec_type == "audio" for s in media_info.streams)
+
+    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 both video and audio.",
+        )
+
+    if not has_audio:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message=f"No audio stream found: {media_path.name}",
+            hint="Provide a media file that contains both video and audio.",
+        )
+
+    # Obtain duration (total duration in seconds passed to _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:
+        # New timeline: append one full-length keep clip to V1
+        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. Noise analysis ---
+
+    analysis = measure_noise(
+        media_path=media_path,
+        strength=options.strength,
+        backend=options.backend,
+    )
+
+    params: dict[str, Any] = analysis["params"]
+    measured: float | None = analysis["measured_noise_floor_db"]
+    warnings: list[str] = list(analysis["warnings"])
+
+    # --- 5. Partial update of denoise directive into timeline-level metadata ---
+
+    directive = DenoiseDirective(
+        tool="clipwright-noise",
+        version=clipwright_noise.__version__,
+        kind="denoise",
+        backend=options.backend,
+        params=params,
+        measured_noise_floor_db=measured,
+    )
+
+    existing_meta = get_clipwright_metadata(tl)
+    existing_meta["denoise"] = directive.model_dump()
+    set_clipwright_metadata(tl, existing_meta)
+
+    # Add render-not-supported warning when deepfilternet is selected (DC-GP-003)
+    if options.backend == "deepfilternet":
+        warnings.append(
+            "backend=deepfilternet was selected."
+            " Render application is not supported (first release: afftdn only)."
+            " Re-detect with afftdn or wait for a future release."
+        )
+
+    # --- 6. save_timeline → ok_result ---
+
+    save_timeline(tl, str(output_path))
+
+    summary = (
+        f"Noise analysis of {media_path.name} completed."
+        f" backend={options.backend}, strength={options.strength}."
+        f" Denoise directive written to {output_path.name}."
+        + (
+            f" Measured noise floor: {measured:.1f} dB."
+            if measured is not None
+            else " Noise floor measurement failed; default value used."
+        )
+    )
+
+    return ok_result(
+        summary,
+        data={
+            "backend": options.backend,
+            "strength": options.strength,
+            "measured_noise_floor_db": measured,
+            "params": params,
+        },
+        artifacts=[
+            {"role": "timeline", "path": str(output_path), "format": "otio"},
+        ],
+        warnings=warnings,
+    )
+
+
+def _add_full_clip(
+    tl: otio.schema.Timeline,
+    media_path: Path,
+    duration_sec: float,
+    duration_rt: RationalTimeModel | None,
+) -> None:
+    """Append one full-length keep clip to the V1/A1 tracks of the timeline.
+
+    Used for new timelines.
+    target_url is the absolute path of media_path.resolve() (DC-AS-002).
+    """
+    try:
+        target_url = str(media_path.resolve())
+    except OSError:
+        target_url = str(media_path.absolute())
+
+    # Determine rate: use the measured duration rate if available, otherwise 1000.0
+    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)
+
+    # Append the same clip to V1 (index 0) and A1 (index 1)
+    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.
+
+    Validation references: DC-AM-003 / DC-AM-004 / B-4 / B-5.
+
+    Validation:
+    - V1 clip target_url matches media_path (B-4: normalized path comparison)
+    - Single source (all clips share the same target_url)
+    - Exactly one Video-kind track (B-5)
+
+    If V1 is empty, a full-length keep clip is appended and processing continues
+    (to make the timeline renderable, equivalent to creating a new one;
+    prevents render from rejecting with INVALID_INPUT due to zero clips).
+
+    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]
+
+    # --- Collect all clip target_urls and validate single source (DC-AM-004) ---
+    clips = [item for item in v1 if isinstance(item, otio.schema.Clip)]
+
+    if not clips:
+        # V1 is empty: append a full-length keep clip and continue
+        # (equivalent to creating a new timeline).
+        # Prevents render's resolve_kept_ranges from rejecting due to zero 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)
+
+    if len(urls) > 1:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message="The 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() normalized comparison) ---
+    if urls:
+        target_url = next(iter(urls))
+        try:
+            tl_source = Path(target_url).resolve()
+            media_resolved = media_path.resolve()
+        except OSError:
+            # On OSError, fall back to absolute() comparison (best-effort)
+            tl_source = Path(target_url).absolute()
+            media_resolved = media_path.absolute()
+
+        if tl_source != media_resolved:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message=(
+                    "Timeline source file does not match the 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 generated."
+                ),
+            )
+
+    return tl
+
+
+def _same_path(a: Path, b: Path) -> bool:
+    """Return True if two paths refer to the same entity.
+
+    Falls back to string comparison on OSError.
+    """
+    try:
+        return a.resolve() == b.resolve()
+    except OSError:
+        return str(a) == str(b)

clipwright_noise-0.1.1/src/clipwright_noise/schemas.py

@@ -0,0 +1,96 @@
+"""schemas.py — clipwright-noise-specific Pydantic schemas.
+
+Common types (MediaRef / Artifact / ToolResult, etc.) are defined centrally
+in clipwright.schemas and are not redefined here.
+
+DetectNoiseOptions: Input options for clipwright_detect_noise.
+DenoiseDirective: Directive schema written to timeline-level
+    metadata["clipwright"]["denoise"].
+AfftdnParams: afftdn filter parameters (body of DenoiseDirective.params).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DetectNoiseOptions(BaseModel):
+    """Options for clipwright_detect_noise (design §2.1).
+
+    The `track` field is deprecated (ADR-N7).
+    The first audio stream is processed unconditionally.
+    """
+
+    backend: Annotated[
+        Literal["afftdn", "deepfilternet"],
+        Field(
+            default="afftdn",
+            description=(
+                "Denoise backend. "
+                '"afftdn" (default) applies the ffmpeg afftdn filter at render time. '
+                '"deepfilternet" generates annotations only; '
+                "render application is not supported (first release)."
+            ),
+        ),
+    ] = "afftdn"
+
+    strength: Annotated[
+        Literal["light", "medium", "strong"],
+        Field(
+            default="medium",
+            description=(
+                "Strength mapped to afftdn nr (noise reduction dB). "
+                "light=6 / medium=12 / strong=24 (fixed values). "
+                "Not referenced when using the deepfilternet backend."
+            ),
+        ),
+    ] = "medium"
+
+
+class AfftdnParams(BaseModel):
+    """afftdn filter parameters (design §2.2 / DC-AS-006).
+
+    Used when render re-validates DenoiseDirective.params as AfftdnParams.
+    Applied only when backend=="afftdn".
+    """
+
+    nr: Annotated[
+        float,
+        Field(ge=0.01, le=97, description="Noise reduction (dB). Range [0.01, 97]."),
+    ]
+    nf: Annotated[
+        float,
+        Field(ge=-80, le=-20, description="Noise floor (dB). Range [-80, -20]."),
+    ]
+    nt: Annotated[
+        Literal["w", "v"],
+        Field(default="w", description="Noise type. w=white noise (default), v=vinyl."),
+    ] = "w"
+
+
+class DenoiseDirective(BaseModel):
+    """Denoise directive schema written to timeline-level metadata (design §2.2).
+
+    Generated by noise; loaded and validated by render.
+    When backend=="afftdn", params is a dict equivalent to AfftdnParams
+    (re-validated by render).
+    When backend=="deepfilternet", params is fixed to {} (first release).
+    """
+
+    tool: Annotated[str, Field(max_length=64)]
+    version: Annotated[str, Field(max_length=64)]
+    kind: Literal["denoise"]
+    backend: Literal["afftdn", "deepfilternet"]
+    params: dict[str, Any]
+    measured_noise_floor_db: Annotated[float, Field(ge=-200.0, le=0.0)] | None = None
+
+    @field_validator("measured_noise_floor_db", mode="before")
+    @classmethod
+    def _reject_non_finite(cls, v: object) -> object:
+        """Reject inf / nan (CWE-20: invalid numeric value elimination)."""
+        if isinstance(v, float) and not math.isfinite(v):
+            raise ValueError("inf / nan cannot be used for measured_noise_floor_db.")
+        return v

clipwright_noise-0.1.1/src/clipwright_noise/server.py

@@ -0,0 +1,105 @@
+"""server.py — clipwright-noise MCP server + CLI entry point.
+
+A thin wrapper that delegates business logic to noise.py.
+ClipwrightError conversion is handled in noise.py; no double conversion here.
+
+Transport defaults to stdio (mcp.run(transport="stdio")).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_noise.noise import detect_noise
+from clipwright_noise.schemas import DetectNoiseOptions
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-noise")
+
+
+# ===========================================================================
+# clipwright_detect_noise MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_detect_noise(
+    media: Annotated[
+        str,
+        Field(description="Input media file path (must contain video and audio)."),
+    ],
+    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[
+        DetectNoiseOptions | None,
+        Field(
+            description=(
+                "Noise detection options (backend / strength). "
+                "Defaults to backend=afftdn / strength=medium when omitted."
+            )
+        ),
+    ] = None,
+    timeline: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Existing OTIO timeline file path. "
+                "When specified, the denoise directive is appended to that timeline. "
+                "A new timeline is generated when omitted."
+            )
+        ),
+    ] = None,
+) -> dict[str, Any]:
+    """MCP tool: analyzes audio noise and generates a denoise-annotated OTIO timeline.
+
+    The input media file is never modified (non-destructive / readOnly).
+    Measures the noise floor via ffmpeg astats, calculates backend-specific parameters,
+    and writes them to timeline-level metadata["clipwright"]["denoise"].
+    Returns the path to the annotated timeline.otio in artifacts.
+
+    Business logic is delegated to noise.detect_noise.
+    When options is None, the default DetectNoiseOptions() is used.
+    """
+    resolved_options = options if options is not None else DetectNoiseOptions()
+    return detect_noise(
+        media=media,
+        output=output,
+        options=resolved_options,
+        timeline=timeline,
+    )
+
+
+# ===========================================================================
+# Entry point (MCP stdio launch)
+# ===========================================================================
+
+
+def main() -> None:
+    """CLI entry point. Starts the MCP server over stdio.
+
+    Registered in pyproject.toml [project.scripts] as:
+    clipwright-noise = "clipwright_noise.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()