clipwright-loudness 0.1.1__tar.gz

clipwright_loudness-0.1.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.3
+Name: clipwright-loudness
+Version: 0.1.1
+Summary: MCP tool for audio loudness normalization detection and OTIO timeline annotation generation. Measures loudness with ffmpeg loudnorm/volumedetect and writes loudness instructions to timeline-level metadata.
+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-loudness
+
+MCP tool for audio loudness normalization detection and OTIO timeline annotation generation.
+
+## Overview
+
+Measures audio loudness and peak level using ffmpeg `loudnorm` / `volumedetect` filters,
+writes loudness instructions (mode, target, measured) to timeline-level `metadata["clipwright"]["loudness"]`.
+
+Performs detection only (OTIO annotation); realization (ffmpeg filter application) is done once by `clipwright-render`
+(design M3: separation of detection and application).
+
+**Normalization modes**:
+- `loudnorm` (EBU R128 LUFS): Two-stage linear method. detect measures with `loudnorm print_format=json` and saves
+  `measured_*` parameters to OTIO annotation; render applies exact one-pass with `loudnorm:linear=true`.
+- `peak` (max dB match): Measures max_volume with `volumedetect` and applies gain difference in render.
+
+**Initial render support**:
+- `track` scope only (single loudness normalization applied to entire timeline).
+- `per_clip` scope (individual clip application) deferred until after compositing.
+
+## 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_loudness`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input media file path (audio required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.mode` | `"loudnorm" \| "peak"` | `"loudnorm"` | Normalization mode |
+| `options.target_i` | `float` | `-14.0` | loudnorm mode: target integrated loudness (LUFS, -70 to -5) |
+| `options.target_tp` | `float` | `-1.0` | loudnorm mode: target true peak (dBTP, -9 to 0) |
+| `options.target_lra` | `float` | `11.0` | loudnorm mode: target loudness range (LU, 1 to 50) |
+| `options.target_peak_db` | `float` | `-1.0` | peak mode: target peak level (dB, -60 to 0) |
+| `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.
+
+## loudnorm Linear Two-Stage Method
+
+1. **detect (this tool)**: `ffmpeg -i <media> -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null -`
+   gets measured_* parameters and saves them to OTIO annotation.
+2. **render (clipwright-render)**: `loudnorm=I=-14:TP=-1:LRA=11:measured_I=..:...:linear=true`
+   executes only one-pass linear application with detected parameters (improved accuracy).
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-loudness clipwright-loudness
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-loudness
+clipwright-loudness
+```

clipwright_loudness-0.1.1/README.md

@@ -0,0 +1,81 @@
+# clipwright-loudness
+
+MCP tool for audio loudness normalization detection and OTIO timeline annotation generation.
+
+## Overview
+
+Measures audio loudness and peak level using ffmpeg `loudnorm` / `volumedetect` filters,
+writes loudness instructions (mode, target, measured) to timeline-level `metadata["clipwright"]["loudness"]`.
+
+Performs detection only (OTIO annotation); realization (ffmpeg filter application) is done once by `clipwright-render`
+(design M3: separation of detection and application).
+
+**Normalization modes**:
+- `loudnorm` (EBU R128 LUFS): Two-stage linear method. detect measures with `loudnorm print_format=json` and saves
+  `measured_*` parameters to OTIO annotation; render applies exact one-pass with `loudnorm:linear=true`.
+- `peak` (max dB match): Measures max_volume with `volumedetect` and applies gain difference in render.
+
+**Initial render support**:
+- `track` scope only (single loudness normalization applied to entire timeline).
+- `per_clip` scope (individual clip application) deferred until after compositing.
+
+## 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_loudness`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `string` | required | Input media file path (audio required) |
+| `output` | `string` | required | Output OTIO timeline path (`.otio`, same directory as media) |
+| `options.mode` | `"loudnorm" \| "peak"` | `"loudnorm"` | Normalization mode |
+| `options.target_i` | `float` | `-14.0` | loudnorm mode: target integrated loudness (LUFS, -70 to -5) |
+| `options.target_tp` | `float` | `-1.0` | loudnorm mode: target true peak (dBTP, -9 to 0) |
+| `options.target_lra` | `float` | `11.0` | loudnorm mode: target loudness range (LU, 1 to 50) |
+| `options.target_peak_db` | `float` | `-1.0` | peak mode: target peak level (dB, -60 to 0) |
+| `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.
+
+## loudnorm Linear Two-Stage Method
+
+1. **detect (this tool)**: `ffmpeg -i <media> -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null -`
+   gets measured_* parameters and saves them to OTIO annotation.
+2. **render (clipwright-render)**: `loudnorm=I=-14:TP=-1:LRA=11:measured_I=..:...:linear=true`
+   executes only one-pass linear application with detected parameters (improved accuracy).
+
+## Installation and Startup
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-loudness clipwright-loudness
+```
+
+Or install directly:
+
+```bash
+uv add clipwright-loudness
+clipwright-loudness
+```

