clipwright 0.1.1__py3-none-any.whl

clipwright/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright: Core library for the FFmpeg/OTIO MCP server suite."""
+
+__version__ = "0.1.1"

clipwright/cli_io.py

@@ -0,0 +1,25 @@
+"""cli_io.py — Shared UTF-8 I/O helper for separate-process CLIs.
+
+DRY home for the per-CLI UTF-8 pinning helper (CR L-2 / SR I-1). wrap_cli and
+vad_cli import force_utf8_io() from here instead of carrying a local copy, so the
+behaviour is defined once for every separate-process CLI that depends on core.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def force_utf8_io() -> None:
+    """Pin stdin/stdout to UTF-8 so this CLI is correct regardless of host
+    locale or inherited PYTHONIOENCODING (cp932 on JP Windows otherwise).
+
+    MUST be called before the first read from stdin: TextIOWrapper.reconfigure
+    raises once buffered reading has begun. Calling it at the very top of main()
+    (before sys.stdin.read()) satisfies this. Safe to call even on a CLI that
+    never reads stdin (reconfigure before any read is a no-op there).
+    """
+    for stream in (sys.stdin, sys.stdout):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")

clipwright/envelope.py

@@ -0,0 +1,64 @@
+"""envelope.py — Return value envelope construction helpers.
+
+Thin helpers that normalise all tool return values to the standard format (§6.3 / §6.4).
+Returns dict representations of ToolResult / ToolErrorResult, which are directly
+compatible with FastMCP JSON serialisation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def ok_result(
+    summary: str,
+    *,
+    data: dict[str, Any] | None = None,
+    artifacts: list[Any] | None = None,
+    warnings: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build a success envelope dict (§6.3 ToolResult form).
+
+    summary must include key points an AI needs to decide the next action
+    (counts, durations, maxima, etc.). Do not make it minimal.
+
+    Args:
+        summary: Key points of the result (required).
+        data: Supplementary information (optional).
+        artifacts: List of references to output files (optional).
+        warnings: List of warning messages (optional).
+
+    Returns:
+        A dict of the form { ok: True, summary, data, artifacts, warnings }.
+    """
+    return {
+        "ok": True,
+        "summary": summary,
+        "data": data if data is not None else {},
+        "artifacts": artifacts if artifacts is not None else [],
+        "warnings": warnings if warnings is not None else [],
+    }
+
+
+def error_result(code: str, message: str, hint: str) -> dict[str, Any]:
+    """Build a failure envelope dict (§6.4 ToolErrorResult form).
+
+    message describes what happened; hint describes the concrete next step.
+    An empty hint violates the error contract (§6).
+
+    Args:
+        code: String representation of an ErrorCode value.
+        message: What happened.
+        hint: Concrete, actionable next step.
+
+    Returns:
+        A dict of the form { ok: False, error: { code, message, hint } }.
+    """
+    return {
+        "ok": False,
+        "error": {
+            "code": code,
+            "message": message,
+            "hint": hint,
+        },
+    }

clipwright/errors.py

