clipwright-sequence 0.1.0__py3-none-any.whl

clipwright_sequence/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-sequence — multi-source OTIO sequence builder MCP tool."""
+
+__version__ = "0.1.0"

clipwright_sequence/plan.py

@@ -0,0 +1,141 @@
+"""plan.py — Pure clip-resolution logic for clipwright-sequence.
+
+No I/O, no subprocess, no OTIO.  All operations work on float-second values.
+
+Design decisions (ADR-SEQ-3):
+- Empty clips list -> INVALID_INPUT (defensive guard).
+- start_sec=None defaults to 0.0; end_sec=None defaults to probe.duration_sec.
+- end_sec within one frame of duration is accepted and clipped to duration
+  (DC-AS-003 tolerance: absorbs probe-measurement error, no warning emitted).
+- start_sec >= end_sec - _EPSILON -> INVALID_INPUT (inversion check).
+- Clips are returned in enumeration order with zero-based index (DC-GP-003).
+- Probe keys are already resolved absolute paths (DC-AM-002 / §V2.6):
+  plan.py does NOT call Path().resolve().
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from clipwright.errors import ClipwrightError, ErrorCode
+
+from clipwright_sequence.schemas import SequenceClip
+
+# Floating-point epsilon for near-zero comparisons (same convention as trim/silence).
+_EPSILON = 1e-9
+
+
+@dataclass(frozen=True)
+class SourceProbe:
+    """Probe result for a single source media file.
+
+    abs_path is the resolved absolute path used as the probes dict key.
+    rate is frames-per-second (video). Audio-only sources never reach plan.py —
+    they are rejected by sequence.py before resolve_clip_specs is called.
+    The sentinel check (rate >= 1000.0) is performed by sequence.py.
+    """
+
+    abs_path: str
+    duration_sec: float
+    rate: float
+    has_video: bool
+
+
+@dataclass(frozen=True)
+class ResolvedClip:
+    """A fully resolved clip ready for OTIO construction.
+
+    start_sec and end_sec are concrete float seconds (no None values).
+    index is the zero-based position in the input clips list.
+    """
+
+    source: str
+    start_sec: float
+    end_sec: float
+    rate: float
+    index: int
+
+
+def resolve_clip_specs(
+    probes: dict[str, SourceProbe],
+    clips: list[SequenceClip],
+) -> tuple[list[ResolvedClip], list[str]]:
+    """Resolve SequenceClip specs against probed source metadata.
+
+    Args:
+        probes: Mapping from resolved absolute path to SourceProbe.
+                Keys must already be resolved paths (DC-AM-002 / §V2.6).
+        clips:  Ordered list of SequenceClip specs from the MCP caller.
+
+    Returns:
+        A 2-tuple of (resolved_clips, warnings).
+        resolved_clips is in the same enumeration order as the input clips.
+        warnings is an empty list in v0.1.0 (no clamping produces warnings).
+
+    Raises:
+        ClipwrightError(INVALID_INPUT) for:
+          - Empty clips list (defensive guard, ADR-SEQ-3 §1).
+          - end_sec exceeds duration beyond one-frame tolerance (DC-AS-003).
+          - start_sec >= end_sec after defaulting (inversion, ADR-SEQ-3).
+    """
+    if not clips:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="No clips were provided.",
+            hint="Provide at least one SequenceClip in the clips list.",
+        )
+
+    resolved: list[ResolvedClip] = []
+    warnings: list[str] = []
+
+    for index, clip in enumerate(clips):
+        probe = probes[clip.media]
+        duration = probe.duration_sec
+        rate = probe.rate
+
+        # Default None values to full-length range.
+        start = clip.start_sec if clip.start_sec is not None else 0.0
+        end = clip.end_sec if clip.end_sec is not None else duration
+
+        # DC-AS-003 tolerance: end within one frame beyond duration is accepted
+        # and silently clipped to duration (no warning — this absorbs probe error).
+        tolerance = max(_EPSILON, 1.0 / rate)
+        if end > duration and end <= duration + tolerance:
+            end = duration
+
+        # Out-of-range check: end still exceeds duration + tolerance.
+        if end > duration + tolerance:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="A clip's end_sec exceeds the source duration.",
+                hint=(
+                    f"Clip at index {index}: end_sec={end:.3f}s exceeds "
+                    f"source duration={duration:.3f}s (tolerance={tolerance:.6f}s). "
+                    "Set end_sec within the source duration, or omit end_sec."
+                ),
+            )
+
+        # Inversion check: start must be strictly less than end (gap > _EPSILON).
+        if start >= end - _EPSILON:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="A clip's start_sec is greater than or equal to its end_sec.",
+                hint=(
+                    f"Clip at index {index}: start_sec={start:.3f}s >= "
+                    f"end_sec={end:.3f}s — zero-length or inverted range. "
+                    "Ensure start_sec < end_sec for every clip. "
+                    "Omit end_sec to use the full source duration."
+                ),
+            )
+
+        resolved.append(
+            ResolvedClip(
+                source=probe.abs_path,
+                start_sec=start,
+                end_sec=end,
+                rate=rate,
+                index=index,
+            )
+        )
+
+    return resolved, warnings