clipwright_loudness-0.1.1/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "clipwright-loudness"
+version = "0.1.1"
+description = "MCP tool for audio loudness normalization detection and OTIO timeline annotation generation. Measures loudness with ffmpeg loudnorm/volumedetect and writes loudness instructions 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.1.1",
+    "mcp[cli]>=1.27.2",
+    "pydantic>=2",
+]
+
+[project.scripts]
+clipwright-loudness = "clipwright_loudness.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",
+]
+
+# Resolve clipwright (core) within workspace by path reference
+[tool.uv.sources]
+clipwright = { workspace = true }
+
+# --- Ruff ---
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+# Allow E501 for English docstrings/comments in test files
+"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_loudness"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_loudness-0.1.1/src/clipwright_loudness/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-loudness: Loudness detection -> OTIO timeline directive MCP tool."""
+
+__version__ = "0.1.1"

clipwright_loudness-0.1.1/src/clipwright_loudness/analyze.py

@@ -0,0 +1,240 @@
+"""analyze.py — Loudness measurement using ffmpeg loudnorm/volumedetect.
+
+Design §3.1, ADR-L1/L2.
+
+Actual ffmpeg 8.1.1 Windows output format (ADR-L3, verified on real hardware):
+
+  loudnorm print_format=json:
+    [Parsed_loudnorm_0 @ 0x...] <- empty line
+    {
+    \t"input_i" : "-21.75",
+    \t"input_tp" : "-18.06",
+    \t"input_lra" : "0.00",
+    \t"input_thresh" : "-31.75",
+    \t"output_i" : "-14.03",
+    ...
+    \t"target_offset" : "0.03"
+    }
+    Note: values are output as quoted strings. "-inf" may appear (silent input).
+
+  volumedetect:
+    [Parsed_volumedetect_0 @ 0x...] max_volume: -18.1 dB
+    Note: "max_volume: <VALUE> dB" format.
+
+When measurement is not possible, returns measured=None + warning
+(U-1 confirmed policy, DC-AM-003).
+ClipwrightError failures are propagated as-is.
+Absolute paths are never included in messages (fixed wording).
+"""
+
+from __future__ import annotations
+
+import json
+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_loudness.schemas import LoudnormMeasured, PeakMeasured
+
+# ffmpeg execution timeout (seconds).
+# Measurement-only passes (loudnorm 1-pass / volumedetect) complete much faster
+# than re-encoding, so 300 seconds is sufficient even for long-duration media.
+# Dynamic calculation is not needed.
+_TIMEOUT_SECONDS: float = 300.0
+
+
+def _parse_loudnorm_measured(stderr: str) -> dict[str, Any] | None:
+    """Extract measured values from the loudnorm print_format=json stderr JSON block.
+
+    ffmpeg writes a JSON block to stderr. Values are quoted strings.
+    If "-inf" / "inf" is present, LoudnormMeasured's allow_inf_nan=False causes
+    a ValidationError and None is returned (U-1).
+
+    Returns:
+        Dict of {input_i, input_tp, input_lra, input_thresh, target_offset},
+        or None if extraction fails.
+    """
+    # Collect all JSON block candidates ({ ... }) from stderr.
+    # re.search only matches the first occurrence, so if an earlier {} appears
+    # before the loudnorm JSON block it may be missed (H-1).
+    # Use re.findall to collect all candidates, then search in reverse for the
+    # last block containing all required_keys.
+    candidates = re.findall(r"\{[^{}]+\}", stderr, re.DOTALL)
+    if not candidates:
+        return None
+
+    required_keys = [
+        "input_i",
+        "input_tp",
+        "input_lra",
+        "input_thresh",
+        "target_offset",
+    ]
+
+    raw: dict[str, Any] | None = None
+    for block in reversed(candidates):
+        try:
+            parsed: dict[str, Any] = json.loads(block)
+        except json.JSONDecodeError:
+            continue
+        if all(k in parsed for k in required_keys):
+            raw = parsed
+            break
+
+    if raw is None:
+        return None
+
+    # Convert required fields from string to float
+    extracted: dict[str, Any] = {}
+    for key in required_keys:
+        val = raw[key]
+        try:
+            extracted[key] = float(val)
+        except (ValueError, TypeError):
+            return None
+
+    # Validate with LoudnormMeasured (inf/nan -> ValidationError -> degrade to None)
+    try:
+        validated = LoudnormMeasured(**extracted)
+    except ValidationError:
+        return None
+
+    return validated.model_dump()
+
+
+def _parse_volumedetect_measured(stderr: str) -> dict[str, Any] | None:
+    """Extract max_volume from volumedetect stderr.
+
+    Format: "[Parsed_volumedetect_0 @ 0x...] max_volume: -X.X dB"
+
+    Returns:
+        Dict of {max_volume_db: float}, or None if extraction fails.
+    """
+    m = re.search(r"max_volume:\s*(-?\d+\.?\d*)\s*dB", stderr)
+    if not m:
+        return None
+
+    try:
+        val = float(m.group(1))
+    except ValueError:
+        return None
+
+    # Validate with PeakMeasured (out-of-range -> ValidationError -> degrade to None)
+    try:
+        validated = PeakMeasured(max_volume_db=val)
+    except ValidationError:
+        return None
+
+    return validated.model_dump()
+
+
+def measure_loudness(
+    media: Path,
+    *,
+    mode: str,
+    target_i: float = -14.0,
+    target_tp: float = -1.0,
+    target_lra: float = 11.0,
+    target_peak_db: float = -1.0,
+) -> dict[str, Any]:
+    """Measure audio loudness of media and return the measured values (ADR-L1/L2/L7).
+
+    Args:
+        media: Path to the input media file (video + audio).
+        mode: "loudnorm" or "peak".
+        target_i: loudnorm integrated loudness target (LUFS).
+        target_tp: loudnorm true peak target (dBTP).
+        target_lra: loudnorm LRA target (LU).
+        target_peak_db: peak mode peak target (dB).
+
+    Returns:
+        {
+            "measured": dict | None,  # Mode-specific measured values.
+                                      # None means U-1 (not measurable).
+            "warnings": list[str],
+        }
+
+    Raises:
+        clipwright.errors.ClipwrightError:
+            DEPENDENCY_MISSING / SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT.
+    """
+    # Resolve ffmpeg binary (PATH-independent)
+    ffmpeg_bin = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+
+    warnings: list[str] = []
+
+    if mode == "loudnorm":
+        # Single-pass measurement with
+        # loudnorm=I=<I>:TP=<TP>:LRA=<LRA>:print_format=json (ADR-L1)
+        af_filter = (
+            f"loudnorm=I={target_i}:TP={target_tp}:LRA={target_lra}:print_format=json"
+        )
+        cmd: list[str] = [
+            ffmpeg_bin,
+            "-i",
+            str(media),
+            "-af",
+            af_filter,
+            "-f",
+            "null",
+            "-",
+        ]
+
+        try:
+            result = run(cmd, timeout=_TIMEOUT_SECONDS)
+        except ClipwrightError as exc:
+            # Prevent absolute paths from leaking into the error message from run().
+            # Preserve the ErrorCode and re-raise with fixed wording (CWE-209).
+            # Use "from None" to avoid chaining __cause__ (SR L-1).
+            raise ClipwrightError(
+                code=exc.code,
+                message="ffmpeg loudnorm command failed.",
+                hint="Check the ffmpeg version and arguments.",
+            ) from None
+        measured = _parse_loudnorm_measured(result.stderr)
+
+        if measured is None:
+            warnings.append(
+                "Could not retrieve loudnorm measured values."
+                " loudness directive will not be written (U-1, DC-AM-003)."
+                " ffmpeg stderr did not contain a valid loudnorm JSON block."
+            )
+
+        return {"measured": measured, "warnings": warnings}
+
+    else:
+        # mode == "peak": measure max_volume with volumedetect (ADR-L2)
+        cmd = [
+            ffmpeg_bin,
+            "-i",
+            str(media),
+            "-af",
+            "volumedetect",
+            "-f",
+            "null",
+            "-",
+        ]
+
+        try:
+            result = run(cmd, timeout=_TIMEOUT_SECONDS)
+        except ClipwrightError as exc:
+            # Use "from None" to avoid chaining __cause__ (SR L-1).
+            raise ClipwrightError(
+                code=exc.code,
+                message="ffmpeg volumedetect command failed.",
+                hint="Check the ffmpeg version and arguments.",
+            ) from None
+        measured = _parse_volumedetect_measured(result.stderr)
+
+        if measured is None:
+            warnings.append(
+                "Could not retrieve volumedetect measured values."
+                " loudness directive will not be written (U-1, DC-AM-003)."
+                " ffmpeg stderr did not contain a max_volume field."
+            )
+
+        return {"measured": measured, "warnings": warnings}

clipwright_loudness-0.1.1/src/clipwright_loudness/loudness.py

@@ -0,0 +1,471 @@
+"""loudness.py — clipwright-loudness orchestration layer (design §3.2, ADR-L4/L7).
+
+Flow:
+  1. Output validation (extension, parent dir, output==media,
+     output==timeline, same dir)
+  2. inspect_media: require both video and audio streams
+  3. Timeline resolution (None -> create new / path -> load + validate)
+  4. measure_loudness: measure loudness
+  5. If measured is None, skip loudness directive and emit warning
+     (U-1, DC-AM-003).
+     If measured is present, partial-update timeline-level metadata
+     with loudness directive.
+  6. save_timeline -> return ok_result
+
+Design decisions:
+- FILE_NOT_FOUND / message uses basename only (DC-GP-005).
+- output must be in the same directory as media (MUST, DC-AS-002).
+- output==media comparison uses Path.resolve() for normalization (B-4).
+- timeline validation: exactly one Video-kind track (B-5).
+- measured=None: skip loudness directive and return warning (U-1, DC-AM-003).
+- Mirrors _same_path / _add_full_clip / _load_and_validate_timeline
+  structure from noise.py.
+"""
+
+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
+from pydantic import ValidationError
+
+import clipwright_loudness
+from clipwright_loudness.analyze import measure_loudness
+from clipwright_loudness.schemas import (
+    DetectLoudnessOptions,
+    LoudnessDirective,
+    LoudnormMeasured,
+    LoudnormTarget,
+    PeakMeasured,
+    PeakTarget,
+)
+
+
+def detect_loudness(
+    media: str,
+    output: str,
+    options: DetectLoudnessOptions,
+    timeline: str | None,
+) -> dict[str, Any]:
+    """Public API for loudness detection. Converts ClipwrightError to ok=False envelope.
+
+    Args:
+        media: Input media file path (video + audio required).
+        output: Output OTIO timeline file path (.otio, same directory as media).
+        options: DetectLoudnessOptions.
+        timeline: Existing timeline path (None = create new).
+
+    Returns:
+        ok_result or error_result envelope dict.
+    """
+    try:
+        return _detect_loudness_inner(media, output, options, timeline)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _detect_loudness_inner(
+    media: str,
+    output: str,
+    options: DetectLoudnessOptions,
+    timeline: str | None,
+) -> dict[str, Any]:
+    """Internal implementation of detect_loudness. 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 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 (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=(
+                "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: require both video and audio ---
+
+    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.",
+        )
+
+    # 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:
+        # Create new: add 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. Loudness measurement ---
+
+    kwargs: dict[str, Any] = {}
+    if options.mode == "loudnorm":
+        kwargs = {
+            "target_i": options.target_i,
+            "target_tp": options.target_tp,
+            "target_lra": options.target_lra,
+        }
+    else:
+        kwargs = {"target_peak_db": options.target_peak_db}
+
+    analysis = measure_loudness(media_path, mode=options.mode, **kwargs)
+
+    measured_raw: dict[str, Any] | None = analysis["measured"]
+    warnings: list[str] = list(analysis["warnings"])
+
+    # --- 5. Partial-update timeline-level metadata with loudness directive ---
+    # (U-1: skip when measured is None)
+
+    if measured_raw is None:
+        # U-1: measurement not possible — skip directive and emit warning (DC-AM-003)
+        # analyze already added a warning, but loudness adds one as well
+        warnings.append(
+            "Could not retrieve loudness measured values."
+            " loudness directive will not be written (U-1)."
+        )
+    else:
+        # measured present — write loudness directive
+        if options.mode == "loudnorm":
+            target: LoudnormTarget | PeakTarget = LoudnormTarget(
+                i=options.target_i,
+                tp=options.target_tp,
+                lra=options.target_lra,
+            )
+            try:
+                measured_obj: LoudnormMeasured | PeakMeasured | None = LoudnormMeasured(
+                    **measured_raw
+                )
+            except ValidationError:
+                # CWE-209: do not expose ValidationError details externally
+                raise ClipwrightError(
+                    code=ErrorCode.INVALID_INPUT,
+                    message=(
+                        "Validation of loudnorm measured values failed."
+                        " Check field types."
+                    ),
+                    hint="Check the return value of measure_loudness.",
+                ) from None
+        else:
+            target = PeakTarget(peak_db=options.target_peak_db)
+            try:
+                measured_obj = PeakMeasured(**measured_raw)
+            except ValidationError:
+                # CWE-209: do not expose ValidationError details externally
+                raise ClipwrightError(
+                    code=ErrorCode.INVALID_INPUT,
+                    message=(
+                        "Validation of peak measured values failed. Check field types."
+                    ),
+                    hint="Check the return value of measure_loudness.",
+                ) from None
+
+        directive = LoudnessDirective(
+            tool="clipwright-loudness",
+            version=clipwright_loudness.__version__,
+            kind="loudness",
+            mode=options.mode,
+            scope="track",
+            target=target,
+            measured=measured_obj,
+        )
+
+        existing_meta = get_clipwright_metadata(tl)
+        existing_meta["loudness"] = directive.model_dump()
+        set_clipwright_metadata(tl, existing_meta)
+
+    # --- 6. save_timeline -> ok_result ---
+
+    save_timeline(tl, str(output_path))
+
+    if measured_raw is not None:
+        summary = (
+            f"Loudness analysis of {media_path.name} complete."
+            f" mode={options.mode}, scope={options.scope}."
+            f" loudness directive written to {output_path.name}."
+        )
+    else:
+        summary = (
+            f"Loudness analysis of {media_path.name} attempted"
+            " but measured values could not be retrieved."
+            f" mode={options.mode}, scope={options.scope}."
+            f" loudness directive was not written (U-1)."
+        )
+
+    return ok_result(
+        summary,
+        data={
+            "mode": options.mode,
+            "scope": options.scope,
+            "measured": measured_raw,
+        },
+        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:
+    """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())
+
+    # Determine rate: use duration if available, otherwise 1000.0.
+    # RationalTimeModel.rate is guaranteed to be float by the Pydantic schema,
+    # but gt=0 is not constrained, so zero-division is theoretically possible.
+    # However, OTIO RationalTime(duration_sec * rate, rate) initialization does
+    # not divide internally, so no crash occurs in practice.
+    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)
+
+    # Add 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 (B-4 / B-5).
+
+    Validates:
+    - The target_url of V1 clips matches media_path
+      (B-4: path normalization comparison)
+    - 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
+    (equivalent to new creation).
+
+    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 ---
+    clips = [item for item in v1 if isinstance(item, otio.schema.Clip)]
+
+    if not clips:
+        # V1 is empty — add full-length keep clip and continue
+        _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) ---
+    # Guard against malicious OTIO embedding arbitrary paths in target_url.
+    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.
+    Equivalent boundary check to _check_source_within_timeline_dir in render.py.
+
+    Args:
+        timeline_path: Path to the OTIO timeline file.
+        source: Media source path obtained from OTIO target_url.
+
+    Raises:
+        ClipwrightError: INVALID_INPUT (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(
+                # Use the same PATH_NOT_ALLOWED as render.py (SR-r2 L-1)
+                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:
+        # Skip on resolve() failure as a best-effort fallback.
+        # An invalid path will surface as INVALID_INPUT in the subsequent
+        # source==media comparison.
+        pass
+
+
+def _same_path(a: Path, b: Path) -> bool:
+    """Return True if both 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_loudness-0.1.1/src/clipwright_loudness/schemas.py

@@ -0,0 +1,251 @@
+"""schemas.py — clipwright-loudness Pydantic schemas.
+
+Common types (MediaRef / Artifact / ToolResult, etc.) are defined centrally
+in clipwright.schemas and are not redefined here.
+
+DetectLoudnessOptions: Input options for clipwright_detect_loudness.
+LoudnessDirective: Directive schema written to
+    timeline-level metadata["clipwright"]["loudness"].
+LoudnormTarget / PeakTarget: Normalization target values per mode.
+LoudnormMeasured / PeakMeasured: Measured values per mode.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class DetectLoudnessOptions(BaseModel):
+    """Options for clipwright_detect_loudness (design §3, ADR-L1/L2).
+
+    mode: loudnorm (EBU R128 LUFS normalization) or peak (peak dB normalization).
+    scope: track only (per_clip deferred per DC-AS-003).
+    target_i/target_tp/target_lra: loudnorm target values (overridable).
+    target_peak_db: peak target value (overridable).
+    """
+
+    mode: Annotated[
+        Literal["loudnorm", "peak"],
+        Field(
+            default="loudnorm",
+            description=(
+                "Loudness normalization mode. "
+                '"loudnorm" (default) applies EBU R128 LUFS normalization'
+                " (ffmpeg loudnorm). "
+                '"peak" applies peak dB normalization (ffmpeg volumedetect).'
+            ),
+        ),
+    ] = "loudnorm"
+
+    scope: Annotated[
+        Literal["track"],
+        Field(
+            default="track",
+            description=(
+                "Processing scope. "
+                '"track" (default) measures the entire timeline in a single pass. '
+                "per_clip is deferred per DC-AS-003."
+            ),
+        ),
+    ] = "track"
+
+    # loudnorm target parameters (design: I=-14/TP=-1/LRA=11)
+    target_i: Annotated[
+        float,
+        Field(
+            default=-14.0,
+            ge=-70.0,
+            le=-5.0,
+            description=(
+                "loudnorm integrated loudness target (LUFS)."
+                " Range [-70, -5]. Default -14."
+            ),
+        ),
+    ] = -14.0
+
+    target_tp: Annotated[
+        float,
+        Field(
+            default=-1.0,
+            ge=-9.0,
+            le=0.0,
+            description=(
+                "loudnorm true peak target (dBTP). Range [-9, 0]. Default -1."
+            ),
+        ),
+    ] = -1.0
+
+    target_lra: Annotated[
+        float,
+        Field(
+            default=11.0,
+            ge=1.0,
+            le=50.0,
+            description="loudnorm LRA target (LU). Range [1, 50]. Default 11.",
+        ),
+    ] = 11.0
+
+    # peak target parameters
+    target_peak_db: Annotated[
+        float,
+        Field(
+            default=-1.0,
+            ge=-60.0,
+            le=0.0,
+            description="Peak mode peak target (dB). Range [-60, 0]. Default -1.",
+        ),
+    ] = -1.0
+
+
+class LoudnormTarget(BaseModel):
+    """Normalization target values for loudnorm mode (ADR-L4).
+
+    Also independently redefined on the render side in plan.py
+    (NR-M-1 lesson: no dependency on clipwright_loudness).
+    """
+
+    i: Annotated[
+        float,
+        Field(
+            default=-14.0,
+            ge=-70.0,
+            le=-5.0,
+            description="Integrated loudness target (LUFS). Range [-70, -5].",
+        ),
+    ] = -14.0
+
+    tp: Annotated[
+        float,
+        Field(
+            default=-1.0,
+            ge=-9.0,
+            le=0.0,
+            description="True peak target (dBTP). Range [-9, 0].",
+        ),
+    ] = -1.0
+
+    lra: Annotated[
+        float,
+        Field(
+            default=11.0,
+            ge=1.0,
+            le=50.0,
+            description="LRA target (LU). Range [1, 50].",
+        ),
+    ] = 11.0
+
+
+class PeakTarget(BaseModel):
+    """Normalization target values for peak mode (ADR-L4)."""
+
+    peak_db: Annotated[
+        float,
+        Field(
+            default=-1.0,
+            ge=-60.0,
+            le=0.0,
+            allow_inf_nan=False,
+            description="Peak target (dB). Range [-60, 0]. inf/nan not allowed.",
+        ),
+    ] = -1.0
+
+
+class LoudnormMeasured(BaseModel):
+    """Measured values output by the loudnorm filter (ADR-L1).
+
+    Five values extracted from the JSON block at the end of ffmpeg
+    loudnorm=print_format=json stderr.
+    When the input is silent, "-inf" may be returned; in that case
+    allow_inf_nan=False causes a ValidationError and the caller treats
+    measured=None (U-1).
+    """
+
+    input_i: Annotated[
+        float,
+        Field(
+            allow_inf_nan=False,
+            description="Input integrated loudness (LUFS). inf/nan not allowed.",
+        ),
+    ]
+
+    input_tp: Annotated[
+        float,
+        Field(
+            allow_inf_nan=False,
+            description="Input true peak (dBTP). inf/nan not allowed.",
+        ),
+    ]
+
+    input_lra: Annotated[
+        float,
+        Field(
+            allow_inf_nan=False,
+            description="Input LRA (LU). inf/nan not allowed.",
+        ),
+    ]
+
+    input_thresh: Annotated[
+        float,
+        Field(
+            allow_inf_nan=False,
+            description="Input threshold (LUFS). inf/nan not allowed.",
+        ),
+    ]
+
+    target_offset: Annotated[
+        float,
+        Field(
+            allow_inf_nan=False,
+            description="Target offset (LU). inf/nan not allowed.",
+        ),
+    ]
+
+
+class PeakMeasured(BaseModel):
+    """Measured values output by the volumedetect filter (ADR-L2).
+
+    Value extracted from "max_volume: -X.X dB" in ffmpeg volumedetect stderr.
+    """
+
+    max_volume_db: Annotated[
+        float,
+        Field(
+            ge=-200.0,
+            le=0.0,
+            allow_inf_nan=False,
+            description="Maximum volume (dB). Range [-200, 0]. inf/nan not allowed.",
+        ),
+    ]
+
+
+class LoudnessDirective(BaseModel):
+    """Loudness directive schema written to timeline-level metadata
+    (design §3.2, ADR-L4).
+
+    Generated by loudness and read/validated by render.
+    scope is track only (per_clip deferred per DC-AS-003).
+    target is discriminated by mode (LoudnormTarget or PeakTarget).
+    measured holds mode-specific measured values or None (U-1: when measurement fails).
+    """
+
+    tool: Annotated[str, Field(max_length=64)]
+    version: Annotated[str, Field(max_length=64)]
+    kind: Literal["loudness"]
+    mode: Literal["loudnorm", "peak"]
+    scope: Literal["track"]
+    target: LoudnormTarget | PeakTarget
+    measured: LoudnormMeasured | PeakMeasured | None = None
+
+    @model_validator(mode="after")
+    def _validate_target_mode_consistency(self) -> LoudnessDirective:
+        """Validate that the target type is consistent with mode.
+
+        mode=loudnorm requires LoudnormTarget; mode=peak requires PeakTarget.
+        """
+        if self.mode == "loudnorm" and not isinstance(self.target, LoudnormTarget):
+            raise ValueError("When mode=loudnorm, target must be LoudnormTarget.")
+        if self.mode == "peak" and not isinstance(self.target, PeakTarget):
+            raise ValueError("When mode=peak, target must be PeakTarget.")
+        return self

clipwright_loudness-0.1.1/src/clipwright_loudness/server.py

@@ -0,0 +1,108 @@
+"""server.py — clipwright-loudness MCP server + CLI entry point.
+
+Thin wrapper that delegates business logic to loudness.py.
+ClipwrightError conversion is handled in loudness.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_loudness.loudness import detect_loudness
+from clipwright_loudness.schemas import DetectLoudnessOptions
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-loudness")
+
+
+# ===========================================================================
+# clipwright_detect_loudness MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_detect_loudness(
+    media: Annotated[
+        str,
+        Field(description="Input media file path (must contain both 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[
+        DetectLoudnessOptions | None,
+        Field(
+            description=(
+                "Loudness detection options (mode / scope / target, etc.). "
+                "Defaults to mode=loudnorm / scope=track /"
+                " I=-14 / TP=-1 / LRA=11 when omitted."
+            )
+        ),
+    ] = None,
+    timeline: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Existing OTIO timeline file path. "
+                "When specified, the loudness directive is appended to that timeline. "
+                "A new timeline is created when omitted."
+            )
+        ),
+    ] = None,
+) -> dict[str, Any]:
+    """Analyze audio loudness and generate an OTIO timeline with a loudness directive.
+
+    The input media file is never modified (non-destructive, readOnly).
+    readOnlyHint=True means "the input media is not changed"; the .otio file
+    specified in output is newly created (outside the readOnly scope).
+    Measures loudness with ffmpeg loudnorm/volumedetect and writes the loudness
+    directive to timeline-level metadata["clipwright"]["loudness"].
+    Returns the path of the resulting timeline.otio in artifacts.
+
+    Delegates business logic to loudness.detect_loudness.
+    Uses default DetectLoudnessOptions() when options is None.
+    """
+    resolved_options = options if options is not None else DetectLoudnessOptions()
+    return detect_loudness(
+        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-loudness = "clipwright_loudness.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()