clipwright-silence 0.1.0__tar.gz

clipwright_silence-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.3
+Name: clipwright-silence
+Version: 0.1.0
+Summary: MCP tool for silence detection and OTIO timeline generation. Detects silence with ffmpeg silencedetect and generates timeline.otio with clip sequence for regions to keep.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.1.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: opentimelineio>=0.18
+Requires-Dist: pydantic>=2
+Requires-Dist: silero-vad>=5.1 ; extra == 'vad'
+Requires-Dist: onnxruntime>=1.17 ; extra == 'vad'
+Requires-Dist: numpy>=1.24 ; extra == 'vad'
+Requires-Python: >=3.11
+Provides-Extra: vad
+Description-Content-Type: text/markdown
+
+# clipwright-silence
+
+MCP tool for silence detection and OTIO timeline generation.

clipwright_silence-0.1.0/README.md

@@ -0,0 +1,3 @@
+# clipwright-silence
+
+MCP tool for silence detection and OTIO timeline generation.

clipwright_silence-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "clipwright-silence"
+version = "0.1.0"
+description = "MCP tool for silence detection and OTIO timeline generation. Detects silence with ffmpeg silencedetect and generates timeline.otio with clip sequence for regions to keep."
+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.0",
+    "mcp[cli]>=1.27.2",
+    "opentimelineio>=0.18",
+    "pydantic>=2",
+]
+
+[project.optional-dependencies]
+vad = [
+    "silero-vad>=5.1",
+    "onnxruntime>=1.17",
+    # numpy is a transitive dependency of onnxruntime, but explicitly listed to pin minimum version
+    "numpy>=1.24",
+]
+
+[project.scripts]
+clipwright-silence = "clipwright_silence.server:main"
+clipwright-silence-vad = "clipwright_silence.vad_cli: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
+
+# silero-vad / onnxruntime have no stubs, ignored as VAD is optional extra
+[[tool.mypy.overrides]]
+module = "silero_vad.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "onnxruntime.*"
+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",
+]
+
+# --- coverage ---
+[tool.coverage.run]
+source = ["clipwright_silence"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_silence-0.1.0/src/clipwright_silence/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-silence: silence detection → OTIO timeline generation MCP tool."""
+
+__version__ = "0.1.0"

clipwright_silence-0.1.0/src/clipwright_silence/detect.py

@@ -0,0 +1,523 @@
+"""detect.py — clipwright-silence orchestration layer.
+
+Handles the full flow: input validation -> inspect_media -> silencedetect
+execution/parsing -> KEEP derivation -> OTIO construction/save -> envelope return.
+
+Design decisions:
+- _detect_silence_intervals() encapsulates ffmpeg execution and stderr parsing,
+  allowing future backend replacement (adapter abstraction, AD-1).
+- _detect_vad_silence_intervals() handles spawning the VAD CLI as a separate
+  process and inverting speech -> silence. Both return (silence interval list)
+  with a common contract so derive_keep_ranges onward uses a shared flow.
+- source_range rate is taken from inspect_media MediaInfo.duration.rate,
+  and value = seconds * rate (DC-AS-003).
+- output is only permitted in the same directory as media (DC-AS-001).
+- Error messages do not expose full paths or raw ffmpeg stderr (basename only, M-1).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+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 add_clip, new_timeline, save_timeline
+from clipwright.process import resolve_tool, run
+from clipwright.schemas import MediaRef, RationalTimeModel, TimeRangeModel
+
+import clipwright_silence
+from clipwright_silence.plan import derive_keep_ranges
+from clipwright_silence.schemas import DetectSilenceOptions
+
+# Regex to extract silence_start / silence_end lines
+# (DC-AM-003: line-start match, '.' fixed decimal)
+_RE_SILENCE_START = re.compile(r"silence_start:\s*([0-9]+(?:\.[0-9]+)?)")
+_RE_SILENCE_END = re.compile(r"silence_end:\s*([0-9]+(?:\.[0-9]+)?)")
+
+
+def _fmt_sec(sec: float) -> str:
+    """Convert seconds to a human-readable minutes/seconds string (for summary).
+
+    Format examples: 90.0 -> "1m30.0s", 45.5 -> "45.5s"
+    """
+    m = int(sec) // 60
+    s = sec - m * 60
+    return f"{m}m{s:.1f}s" if m > 0 else f"{s:.1f}s"
+
+
+def _parse_silence_intervals(
+    stderr: str,
+    total_duration_sec: float,
+) -> list[tuple[float, float]]:
+    """Extract silence interval list from silencedetect stderr.
+
+    Parses line by line using a line-start match regex with fixed '.'
+    decimal (DC-AM-003). A trailing silence_start with no matching
+    silence_end is completed using
+    total_duration_sec (DC-AM-002).
+
+    Args:
+        stderr: ffmpeg standard error output string.
+        total_duration_sec: Total duration of the source (seconds). Used for completion.
+
+    Returns:
+        List of silence intervals. Each element is a (start_sec, end_sec) tuple.
+    """
+    intervals: list[tuple[float, float]] = []
+    pending_start: float | None = None
+
+    for line in stderr.splitlines():
+        m_start = _RE_SILENCE_START.search(line)
+        if m_start:
+            pending_start = float(m_start.group(1))
+            continue
+
+        m_end = _RE_SILENCE_END.search(line)
+        # An isolated silence_end does not occur in normal silencedetect output
+        # (start->end are always paired). If encountered, skip as abnormal output.
+        # This is an intentional ignore per silencedetect spec, not suppression.
+        if m_end and pending_start is not None:
+            end = float(m_end.group(1))
+            # SR L-3: skip abnormal intervals where end < start
+            # (defensive check for future backend replacement)
+            if end < pending_start:
+                pending_start = None
+                continue
+            intervals.append((pending_start, end))
+            pending_start = None
+
+    # Trailing silence_end missing -> complete with total_duration (DC-AM-002)
+    if pending_start is not None:
+        intervals.append((pending_start, total_duration_sec))
+
+    return intervals
+
+
+def _detect_silence_intervals(
+    ffmpeg: str,
+    source: str,
+    options: DetectSilenceOptions,
+    total_duration_sec: float,
+) -> list[tuple[float, float]]:
+    """Run ffmpeg silencedetect and return a list of silence intervals.
+
+    Adapter abstraction (AD-1).
+
+    When replacing the backend in the future, only this function needs to be swapped.
+
+    Args:
+        ffmpeg: Path to ffmpeg executable.
+        source: Input media file path.
+        options: DetectSilenceOptions.
+        total_duration_sec: Total duration of source (seconds).
+            Used for trailing completion.
+
+    Returns:
+        List of silence intervals. Each element is (start_sec, end_sec).
+
+    Raises:
+        ClipwrightError: SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT (raised by run).
+    """
+    # Filter string uses explicit format to be locale-independent (DC-AM-003)
+    filter_str = (
+        f"silencedetect=noise={options.silence_threshold_db:.3f}dB"
+        f":d={options.min_silence_duration:.6f}"
+    )
+    timeout = max(60, math.ceil(total_duration_sec * 2))
+
+    cmd = [
+        ffmpeg,
+        "-hide_banner",
+        "-nostats",
+        "-i",
+        source,
+        "-af",
+        filter_str,
+        "-f",
+        "null",
+        "-",
+    ]
+    result = run(cmd, timeout=float(timeout))
+    return _parse_silence_intervals(result.stderr, total_duration_sec)
+
+
+def _detect_vad_silence_intervals(
+    source: str,
+    options: DetectSilenceOptions,
+    total_duration_sec: float,
+) -> tuple[list[tuple[float, float]], int]:
+    """Spawn VAD CLI as a separate process; return silence intervals and speech_count.
+
+    VAD-AD-02/04: Inverts the speech intervals returned by the VAD CLI against
+    total_duration_sec to produce silence intervals. speech_count is used only
+    for VAD summary generation and is not passed to the common flow (§7.5).
+
+    Args:
+        source: Absolute path to the input media file.
+        options: DetectSilenceOptions (references vad_* fields).
+        total_duration_sec: Total duration of source (seconds). Used for inversion.
+
+    Returns:
+        Tuple of (silence interval list, speech_count).
+
+    Raises:
+        ClipwrightError: Maps VAD CLI error JSON to corresponding ErrorCode.
+                         SUBPROCESS_FAILED if run() exits non-zero.
+    """
+    timeout = float(max(60, math.ceil(total_duration_sec * 4)))
+    cmd = [
+        sys.executable,
+        "-m",
+        "clipwright_silence.vad_cli",
+        "--media",
+        source,
+        "--threshold",
+        f"{options.vad_threshold}",
+        "--min-speech",
+        f"{options.vad_min_speech_duration}",
+        "--min-silence",
+        f"{options.vad_min_silence_duration}",
+        "--media-duration",
+        # vad_cli uses ceil(total*2); float precision has no practical impact (NF-L-1)
+        f"{total_duration_sec}",
+    ]
+    result = run(cmd, timeout=timeout)
+
+    try:
+        payload: dict[str, Any] = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise ClipwrightError(
+            code=ErrorCode.SUBPROCESS_FAILED,
+            message="VAD CLI returned invalid JSON output",
+            hint=(
+                "VAD CLI did not return the expected JSON. "
+                "If the error persists, please report with reproduction steps."
+            ),
+        ) from exc
+
+    # If error JSON, map to ErrorCode and raise ClipwrightError (§7.1)
+    if "error" in payload:
+        err = payload["error"]
+        raw_code: str = err.get("code", "INTERNAL")
+        message: str = err.get("message", "An error occurred in VAD CLI")
+        hint: str = err.get("hint", "Please report with reproduction steps.")
+
+        # Map to known ErrorCode; fall back to SUBPROCESS_FAILED for unknown codes
+        try:
+            error_code = ErrorCode(raw_code)
+        except ValueError:
+            error_code = ErrorCode.SUBPROCESS_FAILED
+
+        raise ClipwrightError(code=error_code, message=message, hint=hint)
+
+    # Pre-process speech intervals (§7.4): clip and remove degenerate intervals
+    raw_segments: list[dict[str, Any]] = payload.get("speech_segments", [])
+    total = total_duration_sec
+    speech_segments: list[tuple[float, float]] = []
+    for seg in raw_segments:
+        try:
+            # Accept both dict {"start": ..., "end": ...} and list [start, end] formats
+            if isinstance(seg, (list, tuple)):
+                start, end = float(seg[0]), float(seg[1])
+            else:
+                start, end = float(seg["start"]), float(seg["end"])
+        except (TypeError, KeyError, ValueError, IndexError):
+            # Skip malformed elements (null/string/empty dict, etc.) — SR L-3
+            continue
+        # Clip start < 0 to 0, clip end > total to total
+        start = max(0.0, start)
+        end = min(total, end)
+        # Remove degenerate intervals (start >= end)
+        if start >= end:
+            continue
+        speech_segments.append((start, end))
+
+    speech_count = len(speech_segments)
+
+    # Invert speech intervals -> silence intervals (VAD-AD-04)
+    # Sort speech intervals ascending and take the complement of [0, total]
+    sorted_speech = sorted(speech_segments, key=lambda iv: iv[0])
+    silence_intervals: list[tuple[float, float]] = []
+    cursor = 0.0
+    for s_start, s_end in sorted_speech:
+        if s_start > cursor:
+            silence_intervals.append((cursor, s_start))
+        cursor = max(cursor, s_end)
+    if cursor < total:
+        silence_intervals.append((cursor, total))
+
+    return silence_intervals, speech_count
+
+
+def detect_silence(
+    media: str,
+    output: str,
+    options: DetectSilenceOptions,
+) -> dict[str, Any]:
+    """Detect silence intervals and generate a KEEP interval OTIO timeline (AD-2/AD-5).
+
+    Non-destructive: does not modify the input media file in any way.
+    Output returns the path of the newly created timeline.otio in artifacts.
+
+    Flow:
+      1. Output validation (extension, parent directory, output==media, same directory)
+      2. inspect_media -> verify audio/video streams and duration
+      3. Run ffmpeg silencedetect and parse stderr
+      4. Derive KEEP intervals with derive_keep_ranges
+      5. Build and save OTIO timeline
+      6. Return envelope
+
+    Args:
+        media: Input media file path.
+        output: Output timeline.otio file path (must be in the same directory as media).
+        options: DetectSilenceOptions.
+
+    Returns:
+        Envelope dict from ok_result or error_result.
+    """
+    try:
+        return _detect_inner(media, output, options)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _detect_inner(
+    media: str,
+    output: str,
+    options: DetectSilenceOptions,
+) -> dict[str, Any]:
+    """Internal implementation of detect_silence. Raises ClipwrightError directly."""
+    output_path = Path(output)
+    media_path = Path(media)
+
+    # --- 1. Output validation ---
+
+    # Extension must be .otio (AD-5)
+    if output_path.suffix.lower() != ".otio":
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                f"Invalid output file extension: {output_path.suffix!r}. "
+                "Only .otio is allowed."
+            ),
+            hint="Change the output file path extension to .otio.",
+        )
+
+    # Verify parent directory exists (no auto-creation, AD-5)
+    if not output_path.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                "The output directory does not exist. "
+                "Check the parent directory of the specified output path."
+            ),
+            hint="Create the output directory first, then re-run.",
+        )
+
+    # Prevent output == media (avoid overwriting the same path)
+    try:
+        if output_path.resolve() == media_path.resolve():
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="The output path and input media path are identical.",
+                hint=(
+                    "Change the output file path to a path"
+                    " different from the input media."
+                ),
+            )
+    except OSError as exc:
+        if str(output_path) == str(media_path):
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="The output path and input media path are identical.",
+                hint=(
+                    "Change the output file path to a path"
+                    " different from the input media."
+                ),
+            ) from exc
+
+    # --- 2. inspect_media -> verify streams and duration ---
+
+    # inspect_media raises FILE_NOT_FOUND (incl. symlink rejection) / PROBE_FAILED, etc.
+    # SR L-2: Replace FILE_NOT_FOUND message with basename only
+    # (prevents full path exposure; same policy as render._probe M-1).
+    try:
+        media_info = inspect_media(media)
+    except ClipwrightError as exc:
+        if exc.code == ErrorCode.FILE_NOT_FOUND:
+            raise ClipwrightError(
+                code=ErrorCode.FILE_NOT_FOUND,
+                message=f"File not found: {media_path.name}",
+                hint=exc.hint,
+            ) from exc
+        raise
+
+    # Verify output is in the same directory as media (DC-AS-001)
+    # Done after inspect_media so the path has been confirmed to exist before resolve()
+    try:
+        media_dir = media_path.resolve().parent
+        output_dir = output_path.parent.resolve()
+        if media_dir != output_dir:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message=(
+                    "The output timeline must be placed in the same"
+                    f" directory as the input media (input: {media_path.name})."
+                ),
+                hint=(
+                    "Change the output path to be in the same directory"
+                    " as the media file."
+                    " (e.g., output = same directory as media / timeline.otio)"
+                ),
+            )
+    except ClipwrightError:
+        raise
+    except OSError:
+        # resolve failure (network paths, etc.) is skipped on best-effort basis
+        pass
+
+    # Verify video stream (DC-AS-002)
+    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=(
+                "This tool targets media with both video and audio streams. "
+                "Specify a media file that contains video."
+            ),
+        )
+
+    if not has_audio:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message=f"No audio stream found: {media_path.name}",
+            hint=(
+                "Silence detection requires an audio stream. "
+                "Specify a media file that contains audio."
+            ),
+        )
+
+    # Verify duration (DC-AS-004)
+    if media_info.duration is None:
+        raise ClipwrightError(
+            code=ErrorCode.PROBE_FAILED,
+            message=f"Could not retrieve media duration: {media_path.name}",
+            hint=(
+                "Check that the media file is not corrupted. "
+                "You can also verify manually with ffprobe."
+            ),
+        )
+
+    total_duration_sec = media_info.duration.value / media_info.duration.rate
+    rate = media_info.duration.rate
+
+    # --- 3. Run detection (branch by backend) ---
+
+    abs_media = str(media_path.resolve())
+
+    # speech_count is for VAD summary only; silence interval list is shared
+    speech_count: int | None = None
+
+    if options.backend == "vad":
+        # VAD path: spawn as separate process via sys.executable -m
+        # resolve_tool is not used (sys.executable -m ensures same venv, VAD-AD-02)
+        silence_intervals, speech_count = _detect_vad_silence_intervals(
+            abs_media, options, total_duration_sec
+        )
+    else:
+        # silencedetect path (existing; backend="silencedetect")
+        ffmpeg = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+        silence_intervals = _detect_silence_intervals(
+            ffmpeg, abs_media, options, total_duration_sec
+        )
+
+    # --- 4. Derive KEEP intervals ---
+
+    keep_ranges = derive_keep_ranges(total_duration_sec, silence_intervals, options)
+
+    # --- 5. Build and save OTIO timeline ---
+
+    timeline = new_timeline(media_path.name)
+    v1 = timeline.tracks[0]  # V1 (Video) track
+
+    for start_sec, end_sec in keep_ranges:
+        start_value = start_sec * rate
+        dur_value = (end_sec - start_sec) * rate
+        source_range = TimeRangeModel(
+            start_time=RationalTimeModel(value=start_value, rate=rate),
+            duration=RationalTimeModel(value=dur_value, rate=rate),
+        )
+        media_ref = MediaRef(target_url=abs_media)
+        add_clip(
+            v1,
+            media_ref,
+            source_range,
+            name="keep",
+            metadata={
+                "tool": "clipwright-silence",
+                "version": clipwright_silence.__version__,
+                "kind": "keep",
+                "backend": options.backend,  # VAD-AD-07
+            },
+        )
+
+    save_timeline(timeline, output)
+
+    # --- 6. Return envelope ---
+
+    silence_count = len(silence_intervals)
+    keep_count = len(keep_ranges)
+    total_silence_seconds = sum(e - s for s, e in silence_intervals)
+    total_keep_seconds = sum(e - s for s, e in keep_ranges)
+
+    # Differentiate summary by backend (VAD-AD-08, §7.5)
+    # In the VAD path, _detect_vad_silence_intervals always returns an int,
+    # so speech_count is guaranteed to be int (assert to satisfy mypy)
+    if options.backend == "vad":
+        assert speech_count is not None  # Always set on the VAD path
+        _silence_fmt = _fmt_sec(total_silence_seconds)
+        _keep_fmt = _fmt_sec(total_keep_seconds)
+        summary = (
+            f"Detected {speech_count} speech interval(s). "
+            f"Removed {silence_count} non-speech interval(s) (total {_silence_fmt}). "
+            f"Generated {output_path.name} with {keep_count} interval(s) to keep"
+            f" (total {_keep_fmt})."
+        )
+    else:
+        _silence_fmt = _fmt_sec(total_silence_seconds)
+        _keep_fmt = _fmt_sec(total_keep_seconds)
+        summary = (
+            f"Detected {silence_count} silence interval(s) (total {_silence_fmt})"
+            f" from source with duration {_fmt_sec(total_duration_sec)}. "
+            f"Generated {output_path.name} with {keep_count} interval(s) to keep"
+            f" (total {_keep_fmt})."
+        )
+
+    warnings: list[str] = []
+    if keep_count == 0:
+        warnings.append(
+            "No intervals to keep (all intervals classified as silence). "
+            "The V1 track of the generated timeline.otio is empty. "
+            "Passing it to render will result in INVALID_INPUT."
+        )
+
+    return ok_result(
+        summary,
+        data={
+            "silence_count": silence_count,
+            "total_silence_seconds": total_silence_seconds,
+            "keep_count": keep_count,
+            "total_keep_seconds": total_keep_seconds,
+        },
+        artifacts=[{"role": "timeline", "path": str(output_path), "format": "otio"}],
+        warnings=warnings,
+    )