clipwright_sequence/schemas.py

@@ -0,0 +1,56 @@
+"""schemas.py — Pydantic types for clipwright-sequence tool.
+
+SequenceClip: a single clip specification within a multi-source sequence.
+
+SequenceOptions is NOT defined in v0.1.0 (ADR-SEQ-1): the tool has no
+adjustable parameters yet.  Introduce SequenceOptions only when concrete
+options (e.g. transition hints) are added.
+
+Common types (MediaRef, Artifact, ToolResult) are imported from clipwright.schemas;
+do NOT redefine them here.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SequenceClip(BaseModel):
+    """A single clip specification within a multi-source sequence.
+
+    Each SequenceClip refers to a source media file and an optional
+    sub-range [start_sec, end_sec).  Omitting start_sec defaults to 0.0;
+    omitting end_sec defaults to the source's full duration.
+
+    Range validity (start_sec < end_sec, end_sec <= duration) is deferred
+    to plan.resolve_clip_specs because duration is unknown at schema-validation
+    time (ADR-SEQ-1).
+    """
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+
+    media: str = Field(
+        max_length=4096,  # OS path length upper bound
+        description=(
+            "Absolute or relative path to the source media file. "
+            "The path is resolved by the orchestration layer before probe."
+        ),
+    )
+    start_sec: float | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Start of the clip in seconds from the beginning of the source media. "
+            "Must be non-negative (ge=0) when provided. "
+            "Defaults to 0.0 (beginning of the source) when omitted."
+        ),
+    )
+    end_sec: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "End of the clip in seconds from the beginning of the source media. "
+            "Must be strictly positive (gt=0) when provided. "
+            "Defaults to the source's full duration when omitted."
+        ),
+    )

clipwright_sequence/sequence.py

@@ -0,0 +1,426 @@
+"""sequence.py — orchestration layer for clipwright-sequence.
+
+Assembles an ordered list of SequenceClip specs into a single multi-source
+OTIO timeline (V1 video track only).
+
+Design decisions:
+- build_sequence is the sole ClipwrightError -> error_result boundary (ADR-SEQ-4).
+  No error conversion in server.py; no I/O in plan.py.
+- Fast-fail order before spawning ffprobe: empty clips, clips>1000, .otio
+  extension, parent dir existence (§V2.12 / trim.py L66-99 pattern).
+- Unique sources are deduplicated by resolved absolute path in first-occurrence
+  order (§V2.6 DC-AM-002). probe is called exactly once per unique source.
+- Per-source validation order: probe -> duration None -> rate sentinel ->
+  has_video -> co-location -> output==source (§V2.2 DC-AS-002).
+- _resolve_and_check_colocation resolves the source path exactly once and
+  returns the resolved absolute path string, which is reused as SourceProbe.abs_path
+  and OTIO target_url (§V2.1 DC-AS-001; no double resolve).
+- All ClipwrightError from inspect_media (including DEPENDENCY_MISSING /
+  SUBPROCESS_*) propagate transparently through the 2-layer boundary
+  (§V2.10 DC-AM-004/005).
+- Error messages do not expose full paths (CWE-209).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+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.schemas import MediaRef, RationalTimeModel, TimeRangeModel, ToolResult
+
+import clipwright_sequence
+from clipwright_sequence.plan import SourceProbe, resolve_clip_specs
+from clipwright_sequence.schemas import SequenceClip
+
+# Sentinel frame rate produced by media.py when avg_frame_rate is 0/0 or N/A.
+# Keep in sync with clipwright.media (1000.0).
+_SENTINEL_RATE = 1000.0
+
+# Maximum number of clips accepted per call (§V2.12 DC-GP-003).
+_MAX_CLIPS = 1000
+
+
+def build_sequence(clips: list[SequenceClip], output: str) -> ToolResult:
+    """Public entry point. Sole ClipwrightError -> error_result boundary.
+
+    Assembles the ordered clips list into a single OTIO timeline written to
+    the output path.  Non-destructive: input media files are never modified.
+
+    Args:
+        clips: Ordered list of SequenceClip specs to assemble.
+        output: Output OTIO file path (.otio extension required).
+
+    Returns:
+        ok_result on success; error_result on any failure.
+        total_duration_sec in data is the sum of input clip ranges (an estimate);
+        the rendered output duration may differ by a few frames after normalization.
+    """
+    try:
+        return _build_sequence_inner(clips, output)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _build_sequence_inner(clips: list[SequenceClip], output: str) -> ToolResult:
+    """Internal implementation. Raises ClipwrightError directly on any failure.
+
+    Flow:
+      1. Fast-fail checks (before ffprobe): empty clips, clips>1000, .otio
+         extension, output parent dir existence.
+      2. Per unique source (first-occurrence order, resolved-path dedup):
+         inspect_media -> duration None -> rate sentinel -> has_video ->
+         co-location -> output==source.
+      3. resolve_clip_specs (pure range arithmetic / defaulting / tolerance).
+      4. OTIO build: new_timeline -> V1 clips with add_clip.
+      5. save_timeline (atomic write).
+      6. Return ok_result envelope.
+    """
+    output_path = Path(output)
+
+    # ------------------------------------------------------------------
+    # 1. Fast-fail checks (before spawning ffprobe)
+    # ------------------------------------------------------------------
+
+    # Empty clips list
+    if not clips:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="No clips were provided.",
+            hint="Provide at least one SequenceClip in the clips list.",
+        )
+
+    # Clips length upper bound (§V2.12 DC-GP-003)
+    if len(clips) > _MAX_CLIPS:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Too many clips were provided.",
+            hint=(
+                f"Received {len(clips)} clips; reduce to at most {_MAX_CLIPS} clips, "
+                "or split into multiple sequences."
+            ),
+        )
+
+    # Output extension must be .otio
+    if output_path.suffix.lower() != ".otio":
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Invalid output file extension. Only .otio is allowed.",
+            hint="Change the output file path extension to .otio.",
+        )
+
+    # Output parent directory must exist
+    if not output_path.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="The output directory does not exist.",
+            hint="Create the output directory first, then re-run.",
+        )
+
+    # ------------------------------------------------------------------
+    # 2. Per-unique-source validation and probe (first-occurrence order)
+    # ------------------------------------------------------------------
+
+    # Determine unique sources by resolved absolute path in first-occurrence order
+    # (§V2.6 DC-AM-002). All clip.media strings are pre-resolved to a temporary
+    # key for dedup; the canonical abs_path used as target_url comes from
+    # _resolve_and_check_colocation in the probe loop (DC-AS-001: single resolve).
+    #
+    # TOCTOU note: this pre-resolve and the second resolve in
+    # _resolve_and_check_colocation create a two-resolve window per source path.
+    # The window is closed by the inspect_media call (step 1 in the probe loop)
+    # which runs between the two resolves: inspect_media -> _validate_existing_file
+    # rejects symlinks and non-existent paths with FILE_NOT_FOUND, so any path
+    # manipulation between the two resolves is caught before the canonical abs_path
+    # is used as target_url (SR L-1 / DC-AS-005).
+    #
+    # pre_resolved_map: maps every clip.media string -> its temporary resolved key.
+    # This is used both for dedup and for mapping back after probing.
+    pre_resolved_map: dict[str, str] = {}  # clip.media -> resolved/absolute key
+    seen_keys: set[str] = set()
+    ordered_unique_media: list[
+        str
+    ] = []  # first-occurrence clip.media for each unique source
+
+    for clip in clips:
+        if clip.media in pre_resolved_map:
+            continue  # already processed this exact string
+        try:
+            key = str(Path(clip.media).resolve())
+        except OSError:
+            key = str(Path(clip.media).absolute())
+        pre_resolved_map[clip.media] = key
+        if key not in seen_keys:
+            seen_keys.add(key)
+            ordered_unique_media.append(clip.media)
+
+    # canonical_map: pre-resolved key -> canonical abs_path (set during probe loop).
+    # All clip.media spellings sharing the same pre-resolved key share one entry.
+    canonical_map: dict[str, str] = {}  # pre-resolved key -> canonical abs_path
+
+    probes: dict[str, SourceProbe] = {}  # keyed by canonical abs_path
+
+    for media in ordered_unique_media:
+        # (1) inspect_media (existence check, FILE_NOT_FOUND, DEPENDENCY_MISSING, etc.)
+        #     FILE_NOT_FOUND is caught here to replace the core message (which may
+        #     contain a full path from _validate_existing_file) with a basename-only
+        #     fixed message (CWE-209 / DC-AM-004/005). All other ClipwrightError codes
+        #     (DEPENDENCY_MISSING / SUBPROCESS_*) propagate transparently (§V2.10).
+        try:
+            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: {Path(media).name}",
+                    hint="Check that the path is correct and the file exists.",
+                ) from None
+            raise  # DEPENDENCY_MISSING / SUBPROCESS_* stay transparent
+
+        # (2) duration None -> PROBE_FAILED
+        if info.duration is None:
+            raise ClipwrightError(
+                code=ErrorCode.PROBE_FAILED,
+                message=f"Could not retrieve media duration: {Path(media).name}",
+                hint=(
+                    "Check that the media file is not corrupted. "
+                    "You can also verify manually with ffprobe."
+                ),
+            )
+
+        duration_sec = info.duration.value / info.duration.rate
+        rate = info.duration.rate
+
+        # (3) Rate sentinel: video stream reported avg_frame_rate=0/0 or N/A
+        #     (§V2.4 DC-AS-004). Sentinel rate means fps is undetermined.
+        if rate >= _SENTINEL_RATE:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message=(
+                    f"Could not determine a valid frame rate for source: "
+                    f"{Path(media).name}"
+                ),
+                hint=(
+                    "This source reports no usable frame rate (e.g. a still image "
+                    "stream or an unusual capture). Provide a video file with a "
+                    "normal frame rate."
+                ),
+            )
+
+        # (4) has_video check
+        has_video = any(s.codec_type == "video" for s in info.streams)
+        if not has_video:
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message=f"Source has no video stream: {Path(media).name}",
+                hint=(
+                    "Provide a source file that contains a video stream. "
+                    "Audio-only files are not supported."
+                ),
+            )
+
+        # (5) co-location check: resolve once, reuse as abs_path and target_url
+        #     (§V2.1 DC-AS-001 / §V2.2 step 5 / ADR-SEQ-6).
+        abs_path = _resolve_and_check_colocation(media, output_path)
+
+        # (6) output == source -> PATH_NOT_ALLOWED (§V2.8 DC-AM-001)
+        _check_output_not_source(output_path, abs_path)
+
+        probes[abs_path] = SourceProbe(
+            abs_path=abs_path,
+            duration_sec=duration_sec,
+            rate=rate,
+            has_video=has_video,
+        )
+
+        # Record the canonical abs_path for every clip.media string that shares
+        # the same pre-resolved key (handles "./a.mp4" vs "a.mp4" dedup).
+        media_key = pre_resolved_map[media]
+        canonical_map[media_key] = abs_path
+
+    # Build resolved-key clips for plan.resolve_clip_specs (§V2.6):
+    # replace each clip.media with its canonical abs_path so that plan.py
+    # can look up probes[clip.media] correctly.
+    resolved_key_clips = [
+        SequenceClip(
+            media=canonical_map[pre_resolved_map[clip.media]],
+            start_sec=clip.start_sec,
+            end_sec=clip.end_sec,
+        )
+        for clip in clips
+    ]
+
+    # ------------------------------------------------------------------
+    # 3. Resolve clip specs (pure arithmetic; raises INVALID_INPUT on range errors)
+    # ------------------------------------------------------------------
+
+    resolved_clips, warnings = resolve_clip_specs(probes, resolved_key_clips)
+
+    # ------------------------------------------------------------------
+    # 4. Build OTIO timeline (ADR-SEQ-5)
+    # ------------------------------------------------------------------
+
+    timeline = new_timeline(output_path.stem)
+    v1 = timeline.tracks[0]  # V1 (Video) track; index 0 per new_timeline
+
+    for rc in resolved_clips:
+        source_range = TimeRangeModel(
+            start_time=RationalTimeModel(value=rc.start_sec * rc.rate, rate=rc.rate),
+            duration=RationalTimeModel(
+                value=(rc.end_sec - rc.start_sec) * rc.rate, rate=rc.rate
+            ),
+        )
+        add_clip(
+            v1,
+            MediaRef(target_url=rc.source),
+            source_range,
+            name="sequence_clip",
+            metadata={
+                "tool": "clipwright_build_sequence",
+                "version": clipwright_sequence.__version__,
+                "kind": "sequence_clip",
+                "index": rc.index,
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # 5. Save timeline (atomic write)
+    # ------------------------------------------------------------------
+
+    save_timeline(timeline, output)
+
+    # ------------------------------------------------------------------
+    # 6. Build and return ok_result envelope (ADR-SEQ-7)
+    # ------------------------------------------------------------------
+
+    clip_count = len(resolved_clips)
+    total_duration_sec = sum(rc.end_sec - rc.start_sec for rc in resolved_clips)
+    unique_source_count = len(probes)
+
+    summary = (
+        f"Assembled a {clip_count}-clip sequence "
+        f"(approx total {total_duration_sec:.1f}s) "
+        f"from {unique_source_count} source(s). "
+        f"Generated {output_path.name}. "
+        f"Pass it to clipwright-render to concatenate into a single video."
+    )
+
+    return ok_result(
+        summary,
+        data={
+            "clip_count": clip_count,
+            "total_duration_sec": total_duration_sec,
+            "unique_source_count": unique_source_count,
+        },
+        artifacts=[{"role": "timeline", "path": str(output), "format": "otio"}],
+        warnings=warnings,
+    )
+
+
+def _resolve_and_check_colocation(media: str, output_path: Path) -> str:
+    """Resolve the source path once and verify co-location against output directory.
+
+    Resolves the source path exactly once and returns the resolved absolute path
+    string.  The return value is reused as SourceProbe.abs_path and the OTIO
+    target_url (DC-AS-001: no double resolve).
+
+    Mirrors render._check_within_timeline_dir (keep in sync).
+    Allows recursive subdirectories; raises PATH_NOT_ALLOWED only when the
+    source points outside the output parent directory tree (ADR-SEQ-6).
+    Falls back to absolute()-based comparison when resolve() raises OSError
+    (§V2.11 DC-GP-002 / SR L-1).
+
+    Error message uses fixed wording without exposing the full path (CWE-209).
+
+    Args:
+        media: Original source media path string.
+        output_path: Output OTIO file path (its parent is the project boundary).
+
+    Returns:
+        Resolved (or absolute, as fallback) absolute path string.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED when source is outside the project tree.
+    """
+    try:
+        base = output_path.parent.resolve()
+        target = Path(media).resolve()
+        base_str = str(base)
+        target_str = str(target)
+        if not (
+            target_str == base_str
+            or target_str.startswith(base_str + "/")
+            or target_str.startswith(base_str + "\\")
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.PATH_NOT_ALLOWED,
+                message="Source file points outside the project boundary.",
+                hint=(
+                    "Use a source file located under the same directory"
+                    " as the OTIO timeline."
+                ),
+            )
+        return target_str
+    except ClipwrightError:
+        raise
+    except OSError:
+        # resolve() failure (network paths, extremely long paths, symlink loops):
+        # fall back to absolute()-based best-effort comparison (§V2.11 DC-GP-002).
+        try:
+            base_abs = str(output_path.parent.absolute())
+            target_abs = str(Path(media).absolute())
+            if not (
+                target_abs == base_abs
+                or target_abs.startswith(base_abs + "/")
+                or target_abs.startswith(base_abs + "\\")
+            ):
+                raise ClipwrightError(
+                    code=ErrorCode.PATH_NOT_ALLOWED,
+                    message="Source file points outside the project boundary.",
+                    hint=(
+                        "Use a source file located under the same directory"
+                        " as the OTIO timeline."
+                    ),
+                )
+            return target_abs
+        except ClipwrightError:
+            raise
+        except OSError:
+            # Truly unresolvable (e.g. extremely long path, network path, or symlink
+            # loop where both resolve() and absolute() fail): accept the raw absolute
+            # path and skip boundary comparison. This is an intentional best-effort
+            # boundary-skip, consistent with the render/color/loudness precedent
+            # (SR L-2 / §V2.11 DC-GP-002). Only triggers under extreme path conditions
+            # not present in normal operation; real existence is verified upstream by
+            # inspect_media.
+            return str(Path(media).absolute())
+
+
+def _check_output_not_source(output_path: Path, abs_source: str) -> None:
+    """Verify that output and source do not resolve to the same path (§V2.8 DC-AM-001).
+
+    abs_source is already a resolved (or absolute-fallback) path from
+    _resolve_and_check_colocation, so only the output needs resolving.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED when paths are equal.
+    """
+    try:
+        out_resolved = str(output_path.resolve())
+    except OSError:
+        try:
+            out_resolved = str(output_path.absolute())
+        except OSError:
+            out_resolved = str(output_path)
+
+    if out_resolved == abs_source:
+        raise ClipwrightError(
+            code=ErrorCode.PATH_NOT_ALLOWED,
+            message="Output path and input source path are the same.",
+            hint=(
+                "Change the output file path to be different from the"
+                " input source file."
+            ),
+        )

clipwright_sequence/server.py

@@ -0,0 +1,90 @@
+"""server.py — clipwright-sequence MCP server entry point.
+
+Thin wrapper that delegates all business logic to sequence.build_sequence.
+No error conversion is performed here; build_sequence is the sole boundary.
+
+Transport: stdio (mcp.run(transport="stdio")).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from clipwright.schemas import ToolResult
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_sequence.schemas import SequenceClip
+from clipwright_sequence.sequence import build_sequence
+
+# FastMCP instance (server name matches package name)
+mcp = FastMCP("clipwright-sequence")
+
+
+# ===========================================================================
+# clipwright_build_sequence MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        # readOnlyHint=True: OTIO-only output; input media unchanged.
+        # Convention for non-render tools (render uses readOnlyHint=False).
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_build_sequence(
+    clips: Annotated[
+        list[SequenceClip],
+        Field(
+            description=(
+                "Ordered list of clip specifications to assemble into a sequence. "
+                "Each entry identifies a source media file and an optional sub-range. "
+                "Maximum 1000 clips per call (DC-GP-003)."
+            ),
+            max_length=1000,
+        ),
+    ],
+    output: Annotated[
+        str,
+        Field(
+            description=(
+                "Output OTIO timeline file path (.otio extension required). "
+                "Must be in the same directory as the source media files. "
+                "The file is created or overwritten atomically."
+            )
+        ),
+    ],
+) -> ToolResult:
+    """MCP tool: assemble an ordered list of clips into a single-track OTIO timeline.
+
+    Non-destructive: does not modify the input media files.
+    Produces a single V1 video track OTIO timeline consumed by clipwright-render.
+    total_duration_sec in the result data is an approx estimate based on input
+    clip ranges; the rendered output duration may differ after normalization.
+    Symlink sources are unsupported; resolve symlinks before passing to this tool.
+    Delegates all logic to sequence.build_sequence.
+    """
+    return build_sequence(clips=clips, output=output)
+
+
+# ===========================================================================
+# 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-sequence = "clipwright_sequence.server:main"
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

clipwright_sequence-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.3
+Name: clipwright-sequence
+Version: 0.1.0
+Summary: MCP tool for assembling multiple source media files into a single OTIO timeline (multi-source sequence builder).
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.2.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: opentimelineio>=0.18
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# clipwright-sequence
+
+MCP tool that assembles multiple source media files into a single multi-source OTIO
+timeline for concatenation by `clipwright-render`.
+
+## Overview
+
+`clipwright-sequence` accepts an ordered list of clip specifications and emits a single
+OTIO timeline file (one V1 video track; A1 audio track left empty for BGM or mixing
+by the calling agent). The timeline is consumed unchanged by `clipwright-render`, which
+concatenates the clips into a single output video.
+
+This fills the gap between single-source tools and multi-clip programs: every other
+clipwright tool starts from one `media` file. `clipwright-sequence` is the authoring
+primitive that builds a multi-source program OTIO before the final render pass.
+
+**Design principle** (M3 — separation of annotation and realisation):
+`clipwright-sequence` writes only the OTIO; it does not transcode or touch media files.
+All media processing is deferred to `clipwright-render`.
+
+## Prerequisites
+
+- Python 3.11 or later
+- `clipwright` core package (shared types, envelope, OTIO utils)
+- `CLIPWRIGHT_FFPROBE` environment variable (or `ffprobe` on `PATH`) — used to probe
+  each source's duration and confirm video stream presence before building the timeline
+
+No FFmpeg is needed at sequence-build time; FFmpeg is only invoked by `clipwright-render`
+at realisation time.
+
+## MCP Tool: `clipwright_build_sequence`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `clips` | `list[SequenceClip]` | required | Ordered list of clip specifications to assemble. Maximum 1000 entries per call (DC-GP-003). |
+| `clips[].media` | `string` | required | Path to the source media file. Must be co-located under the output directory (see Co-location Constraint). |
+| `clips[].start_sec` | `float \| null` | `null` → `0.0` | Start of the clip in seconds from the beginning of the source. Must be ≥ 0. |
+| `clips[].end_sec` | `float \| null` | `null` → full duration | End of the clip in seconds from the beginning of the source. Must be > 0 and ≤ source duration. |
+| `output` | `string` | required | Output OTIO timeline file path (`.otio` extension required). The parent directory must exist. |
+
+### Return value
+
+```json
+{
+  "ok": true,
+  "summary": "Assembled a 3-clip sequence (approx total 45.2s) from 2 source(s). Generated sequence.otio. Pass it to clipwright-render to concatenate into a single video.",
+  "data": {
+    "clip_count": 3,
+    "total_duration_sec": 45.2,
+    "unique_source_count": 2
+  },
+  "artifacts": [{"role": "timeline", "path": "sequence.otio", "format": "otio"}],
+  "warnings": []
+}
+```
+
+> **Note on `total_duration_sec`**: This value is an approximate estimate computed as
+> the sum of the input clip ranges (DC-AM-003). The rendered output duration may differ
+> slightly after per-frame normalisation in `clipwright-render`.
+
+### Error codes
+
+| Code | Cause |
+|------|-------|
+| `INVALID_INPUT` | `clips` is empty, exceeds 1000 entries, contains an invalid range (`start_sec >= end_sec`, `end_sec > source duration`), or `output` has a non-`.otio` extension |
+| `INVALID_INPUT` | `output` parent directory does not exist |
+| `INVALID_INPUT` | A source file has no video stream (audio-only file) |
+| `INVALID_INPUT` | A source file's frame rate is undetermined (e.g. still-image stream or unusual capture device) |
+| `FILE_NOT_FOUND` | A source media path does not exist |
+| `PATH_NOT_ALLOWED` | A source file is located outside the output directory tree (co-location violation) |
+| `PATH_NOT_ALLOWED` | `output` path and a source media path resolve to the same file |
+| `PROBE_FAILED` | ffprobe could not determine a source's duration (corrupted file) |
+| `DEPENDENCY_MISSING` | ffprobe binary not found (`CLIPWRIGHT_FFPROBE` unset and not on `PATH`) |
+
+## Co-location Constraint
+
+All source media files **must be located under the same directory as the output `.otio`
+file** (or in a recursive subdirectory of it).
+
+**Why this mirrors `clipwright-render`'s rule — not a relaxation of it:**
+`clipwright-render` enforces a `PATH_NOT_ALLOWED` boundary: every source referenced in
+an OTIO timeline must be co-located with the timeline file. If `clipwright-sequence`
+were to accept sources from outside that boundary, the produced `.otio` would be valid
+at build time but would fail immediately when passed to `clipwright-render`.
+
+By enforcing the same co-location rule at sequence-build time, `clipwright-sequence`
+guarantees that any `.otio` it produces will round-trip through `clipwright-render`
+without a `PATH_NOT_ALLOWED` error. The constraint is a forward-compatibility guarantee,
+not an arbitrary restriction.
+
+Recursive subdirectories are permitted: sources may live anywhere inside the tree rooted
+at the output's parent directory.
+
+```
+project/
+  intro.mp4          ← allowed (same directory)
+  footage/
+    main.mp4         ← allowed (subdirectory)
+    broll.mp4        ← allowed (subdirectory)
+  sequence.otio      ← output
+```
+
+```
+/other/path/clip.mp4  ← PATH_NOT_ALLOWED
+```
+
+## Symlink Sources
+
+Symlink sources are **not supported** (DC-AS-005). Resolve symlinks to their real paths
+before passing them to this tool.
+
+## Two-Phase Workflow
+
+```
+clipwright_build_sequence(clips, output)     # Phase 1 — build OTIO
+        │
+        ▼  OTIO timeline with ordered V1 clips
+clipwright_render(timeline, output_media)    # Phase 2 — concatenate and encode
+        │
+        ▼  single output video (intro + main + outro, or any sequence)
+```
+
+`clipwright-sequence` can be combined with other directive tools before the final render:
+
+```
+clipwright_build_sequence → clipwright_detect_color → clipwright_reduce_noise → clipwright_render
+```
+
+## MCP Client Registration
+
+Register `clipwright-sequence` as a standalone MCP server in your client configuration
+(`.mcp.json` / `claude_desktop_config.json`). `CLIPWRIGHT_FFPROBE` is required.
+
+```json
+{
+  "mcpServers": {
+    "clipwright-sequence": {
+      "command": "clipwright-sequence",
+      "env": {
+        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
+      }
+    }
+  }
+}
+```
+
+`clipwright-render` (which materialises the OTIO into a video) still requires
+`CLIPWRIGHT_FFMPEG`.
+
+## Usage Examples
+
+### Assemble intro + main + outro
+
+```python
+# Via MCP call_tool
+result = await session.call_tool("clipwright_build_sequence", {
+    "clips": [
+        {"media": "/project/intro.mp4"},
+        {"media": "/project/main.mp4", "start_sec": 10.0, "end_sec": 130.0},
+        {"media": "/project/outro.mp4"}
+    ],
+    "output": "/project/sequence.otio"
+})
+# Then render
+render_result = await session.call_tool("clipwright_render", {
+    "timeline": "/project/sequence.otio",
+    "output": "/project/final.mp4"
+})
+```
+
+### Splice two gameplay segments
+
+```python
+result = await session.call_tool("clipwright_build_sequence", {
+    "clips": [
+        {"media": "/project/gameplay.mp4", "start_sec": 60.0, "end_sec": 180.0},
+        {"media": "/project/gameplay.mp4", "start_sec": 300.0, "end_sec": 420.0}
+    ],
+    "output": "/project/highlights.otio"
+})
+```
+
+The same source file may appear multiple times (with different ranges). Each unique
+source is probed exactly once.
+
+### B-roll interleave
+
+```python
+result = await session.call_tool("clipwright_build_sequence", {
+    "clips": [
+        {"media": "/project/interview.mp4", "start_sec": 0.0, "end_sec": 30.0},
+        {"media": "/project/broll/cityscape.mp4"},
+        {"media": "/project/interview.mp4", "start_sec": 30.0, "end_sec": 60.0}
+    ],
+    "output": "/project/edited.otio"
+})
+```
+
+## Installation
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-sequence clipwright-sequence
+```
+
+Or install from PyPI:
+
+```bash
+pip install clipwright-sequence
+clipwright-sequence
+```
+
+## License
+
+MIT — See [LICENSE](../LICENSE) for details.

clipwright_sequence-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clipwright_sequence/__init__.py,sha256=4VmSHb1BRFPj3m9jDnCbaOBkksmLHW8XLNZ6R-2QFZw,98
+clipwright_sequence/plan.py,sha256=AfTtosOj_yLB7KoVi15SozAAPmGto6NnkEKkENA6xiw,5123
+clipwright_sequence/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clipwright_sequence/schemas.py,sha256=8fviz4jhZbWyeA5dz2GHPZN7raA0Yj7bRPMjzsGYr60,1992
+clipwright_sequence/sequence.py,sha256=m3it7mEdanrhWwY9EG1OvtVzfMsLcoKjhBUyN_ys7r8,17839
+clipwright_sequence/server.py,sha256=qnLmswe25m0mHBV7aS9rg_Ctnw6VnZoTBNjUdSEmciM,3022
+clipwright_sequence-0.1.0.dist-info/WHEEL,sha256=oBsDExVIEya4llboy9Ce1l6on8xt3GrtT29y6pYVypw,81
+clipwright_sequence-0.1.0.dist-info/entry_points.txt,sha256=pHRnAFvRp94jhACERCFVanRhKpfhqse69fbvRw6m4xc,73
+clipwright_sequence-0.1.0.dist-info/METADATA,sha256=1lUQEdLZ2y8CMg62uAURDkKBfOPE8Nkj4mi1upJIipU,8299
+clipwright_sequence-0.1.0.dist-info/RECORD,,

clipwright_sequence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.23
+Root-Is-Purelib: true
+Tag: py3-none-any

clipwright_sequence-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clipwright-sequence = clipwright_sequence.server:main
+