@@ -0,0 +1,62 @@
+"""errors.py — Error code taxonomy and ClipwrightError exception.
+
+The library layer raises ClipwrightError on failure;
+server.py converts it to error_result at the MCP boundary.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    """Error codes shared across all Clipwright tools (§4 + §13.1 DC-AM-002/DC-AS-003).
+
+    Inherits str so values are JSON-serializable at API boundaries.
+    Each value equals its name string.
+    """
+
+    DEPENDENCY_MISSING = "DEPENDENCY_MISSING"
+    """External tool (ffmpeg/ffprobe, etc.) not found."""
+    INVALID_INPUT = "INVALID_INPUT"
+    """Argument validation failed."""
+    FILE_NOT_FOUND = "FILE_NOT_FOUND"
+    """No file exists at the given input path."""
+    PATH_NOT_ALLOWED = "PATH_NOT_ALLOWED"
+    """Path validation failed (e.g., path traversal attempt)."""
+    SUBPROCESS_FAILED = "SUBPROCESS_FAILED"
+    """External process exited with a non-zero return code."""
+    SUBPROCESS_TIMEOUT = "SUBPROCESS_TIMEOUT"
+    """External process timed out."""
+    PROBE_FAILED = "PROBE_FAILED"
+    """Failed to parse ffprobe output."""
+    OTIO_ERROR = "OTIO_ERROR"
+    """Failed to read, write, or parse an OTIO file."""
+    PROJECT_NOT_FOUND = "PROJECT_NOT_FOUND"
+    """clipwright.json not found."""
+    PROJECT_EXISTS = "PROJECT_EXISTS"
+    """An existing project already exists at the target init location."""
+    UNSUPPORTED_OPERATION = "UNSUPPORTED_OPERATION"
+    """Unknown or unsupported operation type."""
+    INTERNAL = "INTERNAL"
+    """Unexpected internal error (§13.1 DC-AM-002).
+
+    Use a generic message; expose stack traces only in hints/logs.
+    The hint must include a prompt to report with reproduction steps.
+    """
+    TRACK_NOT_FOUND = "TRACK_NOT_FOUND"
+    """The track index in operations exceeds the total track count (§13.1 DC-AS-003)."""
+
+
+class ClipwrightError(Exception):
+    """Exception raised by the Clipwright library layer.
+
+    Always carries the three-part set: code / message / hint (§6.4 error contract).
+    hint must describe the concrete next action for the user or AI agent.
+    """
+
+    def __init__(self, code: ErrorCode, message: str, hint: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint

clipwright/media.py

@@ -0,0 +1,223 @@
+"""media.py — ffprobe wrapper.
+
+Probes a media file with ffprobe and returns a structured MediaInfo.
+Delegates ffprobe invocation to process.run, following subprocess discipline (§6.5).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import clipwright.process as _process_module
+from clipwright.errors import ClipwrightError, ErrorCode
+from clipwright.schemas import MediaInfo, RationalTimeModel, StreamInfo
+
+
+def inspect_media(path: str) -> MediaInfo:
+    """Probe a media file with ffprobe and return a MediaInfo.
+
+    Execution order: validate input → resolve ffprobe → run subprocess → parse JSON.
+    ffprobe is located via the CLIPWRIGHT_FFPROBE env var, then shutil.which (ADR-3).
+
+    Args:
+        path: Path to the media file to probe.
+
+    Returns:
+        Parsed MediaInfo instance.
+
+    Raises:
+        ClipwrightError: File not found (FILE_NOT_FOUND), ffprobe not found
+            (DEPENDENCY_MISSING), JSON parse failure (PROBE_FAILED),
+            or subprocess failure (SUBPROCESS_FAILED / SUBPROCESS_TIMEOUT).
+    """
+    _validate_existing_file(path)
+    ffprobe = _process_module.resolve_tool("ffprobe", "CLIPWRIGHT_FFPROBE")
+
+    cmd = [
+        ffprobe,
+        "-v",
+        "quiet",
+        "-print_format",
+        "json",
+        "-show_format",
+        "-show_streams",
+        path,
+    ]
+    result = _process_module.run(cmd, timeout=30.0)
+    return _parse_ffprobe_json(path, result.stdout)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_optional_int(val: object) -> int | None:
+    """Convert an arbitrary value to int, returning None if conversion is not possible.
+
+    Helper for safely converting field values after JSON parsing (int / float /
+    numeric string / None, etc.) to int (L-2: CR-Q-002 / SR-V-001).
+    Float strings such as "1.5" are treated as non-convertible and return None.
+    bool is a subclass of int, so True→1 / False→0 (existing behaviour).
+
+    Args:
+        val: Value to convert.
+
+    Returns:
+        Converted int, or None if conversion is not possible.
+    """
+    if val is None:
+        return None
+    if isinstance(val, (int, float)):
+        try:
+            return int(val)
+        except (ValueError, OverflowError):
+            return None
+    if isinstance(val, str):
+        try:
+            return int(val)
+        except ValueError:
+            return None
+    return None
+
+
+def _validate_existing_file(path: str) -> None:
+    """Verify that a file exists at the given path.
+
+    Symbolic links are rejected (F-04: SR-V-002).
+    Raises FILE_NOT_FOUND if the file does not exist.
+    """
+    p = Path(path)
+    if p.is_symlink():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"Symbolic links are not accepted: {path}",
+            hint="Specify the path to a real file, not a symbolic link.",
+        )
+    if not p.is_file():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"File not found: {path}",
+            hint="Check that the path is correct and the file exists.",
+        )
+
+
+def _parse_avg_frame_rate(avg_frame_rate: str) -> float:
+    """Convert an ffprobe avg_frame_rate string (e.g. "30/1", "24000/1001") to float.
+
+    Returns 0.0 for malformed input so the caller does not treat it as a video stream.
+    """
+    if "/" in avg_frame_rate:
+        parts = avg_frame_rate.split("/", 1)
+        try:
+            num = float(parts[0])
+            den = float(parts[1])
+            if den == 0.0:
+                return 0.0
+            return num / den
+        except ValueError:
+            return 0.0
+    try:
+        return float(avg_frame_rate)
+    except ValueError:
+        return 0.0
+
+
+def _parse_ffprobe_json(path: str, stdout: str) -> MediaInfo:
+    """Parse ffprobe JSON output into a structured MediaInfo.
+
+    Raises PROBE_FAILED on JSON parse errors or missing required fields.
+    Rate determination rules (§13.3 DC-AS-006):
+      - If a video stream exists, use avg_frame_rate of the first video stream as rate.
+      - Audio-only sources use rate = 1000.0.
+    duration.value holds the frame count computed as seconds × rate.
+
+    Args:
+        path: Original input file path (stored as MediaInfo.path).
+        stdout: JSON string output by ffprobe.
+
+    Returns:
+        Parsed MediaInfo instance.
+
+    Raises:
+        ClipwrightError: JSON parse failure or missing required fields (PROBE_FAILED).
+    """
+    if not stdout:
+        raise ClipwrightError(
+            code=ErrorCode.PROBE_FAILED,
+            message="ffprobe returned empty output",
+            hint="Check that the input file is a valid media file.",
+        )
+
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        # Do not expose parser-internal error strings; use a generic message (R3-L-02).
+        raise ClipwrightError(
+            code=ErrorCode.PROBE_FAILED,
+            message="ffprobe output is not valid JSON.",
+            hint="Check that the input file is a valid media file.",
+        ) from exc
+
+    # Verify required fields
+    if "streams" not in data or "format" not in data:
+        raise ClipwrightError(
+            code=ErrorCode.PROBE_FAILED,
+            message="ffprobe JSON is missing required fields (streams / format)",
+            hint="Check that the input file is a valid media file.",
+        )
+
+    raw_streams: list[dict[str, object]] = data["streams"]
+    raw_format: dict[str, object] = data["format"]
+
+    # Populate stream info
+    streams: list[StreamInfo] = []
+    for s in raw_streams:
+        codec_name_raw = s.get("codec_name")
+        index_raw = s.get("index", 0)
+
+        streams.append(
+            StreamInfo(
+                index=_to_optional_int(index_raw) or 0,
+                codec_type=str(s.get("codec_type", "")),
+                codec_name=str(codec_name_raw) if codec_name_raw is not None else None,
+                width=_to_optional_int(s.get("width")),
+                height=_to_optional_int(s.get("height")),
+                sample_rate=_to_optional_int(s.get("sample_rate")),
+                channels=_to_optional_int(s.get("channels")),
+            )
+        )
+
+    # Rate determination (§13.3 DC-AS-006): use avg_frame_rate of first video stream;
+    # audio-only defaults to 1000.0.
+    rate = 1000.0
+    for s in raw_streams:
+        if str(s.get("codec_type", "")) == "video":
+            avg_frame_rate_raw = s.get("avg_frame_rate", "")
+            if avg_frame_rate_raw:
+                parsed_rate = _parse_avg_frame_rate(str(avg_frame_rate_raw))
+                if parsed_rate > 0.0:
+                    rate = parsed_rate
+                    break
+
+    # Represent duration as RationalTimeModel
+    duration: RationalTimeModel | None = None
+    duration_raw = raw_format.get("duration")
+    if duration_raw is not None:
+        try:
+            duration_sec = float(str(duration_raw))
+            # value = seconds × rate (frame count equivalent)
+            duration = RationalTimeModel(value=duration_sec * rate, rate=rate)
+        except (ValueError, TypeError):
+            pass
+
+    container = str(raw_format.get("format_name", "")) or None
+
+    return MediaInfo(
+        path=path,
+        container=container,
+        duration=duration,
+        streams=streams,
+        bit_rate=_to_optional_int(raw_format.get("bit_rate")),
+    )

