clipwright 0.2.0__tar.gz → 0.3.0__tar.gz

{clipwright-0.2.0 → clipwright-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: clipwright
-Version: 0.2.0
+Version: 0.3.0
 Summary: MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents.
 Author: satoh-y-0323
 Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
@@ -50,6 +50,38 @@ export CLIPWRIGHT_FFMPEG="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Package
 
 ---
 
+## Prerequisite: clipwright-transcribe (whisper-cli)
+
+`clipwright-transcribe` requires the **whisper.cpp** binary (`whisper-cli`) and a ggml
+model file. They are not installed via pip — obtain them separately.
+
+### whisper-cli Binary
+
+| Platform | How to install |
+|---|---|
+| **Windows** | Download the pre-built binary from [whisper.cpp Releases](https://github.com/ggerganov/whisper.cpp/releases) → `whisper-bin-x64.zip` (CPU) or `whisper-cublas-*-bin-x64.zip` (CUDA). Extract and place `whisper-cli.exe` in a directory on `PATH`, or set `CLIPWRIGHT_WHISPER`. |
+| **macOS** | `brew install whisper-cpp` — installs `whisper-cli` on PATH automatically. |
+| **Linux** | Build from source: `git clone https://github.com/ggerganov/whisper.cpp && cd whisper.cpp && cmake -B build && cmake --build build -j --config Release` — binary is at `build/bin/whisper-cli`. |
+
+```bash
+# If whisper-cli is not on PATH, set the full path:
+export CLIPWRIGHT_WHISPER=/path/to/whisper-cli
+```
+
+### ggml Model File
+
+Download a model (e.g. `ggml-base.bin`) from [Hugging Face](https://huggingface.co/ggerganov/whisper.cpp).
+
+```bash
+export CLIPWRIGHT_WHISPER_MODEL=/path/to/ggml-base.bin
+```
+
+If neither `CLIPWRIGHT_WHISPER` nor a `whisper-cli` binary on PATH is found, the
+`clipwright_transcribe` tool returns `DEPENDENCY_MISSING` and integration tests are
+automatically skipped.
+
+---
+
 ## Development Environment Setup
 
 ```bash
@@ -189,6 +221,26 @@ For details, see [docs/clipwright-spec.md](docs/clipwright-spec.md).
 
 ---
 
+## Available Tools
+
+| Package | MCP Tool | Description |
+|---------|----------|-------------|
+| `clipwright` (core) | `clipwright_inspect_media` | Probe a media file and return codec / duration / stream info |
+| `clipwright` (core) | `clipwright_init_project` | Initialize a project directory with an empty OTIO timeline |
+| `clipwright` (core) | `clipwright_read_timeline` | Read an OTIO timeline file and return its structure |
+| `clipwright` (core) | `clipwright_write_timeline` | Write an OTIO timeline back to disk |
+| `clipwright-silence` | `clipwright_detect_silence` | Detect silent regions in audio via FFmpeg `silencedetect` and annotate OTIO markers |
+| `clipwright-loudness` | `clipwright_measure_loudness` | Measure EBU R128 loudness (integrated LUFS / true-peak) via FFmpeg |
+| `clipwright-noise` | `clipwright_reduce_noise` | Annotate OTIO timeline with FFmpeg `afftdn` noise-reduction settings |
+| `clipwright-transcribe` | `clipwright_transcribe` | Transcribe audio to text via whisper-cli and write word-level OTIO markers |
+| `clipwright-bgm` | `clipwright_place_bgm` | Write BGM placement annotations (volume / fade / ducking) to OTIO timeline |
+| `clipwright-render` | `clipwright_render` | Realize OTIO edit operations (trim / concat / filters) to an output media file via FFmpeg |
+| `clipwright-wrap` | `clipwright_wrap_text` | Wrap long text lines with line-break annotations in OTIO timeline |
+| `clipwright-scene` | `clipwright_detect_scenes` | Detect shot boundaries via FFmpeg `scdet` or PySceneDetect and write OTIO markers |
+| `clipwright-frames` | `clipwright_extract_frames` | Extract still frames from video at specified times, scene boundaries, or fixed intervals; writes images, OTIO markers, and a JSON manifest |
+
+---
+
 ## MCP Client Registration
 
 Each clipwright tool is a standalone MCP server. Register them in your MCP client configuration (`.mcp.json` / `claude_desktop_config.json`):
@@ -208,11 +260,30 @@ Each clipwright tool is a standalone MCP server. Register them in your MCP clien
       "env": {
         "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg"
       }
+    },
+    "clipwright-bgm": {
+      "command": "clipwright-bgm"
+    },
+    "clipwright-scene": {
+      "command": "clipwright-scene",
+      "env": {
+        "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg",
+        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
+      }
+    },
+    "clipwright-frames": {
+      "command": "clipwright-frames",
+      "env": {
+        "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg",
+        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
+      }
     }
   }
 }
 ```
 
+> Note: `clipwright-frames` lists both `CLIPWRIGHT_FFMPEG` (frame extraction) and `CLIPWRIGHT_FFPROBE` (video-stream detection and duration probing via `inspect_media`), so both variables must be configured.
+
 Set `CLIPWRIGHT_FFMPEG` and `CLIPWRIGHT_FFPROBE` environment variables if ffmpeg is not in `PATH`.
 
 ---

{clipwright-0.2.0 → clipwright-0.3.0}/README.md

@@ -37,6 +37,38 @@ export CLIPWRIGHT_FFMPEG="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Package
 
 ---
 
+## Prerequisite: clipwright-transcribe (whisper-cli)
+
+`clipwright-transcribe` requires the **whisper.cpp** binary (`whisper-cli`) and a ggml
+model file. They are not installed via pip — obtain them separately.
+
+### whisper-cli Binary
+
+| Platform | How to install |
+|---|---|
+| **Windows** | Download the pre-built binary from [whisper.cpp Releases](https://github.com/ggerganov/whisper.cpp/releases) → `whisper-bin-x64.zip` (CPU) or `whisper-cublas-*-bin-x64.zip` (CUDA). Extract and place `whisper-cli.exe` in a directory on `PATH`, or set `CLIPWRIGHT_WHISPER`. |
+| **macOS** | `brew install whisper-cpp` — installs `whisper-cli` on PATH automatically. |
+| **Linux** | Build from source: `git clone https://github.com/ggerganov/whisper.cpp && cd whisper.cpp && cmake -B build && cmake --build build -j --config Release` — binary is at `build/bin/whisper-cli`. |
+
+```bash
+# If whisper-cli is not on PATH, set the full path:
+export CLIPWRIGHT_WHISPER=/path/to/whisper-cli
+```
+
+### ggml Model File
+
+Download a model (e.g. `ggml-base.bin`) from [Hugging Face](https://huggingface.co/ggerganov/whisper.cpp).
+
+```bash
+export CLIPWRIGHT_WHISPER_MODEL=/path/to/ggml-base.bin
+```
+
+If neither `CLIPWRIGHT_WHISPER` nor a `whisper-cli` binary on PATH is found, the
+`clipwright_transcribe` tool returns `DEPENDENCY_MISSING` and integration tests are
+automatically skipped.
+
+---
+
 ## Development Environment Setup
 
 ```bash
@@ -176,6 +208,26 @@ For details, see [docs/clipwright-spec.md](docs/clipwright-spec.md).
 
 ---
 
+## Available Tools
+
+| Package | MCP Tool | Description |
+|---------|----------|-------------|
+| `clipwright` (core) | `clipwright_inspect_media` | Probe a media file and return codec / duration / stream info |
+| `clipwright` (core) | `clipwright_init_project` | Initialize a project directory with an empty OTIO timeline |
+| `clipwright` (core) | `clipwright_read_timeline` | Read an OTIO timeline file and return its structure |
+| `clipwright` (core) | `clipwright_write_timeline` | Write an OTIO timeline back to disk |
+| `clipwright-silence` | `clipwright_detect_silence` | Detect silent regions in audio via FFmpeg `silencedetect` and annotate OTIO markers |
+| `clipwright-loudness` | `clipwright_measure_loudness` | Measure EBU R128 loudness (integrated LUFS / true-peak) via FFmpeg |
+| `clipwright-noise` | `clipwright_reduce_noise` | Annotate OTIO timeline with FFmpeg `afftdn` noise-reduction settings |
+| `clipwright-transcribe` | `clipwright_transcribe` | Transcribe audio to text via whisper-cli and write word-level OTIO markers |
+| `clipwright-bgm` | `clipwright_place_bgm` | Write BGM placement annotations (volume / fade / ducking) to OTIO timeline |
+| `clipwright-render` | `clipwright_render` | Realize OTIO edit operations (trim / concat / filters) to an output media file via FFmpeg |
+| `clipwright-wrap` | `clipwright_wrap_text` | Wrap long text lines with line-break annotations in OTIO timeline |
+| `clipwright-scene` | `clipwright_detect_scenes` | Detect shot boundaries via FFmpeg `scdet` or PySceneDetect and write OTIO markers |
+| `clipwright-frames` | `clipwright_extract_frames` | Extract still frames from video at specified times, scene boundaries, or fixed intervals; writes images, OTIO markers, and a JSON manifest |
+
+---
+
 ## MCP Client Registration
 
 Each clipwright tool is a standalone MCP server. Register them in your MCP client configuration (`.mcp.json` / `claude_desktop_config.json`):
@@ -195,11 +247,30 @@ Each clipwright tool is a standalone MCP server. Register them in your MCP clien
       "env": {
         "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg"
       }
+    },
+    "clipwright-bgm": {
+      "command": "clipwright-bgm"
+    },
+    "clipwright-scene": {
+      "command": "clipwright-scene",
+      "env": {
+        "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg",
+        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
+      }
+    },
+    "clipwright-frames": {
+      "command": "clipwright-frames",
+      "env": {
+        "CLIPWRIGHT_FFMPEG": "/path/to/ffmpeg",
+        "CLIPWRIGHT_FFPROBE": "/path/to/ffprobe"
+      }
     }
   }
 }
 ```
 
+> Note: `clipwright-frames` lists both `CLIPWRIGHT_FFMPEG` (frame extraction) and `CLIPWRIGHT_FFPROBE` (video-stream detection and duration probing via `inspect_media`), so both variables must be configured.
+
 Set `CLIPWRIGHT_FFMPEG` and `CLIPWRIGHT_FFPROBE` environment variables if ffmpeg is not in `PATH`.
 
 ---

{clipwright-0.2.0 → clipwright-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clipwright"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents."
 readme = "README.md"
 license = { text = "MIT" }
@@ -84,4 +84,4 @@ skip_covered = false
 
 # --- uv workspace ---
 [tool.uv.workspace]
-members = ["clipwright-bgm", "clipwright-loudness", "clipwright-noise", "clipwright-render", "clipwright-silence", "clipwright-transcribe", "clipwright-wrap"]
+members = ["clipwright-bgm", "clipwright-frames", "clipwright-loudness", "clipwright-noise", "clipwright-render", "clipwright-scene", "clipwright-silence", "clipwright-transcribe", "clipwright-wrap"]

{clipwright-0.2.0 → clipwright-0.3.0}/src/clipwright/__init__.py

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

{clipwright-0.2.0 → clipwright-0.3.0}/src/clipwright/otio_utils.py

@@ -6,6 +6,7 @@ Time conversions use to_otio_time / from_otio_time imported from schemas.py.
 
 from __future__ import annotations
 
+import collections.abc
 import contextlib
 import os
 import tempfile
@@ -198,6 +199,61 @@ def get_clipwright_metadata(obj: Any) -> dict[str, Any]:
     return dict(obj.metadata.get("clipwright", {}))
 
 
+# ===========================================================================
+# Marker queries
+# ===========================================================================
+
+
+def get_markers(
+    timeline: otio.schema.Timeline,
+    kind: str | None = None,
+) -> list[otio.schema.Marker]:
+    """Collect Marker objects from all tracks and clips in a Timeline.
+
+    Traversal order: tracks in track order → track markers first, then clip
+    markers in item order → individual markers in marker list order.
+    Time-based sorting is intentionally omitted so that the caller controls
+    ordering and round-trip stability is preserved even when two markers share
+    the same timestamp.
+
+    When *kind* is None all markers are returned.  When *kind* is specified,
+    only markers whose ``metadata["clipwright"]["kind"]`` equals *kind* are
+    returned.  Markers that have no ``metadata["clipwright"]`` dict, or where
+    that value is not a dict, are excluded when *kind* is given (defensive
+    pattern matching ``_marker_to_dict``).
+    """
+    result: list[otio.schema.Marker] = []
+    for track in timeline.tracks:
+        # Track-level markers first
+        for marker in track.markers:
+            if _marker_matches_kind(marker, kind):
+                result.append(marker)
+        # Clip-level markers in item order
+        for item in track:
+            if isinstance(item, otio.schema.Clip):
+                for marker in item.markers:
+                    if _marker_matches_kind(marker, kind):
+                        result.append(marker)
+    return result
+
+
+def _marker_matches_kind(marker: otio.schema.Marker, kind: str | None) -> bool:
+    """Return True when *marker* matches the given kind filter.
+
+    When *kind* is None every marker matches.
+    When *kind* is set, the marker must have metadata["clipwright"]["kind"] == kind.
+    Missing or non-dict clipwright metadata is treated as no-match (exclusive).
+    """
+    if kind is None:
+        return True
+    cw_meta = marker.metadata.get("clipwright", {})
+    # OTIO stores metadata values as AnyDictionary, not a plain dict,
+    # so use Mapping to accept both types.
+    if not isinstance(cw_meta, collections.abc.Mapping):
+        return False
+    return cw_meta.get("kind") == kind
+
+
 # ===========================================================================
 # Timeline summary (§13.5 DC-AM-001 re: return all items, no truncation)
 # ===========================================================================