clipwright_silence-0.1.0/src/clipwright_silence/plan.py

@@ -0,0 +1,107 @@
+"""plan.py — Pure logic for deriving KEEP intervals from silence intervals.
+
+Does not execute ffmpeg at all. Performs interval arithmetic on float seconds
+and delegates OTIO conversion to the detect layer (AD-2/AD-3 design policy).
+"""
+
+from __future__ import annotations
+
+from clipwright_silence.schemas import DetectSilenceOptions
+
+# CR-Q-004: Floating-point comparison tolerance. Used to preserve boundary
+# equality (DC-AM-001: min_keep equal preservation / _merge_intervals adjacent merging).
+_EPSILON = 1e-9
+
+
+def derive_keep_ranges(
+    total_duration_sec: float,
+    silence_intervals: list[tuple[float, float]],
+    options: DetectSilenceOptions,
+) -> list[tuple[float, float]]:
+    """Derive KEEP intervals from a list of silence intervals.
+
+    Processing flow (AD-3):
+    1. Sort silence intervals by start time.
+    2. Invert [0, total_duration_sec] against silence intervals to get KEEP intervals.
+       - Zero silence -> [(0.0, total_duration_sec)] as a single interval.
+       - All silence -> empty list.
+    3. Extend each KEEP by padding and clamp to [0, total].
+    4. Merge overlapping KEEPs (DC-GP-001 short-silence fill-in).
+    5. Discard intervals shorter than min_keep_duration (DC-AM-001 opt-in).
+
+    Args:
+        total_duration_sec: Total duration of the source media (seconds).
+        silence_intervals: List of silence intervals. Each element is
+            (start_sec, end_sec).
+        options: DetectSilenceOptions. Uses padding / min_keep_duration.
+                 (silence_threshold_db / min_silence_duration are the silencedetect
+                 layer's responsibility and are not referenced in this function.)
+
+    Returns:
+        List of KEEP intervals. Each element is a tuple[float, float]
+        of (start_sec, end_sec).
+        Sorted by time, non-overlapping.
+    """
+    total = total_duration_sec
+    padding = options.padding
+    min_keep = options.min_keep_duration
+
+    # 1. Sort silence intervals.
+    sorted_silence = sorted(silence_intervals, key=lambda iv: iv[0])
+
+    # 2. Invert: subtract silence intervals from [0, total] to get KEEPs.
+    keeps: list[tuple[float, float]] = []
+    cursor = 0.0
+    for s_start, s_end in sorted_silence:
+        if s_start > cursor:
+            keeps.append((cursor, s_start))
+        # Advance cursor to end of silence (handles overlapping silences).
+        cursor = max(cursor, s_end)
+    # Trailing speech interval.
+    if cursor < total:
+        keeps.append((cursor, total))
+
+    # 3. Padding extension + clamp.
+    if padding > 0.0:
+        padded: list[tuple[float, float]] = []
+        for start, end in keeps:
+            new_start = max(0.0, start - padding)
+            new_end = min(total, end + padding)
+            padded.append((new_start, new_end))
+        keeps = padded
+
+    # 4. Merge overlapping intervals (DC-GP-001).
+    keeps = _merge_intervals(keeps)
+
+    # 5. Discard intervals shorter than min_keep_duration (default 0.0 = no discard).
+    if min_keep > 0.0:
+        # DC-AM-001: Use _EPSILON to preserve intervals equal to min_keep
+        keeps = [
+            (start, end) for start, end in keeps if (end - start) >= min_keep - _EPSILON
+        ]
+
+    return keeps
+
+
+def _merge_intervals(
+    intervals: list[tuple[float, float]],
+) -> list[tuple[float, float]]:
+    """Merge overlapping intervals and return a sorted, non-overlapping list.
+
+    Intervals do not need to be pre-sorted by start time (sorted internally).
+    """
+    if not intervals:
+        return []
+
+    sorted_ivs = sorted(intervals, key=lambda iv: iv[0])
+    merged: list[tuple[float, float]] = [sorted_ivs[0]]
+
+    for start, end in sorted_ivs[1:]:
+        prev_start, prev_end = merged[-1]
+        if start <= prev_end + _EPSILON:
+            # Overlapping or adjacent -> merge.
+            merged[-1] = (prev_start, max(prev_end, end))
+        else:
+            merged.append((start, end))
+
+    return merged