clipwright/operations.py

@@ -0,0 +1,165 @@
+"""operations.py — Declarative edit operation types and apply logic.
+
+Operations are typed via a Pydantic discriminated union;
+apply_operations applies them to the timeline in an all-or-nothing transaction.
+
+This vocabulary forms the common interface for detect-family tools.
+(Spec §4.2 dogfooding premise)
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+import opentimelineio as otio
+from pydantic import BaseModel, Field
+
+from clipwright.errors import ErrorCode
+from clipwright.otio_utils import add_clip, add_gap, add_marker
+from clipwright.schemas import (
+    MediaRef,
+    OperationError,
+    RationalTimeModel,
+    TimeRangeModel,
+    ValidationReport,
+)
+
+# ===========================================================================
+# Operation types (discriminated union members)
+# ===========================================================================
+
+
+class AddClipOp(BaseModel):
+    """Operation to append a clip to a track.
+
+    track is a flat index (0=V1, 1=A1).
+    metadata uses Any because OTIO metadata is an arbitrary key-value dict.
+    Size and nesting limits are left for a future task.
+    """
+
+    op: Literal["add_clip"]
+    track: int = 0
+    media: MediaRef
+    source_range: TimeRangeModel
+    name: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class AddGapOp(BaseModel):
+    """Operation to append a gap to a track.
+
+    track is a flat index (0=V1, 1=A1).
+    """
+
+    op: Literal["add_gap"]
+    track: int = 0
+    duration: RationalTimeModel
+
+
+class AddMarkerOp(BaseModel):
+    """Operation to attach a marker to the track itself (§13.5 DC-GP-001 re).
+
+    track is a flat index (0=V1, 1=A1).
+    No clip needs to exist; an empty track is valid.
+    metadata uses Any because OTIO metadata is an arbitrary key-value dict.
+    Size and nesting limits are left for a future task.
+    """
+
+    op: Literal["add_marker"]
+    track: int = 0
+    marked_range: TimeRangeModel
+    name: str
+    color: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+# Discriminated union (discriminator="op")
+Operation = Annotated[
+    AddClipOp | AddGapOp | AddMarkerOp,
+    Field(discriminator="op"),
+]
+
+# ===========================================================================
+# apply_operations — all-or-nothing (§13.1 DC-AM-004)
+# ===========================================================================
+
+
+def apply_operations(
+    timeline: otio.schema.Timeline,
+    ops: list[AddClipOp | AddGapOp | AddMarkerOp],
+    *,
+    validate_only: bool,
+) -> ValidationReport:
+    """Apply ops to timeline (all-or-nothing).
+
+    Validates all operations first. If any are invalid, nothing is applied and
+    ValidationReport(valid=False, applied_count=0, errors=[...]) is returned.
+    All operations are applied only when every one is valid; applied_count=len(ops).
+
+    validate_only=True: validates only; does not apply or save (applied_count=0).
+    track is resolved by flat index (0-based). Out-of-range raises TRACK_NOT_FOUND.
+    """
+    operation_count = len(ops)
+    errors: list[OperationError] = []
+    track_count = len(timeline.tracks)
+
+    # --- Validation phase ---
+    for i, op in enumerate(ops):
+        if op.track < 0 or op.track >= track_count:
+            errors.append(
+                OperationError(
+                    index=i,
+                    code=ErrorCode.TRACK_NOT_FOUND,
+                    message=(
+                        f"track {op.track} does not exist."
+                        f" The timeline has {track_count} track(s)."
+                        f" Specify track in the range 0..{track_count - 1}"
+                    ),
+                )
+            )
+
+    if errors:
+        return ValidationReport(
+            valid=False,
+            operation_count=operation_count,
+            applied_count=0,
+            errors=errors,
+        )
+
+    # Return early when validate_only is set
+    if validate_only:
+        return ValidationReport(
+            valid=True,
+            operation_count=operation_count,
+            applied_count=0,
+            errors=[],
+        )
+
+    # --- Apply phase ---
+    for op in ops:
+        track = timeline.tracks[op.track]
+        if isinstance(op, AddClipOp):
+            add_clip(
+                track,
+                op.media,
+                op.source_range,
+                name=op.name,
+                metadata=op.metadata,
+            )
+        elif isinstance(op, AddGapOp):
+            add_gap(track, op.duration)
+        elif isinstance(op, AddMarkerOp):
+            add_marker(
+                track,
+                op.marked_range,
+                op.name,
+                color=op.color,
+                metadata=op.metadata,
+            )
+
+    return ValidationReport(
+        valid=True,
+        operation_count=operation_count,
+        applied_count=operation_count,
+        errors=[],
+    )