clipwright_silence-0.1.0/src/clipwright_silence/schemas.py

@@ -0,0 +1,128 @@
+"""schemas.py — clipwright-silence specific Pydantic schemas.
+
+Common types (MediaRef / Artifact / ToolResult, etc.) are centrally defined
+in clipwright.schemas and are not redefined in this module.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class DetectSilenceOptions(BaseModel):
+    """Options for clipwright_detect_silence (AD-2/AD-3, DC-AM-001).
+
+    silence_threshold_db and min_silence_duration are detection parameters
+    passed directly to the ffmpeg silencedetect filter.
+    padding and min_keep_duration are post-processing parameters used by
+    the KEEP derivation logic in plan.py.
+    vad_* fields are only effective when backend="vad" (VAD-AD-05).
+    """
+
+    silence_threshold_db: Annotated[
+        float,
+        Field(
+            default=-30.0,
+            le=0.0,
+            description=(
+                "silencedetect backend only. Use vad_* when using VAD. "
+                "Volume threshold (dB) for silence detection. Must be <= 0. "
+                "Example: -30.0 dB (default), -40.0 dB (stricter detection)."
+            ),
+        ),
+    ] = -30.0
+
+    min_silence_duration: Annotated[
+        float,
+        Field(
+            default=0.5,
+            gt=0.0,
+            description=(
+                "silencedetect backend only. Use vad_* when using VAD. "
+                "Minimum duration (seconds) to consider as silence. Must be > 0. "
+                "Silences shorter than this value are ignored. Default is 0.5 seconds."
+            ),
+        ),
+    ] = 0.5
+
+    padding: Annotated[
+        float,
+        Field(
+            default=0.1,
+            ge=0.0,
+            description=(
+                "Padding width (seconds) to extend each KEEP interval on both sides."
+                " Must be >= 0. If extension causes adjacent KEEPs to overlap,"
+                " they are merged (prevents word cutoff). Default is 0.1 seconds."
+            ),
+        ),
+    ] = 0.1
+
+    min_keep_duration: Annotated[
+        float,
+        Field(
+            default=0.0,
+            ge=0.0,
+            description=(
+                "Minimum interval length (seconds) to retain as KEEP. Must be >= 0."
+                " KEEP intervals shorter than this value are discarded after"
+                " padding and merging."
+                " Default is 0.0 (no discard; DC-AM-001 opt-in guard)."
+            ),
+        ),
+    ] = 0.0
+
+    backend: Annotated[
+        Literal["silencedetect", "vad"],
+        Field(
+            default="silencedetect",
+            description=(
+                "Detection backend to use. "
+                '"silencedetect" (default) uses the ffmpeg silencedetect filter. '
+                '"vad" uses Silero VAD (ONNX). VAD-AD-01 backward-compatible opt-in.'
+            ),
+        ),
+    ] = "silencedetect"
+
+    vad_threshold: Annotated[
+        float,
+        Field(
+            default=0.5,
+            ge=0.0,
+            le=1.0,
+            description=(
+                "VAD backend only. "
+                "Speech probability threshold (0.0-1.0)."
+                " Values >= this are considered speech. Default is 0.5."
+            ),
+        ),
+    ] = 0.5
+
+    vad_min_speech_duration: Annotated[
+        float,
+        Field(
+            default=0.25,
+            gt=0.0,
+            description=(
+                "VAD backend only. "
+                "Minimum duration (seconds) to classify as speech. Must be > 0. "
+                "Default is 0.25 seconds."
+            ),
+        ),
+    ] = 0.25
+
+    vad_min_silence_duration: Annotated[
+        float,
+        Field(
+            default=0.1,
+            gt=0.0,
+            description=(
+                "VAD backend only. "
+                "Minimum silence duration (seconds) between speech intervals."
+                " Must be > 0. Silences shorter than this value are absorbed"
+                " into speech intervals. Default is 0.1 seconds."
+            ),
+        ),
+    ] = 0.1

clipwright_silence-0.1.0/src/clipwright_silence/server.py

@@ -0,0 +1,88 @@
+"""server.py — clipwright-silence MCP server + CLI entry point.
+
+A thin wrapper that delegates business logic to detect.py.
+ClipwrightError conversion is handled on the detect.py side;
+no double conversion is done 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_silence.detect import detect_silence
+from clipwright_silence.schemas import DetectSilenceOptions
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-silence")
+
+
+# ===========================================================================
+# clipwright_detect_silence MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_detect_silence(
+    media: Annotated[
+        str,
+        Field(description="Input media file path (source containing video and audio)."),
+    ],
+    output: Annotated[
+        str,
+        Field(description="Output OTIO timeline file path (.otio extension)."),
+    ],
+    options: Annotated[
+        DetectSilenceOptions | None,
+        Field(
+            description=(
+                "Silence detection options (silence_threshold_db / min_silence_duration"
+                " / padding / min_keep_duration). All values use defaults when omitted."
+            )
+        ),
+    ] = None,
+) -> dict[str, Any]:
+    """MCP tool: detect silence intervals and generate a KEEP interval OTIO timeline.
+
+    Does not modify the input media file (non-destructive, readOnly).
+    Output returns the path of the newly created timeline.otio in artifacts.
+
+    Delegates business logic to detect.detect_silence.
+    Uses default DetectSilenceOptions() when options is None.
+    """
+    resolved_options = options if options is not None else DetectSilenceOptions()
+    return detect_silence(
+        media=media,
+        output=output,
+        options=resolved_options,
+    )
+
+
+# ===========================================================================
+# Entry point (MCP stdio launch / DC-GP-002)
+# ===========================================================================
+
+
+def main() -> None:
+    """CLI entry point. Launches the MCP server over stdio (DC-GP-002).
+
+    Registered in pyproject.toml [project.scripts] as:
+    clipwright-silence = "clipwright_silence.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

clipwright_silence-0.1.0/src/clipwright_silence/vad_cli.py

@@ -0,0 +1,284 @@
+"""vad_cli.py — Separate-process small CLI for the Silero VAD backend.
+
+Not imported by the MCP server process (§2.4 subprocess loose coupling).
+detect.py spawns this as a separate process via
+sys.executable -m clipwright_silence.vad_cli.
+
+CLI contract (§7.1 unified):
+  - main(argv) catches all exceptions at the top level, always writes stdout JSON,
+    and returns 0.
+  - Success: {"speech_segments": [[start_sec, end_sec], ...]}
+  - Error:   {"error": {"code": str, "message": str, "hint": str}}
+  - stdout is JSON only. Logs and progress go to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import math
+import os
+import sys
+import tempfile
+import wave
+from typing import Any
+
+from clipwright.errors import ClipwrightError, ErrorCode
+from clipwright.process import resolve_tool, run
+
+# Fixed sample rate (§7.3)
+_SAMPLE_RATE = 16000
+# pip install hint string
+_VAD_INSTALL_HINT = (
+    "Install VAD dependencies with `pip install 'clipwright-silence[vad]'`."
+)
+# Sanitized generic message for SUBPROCESS_FAILED/TIMEOUT
+# (SR M-1: prevents ffmpeg stderr leakage)
+_SUBPROCESS_SAFE_MESSAGE = "internal subprocess failed"
+
+
+def _error_output(code: str, message: str, hint: str) -> None:
+    """Write error JSON to stdout.
+
+    The caller must sanitize path information before passing it here.
+    """
+    result: dict[str, Any] = {
+        "error": {
+            "code": code,
+            "message": message,
+            "hint": hint,
+        }
+    }
+    print(json.dumps(result, ensure_ascii=False), file=sys.stdout)
+
+
+def _extract_pcm(ffmpeg: str, media: str, output_path: str, timeout: float) -> None:
+    """Write 16kHz mono s16le PCM to a temporary file using ffmpeg.
+
+    Executed with shell=False and argument array only (subprocess discipline).
+    """
+    cmd = [
+        ffmpeg,
+        "-hide_banner",
+        "-nostats",
+        "-i",
+        media,
+        "-vn",
+        "-acodec",
+        "pcm_s16le",
+        "-ar",
+        str(_SAMPLE_RATE),
+        "-ac",
+        "1",
+        "-y",
+        output_path,
+    ]
+    run(cmd, timeout=timeout)
+
+
+def _load_audio_as_float32(
+    pcm_path: str,
+) -> tuple[Any, int]:
+    """Read a PCM WAV file and return a float32 numpy array and sample_rate.
+
+    Normalizes int16 -> float32 (/32768.0).
+
+    Precondition: This function must always be called via main().
+    main() lazily imports numpy and registers it in sys.modules, so the import
+    inside this function is effectively a cache lookup (NF-M-2: document precondition).
+    Calling directly from tests or utilities breaks the loose-coupling intent of CR L-2.
+    """
+    import numpy as np  # See docstring (cached in sys.modules by main())
+
+    with wave.open(pcm_path, "rb") as wf:
+        n_frames = wf.getnframes()
+        sample_rate = wf.getframerate()
+        raw = wf.readframes(n_frames)
+
+    audio_int16 = np.frombuffer(raw, dtype=np.int16)
+    audio_float32: Any = audio_int16.astype(np.float32) / 32768.0
+    return audio_float32, sample_rate
+
+
+def main(argv: list[str] | None = None) -> int:
+    """VAD CLI entry point.
+
+    Catches all exceptions at the top level, writes JSON to stdout,
+    and returns 0 (§7.1).
+
+    Args:
+        argv: Command-line argument list. Uses sys.argv[1:] if None.
+
+    Returns:
+        Exit code (always 0).
+    """
+    # Lazily import numpy inside main (CR L-2: avoid top-level import to keep
+    # server process loosely coupled. Separate process via sys.executable -m).
+    # Pre-import to cache in sys.modules (referenced by _load_audio_as_float32).
+    # noqa: F401 = suppress lint warning for not referencing directly (NF-L-2).
+    import numpy as np  # noqa: F401
+
+    # --- Parse arguments ---
+    parser = argparse.ArgumentParser(
+        description="Detect speech intervals using Silero VAD and output JSON to stdout."  # noqa: E501
+    )
+    parser.add_argument("--media", required=True, help="Input media file path")
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.5,
+        help="Speech probability threshold (0.0-1.0, default: 0.5)",
+    )
+    parser.add_argument(
+        "--min-speech",
+        type=float,
+        default=0.25,
+        help="Minimum speech duration (seconds, default: 0.25)",
+    )
+    parser.add_argument(
+        "--min-silence",
+        type=float,
+        default=0.1,
+        help="Minimum silence duration between speech intervals (seconds, default: 0.1)",  # noqa: E501
+    )
+    parser.add_argument(
+        "--media-duration",
+        type=float,
+        default=None,
+        help=(
+            "Total media duration (seconds). Used to calculate the inner"
+            " ffmpeg timeout proportional to total duration (§7.7)."
+            " Uses a safe default (60s) if omitted."
+        ),
+    )
+
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # Catch SystemExit from argparse (--help or missing required args)
+        _error_output(
+            code=ErrorCode.INVALID_INPUT,
+            message=f"Argument parsing failed: exit code {exc.code}",
+            hint="Specify --media <path> as a required argument.",
+        )
+        return 0
+
+    media: str = args.media
+    threshold: float = args.threshold
+    min_speech_sec: float = args.min_speech
+    min_silence_sec: float = args.min_silence
+    media_duration: float | None = args.media_duration
+
+    try:
+        # --- Lazy import of silero_vad (keep out of server process, §2.4) ---
+        try:
+            import silero_vad
+        except ImportError:
+            # SR L-2: str(exc) may contain internal paths; use fixed message
+            _error_output(
+                code=ErrorCode.DEPENDENCY_MISSING,
+                message="Failed to import silero_vad or onnxruntime",
+                hint=_VAD_INSTALL_HINT,
+            )
+            return 0
+
+        # --- Load Silero VAD model (before ffmpeg, to catch ImportError early) ---
+        # load_silero_vad raises ImportError if onnxruntime is missing (§7.3)
+        model = silero_vad.load_silero_vad(onnx=True)
+
+        # --- Resolve ffmpeg (§7.2) ---
+        ffmpeg = resolve_tool("ffmpeg", "CLIPWRIGHT_FFMPEG")
+
+        # --- Extract 16kHz mono s16le PCM to a temp file using ffmpeg (§7.3) ---
+        # Inner timeout must always be shorter than outer (§7.7)
+        # max(60, ceil(total*4)) for outer; proportional for inner
+        # When --media-duration given: max(30, ceil(total * 2))
+        # When omitted: safe default of 60 seconds
+        if media_duration is not None:
+            ffmpeg_timeout = float(max(30, math.ceil(media_duration * 2)))
+        else:
+            ffmpeg_timeout = 60.0
+
+        tmp_path: str = ""
+        audio_float32: Any
+        sample_rate: int
+
+        # Open with delete=False to get the name, then delete in try/finally (§7.3)
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_file:
+            tmp_path = tmp_file.name
+        try:
+            _extract_pcm(ffmpeg, media, tmp_path, timeout=ffmpeg_timeout)
+            audio_float32, sample_rate = _load_audio_as_float32(tmp_path)
+        finally:
+            # Ensure deletion even on exception (§7.3)
+            if tmp_path and os.path.exists(tmp_path):
+                with contextlib.suppress(OSError):
+                    os.unlink(tmp_path)
+
+        # get_speech_timestamps returns sample-unit values
+        # min_speech_duration_ms / min_silence_duration_ms are in milliseconds
+        raw_segments: list[dict[str, Any]] = silero_vad.get_speech_timestamps(
+            audio_float32,
+            model,
+            threshold=threshold,
+            sampling_rate=sample_rate,
+            min_speech_duration_ms=int(min_speech_sec * 1000),
+            min_silence_duration_ms=int(min_silence_sec * 1000),
+            return_seconds=False,
+        )
+
+        # Convert sample units -> seconds (built in ascending order)
+        speech_segments: list[list[float]] = []
+        for seg in sorted(raw_segments, key=lambda s: s["start"]):
+            start_sec = float(seg["start"]) / sample_rate
+            end_sec = float(seg["end"]) / sample_rate
+            speech_segments.append([start_sec, end_sec])
+
+        result: dict[str, Any] = {"speech_segments": speech_segments}
+        print(json.dumps(result, ensure_ascii=False), file=sys.stdout)
+        return 0
+
+    except ClipwrightError as exc:
+        # Catch ClipwrightError from core run() (SUBPROCESS_FAILED/TIMEOUT) and
+        # resolve_tool DEPENDENCY_MISSING here (§7.1/§7.2)
+        # SR M-1: SUBPROCESS_FAILED/TIMEOUT may embed ffmpeg stderr in message;
+        # replace with generic message to prevent path leakage
+        if exc.code in (ErrorCode.SUBPROCESS_FAILED, ErrorCode.SUBPROCESS_TIMEOUT):
+            safe_message = f"{_SUBPROCESS_SAFE_MESSAGE} (code: {exc.code})"
+        else:
+            safe_message = exc.message
+        _error_output(
+            code=str(exc.code),
+            message=safe_message,
+            hint=exc.hint,
+        )
+        return 0
+
+    except ImportError:
+        # ImportError propagated from load_silero_vad etc. when onnxruntime is missing
+        # SR L-2: str(exc) may contain internal paths; use fixed message
+        _error_output(
+            code=ErrorCode.DEPENDENCY_MISSING,
+            message="Failed to import silero_vad or onnxruntime",
+            hint=_VAD_INSTALL_HINT,
+        )
+        return 0
+
+    except Exception:
+        # Catch all unexpected exceptions and return error JSON (§7.1)
+        # SR NF-L-1: str(exc) may contain internal paths; use fixed message.
+        # Debug details are stderr-only; do not leak into stdout JSON (MCP response).
+        import traceback
+
+        traceback.print_exc(file=sys.stderr)
+        _error_output(
+            code=ErrorCode.INTERNAL,
+            message="An unexpected error occurred in VAD CLI",
+            hint="Please report with reproduction steps.",
+        )
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())