agentcut 0.1.0__py3-none-any.whl

agentcut/__init__.py

@@ -0,0 +1,7 @@
+"""AgentCut - Video editing MCP server for AI agents."""
+
+__version__ = "0.1.0"
+
+from .client import Client
+
+__all__ = ["Client"]

agentcut/__main__.py

@@ -0,0 +1,300 @@
+"""AgentCut CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentcut",
+        description="AgentCut — Video editing for AI agents",
+    )
+    parser.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Run as MCP server (default mode)",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="CLI commands")
+
+    # info
+    info_p = subparsers.add_parser("info", help="Get video metadata")
+    info_p.add_argument("input", help="Input video file")
+
+    # trim
+    trim_p = subparsers.add_parser("trim", help="Trim a video")
+    trim_p.add_argument("input", help="Input video file")
+    trim_p.add_argument("-s", "--start", default="0", help="Start time")
+    trim_p.add_argument("-d", "--duration", help="Duration")
+    trim_p.add_argument("-e", "--end", help="End time")
+    trim_p.add_argument("-o", "--output", help="Output file path")
+
+    # merge
+    merge_p = subparsers.add_parser("merge", help="Merge multiple clips")
+    merge_p.add_argument("inputs", nargs="+", help="Input video files")
+    merge_p.add_argument("-t", "--transition", default=None, choices=["fade", "dissolve", "wipe-left", "wipe-right", "wipe-up", "wipe-down"])
+    merge_p.add_argument("--transitions", nargs="+", choices=["fade", "dissolve", "wipe-left", "wipe-right", "wipe-up", "wipe-down"], help="Per-pair transition types (overrides --transition)")
+    merge_p.add_argument("-td", "--transition-duration", type=float, default=1.0, help="Transition duration in seconds")
+    merge_p.add_argument("-o", "--output", help="Output file path")
+
+    # add_text
+    text_p = subparsers.add_parser("add-text", help="Overlay text on a video")
+    text_p.add_argument("input", help="Input video file")
+    text_p.add_argument("text", help="Text to overlay")
+    text_p.add_argument("-p", "--position", default="top-center", choices=["top-left", "top-center", "top-right", "center-left", "center", "center-right", "bottom-left", "bottom-center", "bottom-right"])
+    text_p.add_argument("--font", help="Path to font file")
+    text_p.add_argument("--size", type=int, default=48, help="Font size in pixels")
+    text_p.add_argument("--color", default="white", help="Text color")
+    text_p.add_argument("--no-shadow", action="store_true", help="Disable text shadow")
+    text_p.add_argument("--start-time", type=float, help="When text appears (seconds)")
+    text_p.add_argument("--duration", type=float, help="How long text is visible (seconds)")
+    text_p.add_argument("-o", "--output", help="Output file path")
+
+    # add_audio
+    audio_p = subparsers.add_parser("add-audio", help="Add or replace audio track")
+    audio_p.add_argument("video", help="Input video file")
+    audio_p.add_argument("audio", help="Audio file (MP3, WAV, etc.)")
+    audio_p.add_argument("-v", "--volume", type=float, default=1.0, help="Audio volume (0.0-2.0)")
+    audio_p.add_argument("--fade-in", type=float, default=0.0, help="Fade in duration")
+    audio_p.add_argument("--fade-out", type=float, default=0.0, help="Fade out duration")
+    audio_p.add_argument("--mix", action="store_true", help="Mix with existing audio instead of replacing")
+    audio_p.add_argument("--start-time", type=float, help="When audio starts (seconds)")
+    audio_p.add_argument("-o", "--output", help="Output file path")
+
+    # resize
+    resize_p = subparsers.add_parser("resize", help="Resize a video")
+    resize_p.add_argument("input", help="Input video file")
+    resize_p.add_argument("-w", "--width", type=int, help="Target width")
+    resize_p.add_argument("--height", type=int, help="Target height")
+    resize_p.add_argument("-a", "--aspect-ratio", choices=["16:9", "9:16", "1:1", "4:3", "4:5", "21:9"], help="Preset aspect ratio")
+    resize_p.add_argument("-q", "--quality", default="high", choices=["low", "medium", "high", "ultra"])
+    resize_p.add_argument("-o", "--output", help="Output file path")
+
+    # speed
+    speed_p = subparsers.add_parser("speed", help="Change playback speed")
+    speed_p.add_argument("input", help="Input video file")
+    speed_p.add_argument("-f", "--factor", type=float, default=1.0, help="Speed multiplier (0.5=slow, 2.0=fast)")
+    speed_p.add_argument("-o", "--output", help="Output file path")
+
+    # convert
+    convert_p = subparsers.add_parser("convert", help="Convert video format")
+    convert_p.add_argument("input", help="Input video file")
+    convert_p.add_argument("-f", "--format", default="mp4", choices=["mp4", "webm", "gif", "mov"])
+    convert_p.add_argument("-q", "--quality", default="high", choices=["low", "medium", "high", "ultra"])
+    convert_p.add_argument("-o", "--output", help="Output file path")
+
+    # thumbnail
+    thumb_p = subparsers.add_parser("thumbnail", help="Extract a single frame")
+    thumb_p.add_argument("input", help="Input video file")
+    thumb_p.add_argument("-t", "--timestamp", type=float, help="Time in seconds (default: 10%% of duration)")
+    thumb_p.add_argument("-o", "--output", help="Output image path")
+
+    # preview
+    preview_p = subparsers.add_parser("preview", help="Generate a fast low-res preview")
+    preview_p.add_argument("input", help="Input video file")
+    preview_p.add_argument("-o", "--output", help="Output file path")
+    preview_p.add_argument("-s", "--scale", type=int, default=4, help="Downscale factor (default: 4)")
+
+    # storyboard
+    storyboard_p = subparsers.add_parser("storyboard", help="Extract key frames as storyboard")
+    storyboard_p.add_argument("input", help="Input video file")
+    storyboard_p.add_argument("-o", "--output-dir", help="Output directory")
+    storyboard_p.add_argument("-n", "--frames", type=int, default=8, help="Number of frames (default: 8)")
+
+    # subtitles
+    subs_p = subparsers.add_parser("subtitles", help="Burn subtitles into video")
+    subs_p.add_argument("input", help="Input video file")
+    subs_p.add_argument("subtitle", help="Subtitle file (.srt or .vtt)")
+    subs_p.add_argument("-o", "--output", help="Output file path")
+
+    # watermark
+    wm_p = subparsers.add_parser("watermark", help="Add image watermark")
+    wm_p.add_argument("input", help="Input video file")
+    wm_p.add_argument("image", help="Watermark image (PNG recommended)")
+    wm_p.add_argument("-p", "--position", default="bottom-right", choices=["top-left", "top-center", "top-right", "center-left", "center", "bottom-left", "bottom-center", "bottom-right"])
+    wm_p.add_argument("--opacity", type=float, default=0.7, help="Watermark opacity (0.0-1.0)")
+    wm_p.add_argument("--margin", type=int, default=20, help="Margin from edge in pixels")
+    wm_p.add_argument("-o", "--output", help="Output file path")
+
+    # crop
+    crop_p = subparsers.add_parser("crop", help="Crop a video to a region")
+    crop_p.add_argument("input", help="Input video file")
+    crop_p.add_argument("-w", "--width", type=int, required=True, help="Crop width in pixels")
+    crop_p.add_argument("--height", type=int, required=True, help="Crop height in pixels")
+    crop_p.add_argument("-x", type=int, default=None, help="X offset (default: center)")
+    crop_p.add_argument("-y", type=int, default=None, help="Y offset (default: center)")
+    crop_p.add_argument("-o", "--output", help="Output file path")
+
+    # rotate
+    rotate_p = subparsers.add_parser("rotate", help="Rotate and/or flip a video")
+    rotate_p.add_argument("input", help="Input video file")
+    rotate_p.add_argument("-a", "--angle", type=int, default=0, choices=[0, 90, 180, 270], help="Rotation angle in degrees")
+    rotate_p.add_argument("--flip-h", action="store_true", help="Flip horizontally")
+    rotate_p.add_argument("--flip-v", action="store_true", help="Flip vertically")
+    rotate_p.add_argument("-o", "--output", help="Output file path")
+
+    # fade
+    fade_p = subparsers.add_parser("fade", help="Add fade in/out to video")
+    fade_p.add_argument("input", help="Input video file")
+    fade_p.add_argument("--fade-in", type=float, default=0.0, help="Fade in duration (seconds)")
+    fade_p.add_argument("--fade-out", type=float, default=0.0, help="Fade out duration (seconds)")
+    fade_p.add_argument("-o", "--output", help="Output file path")
+
+    # export
+    export_p = subparsers.add_parser("export", help="Export video with quality settings")
+    export_p.add_argument("input", help="Input video file")
+    export_p.add_argument("-q", "--quality", default="high", choices=["low", "medium", "high", "ultra"])
+    export_p.add_argument("-f", "--format", default="mp4", choices=["mp4", "webm", "gif", "mov"])
+    export_p.add_argument("-o", "--output", help="Output file path")
+
+    # extract_audio
+    extract_p = subparsers.add_parser("extract-audio", help="Extract audio from video")
+    extract_p.add_argument("input", help="Input video file")
+    extract_p.add_argument("-f", "--format", default="mp3", choices=["mp3", "aac", "wav", "ogg", "flac"])
+    extract_p.add_argument("-o", "--output", help="Output audio file path")
+
+    # edit (timeline)
+    edit_p = subparsers.add_parser("edit", help="Execute timeline-based edit from JSON")
+    edit_p.add_argument("timeline", help="Path to timeline JSON file")
+    edit_p.add_argument("-o", "--output", help="Output file path")
+
+    args = parser.parse_args()
+
+    # Default mode: run MCP server
+    if args.mcp or args.command is None:
+        from .server import mcp
+        mcp.run()
+        return
+
+    # CLI commands
+    try:
+        if args.command == "info":
+            from .engine import probe
+            info = probe(args.input)
+            print(json.dumps(info.model_dump(), indent=2))
+
+        elif args.command == "trim":
+            from .engine import trim
+            result = trim(args.input, start=args.start, duration=args.duration, end=args.end, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "merge":
+            from .engine import merge
+            result = merge(args.inputs, output_path=args.output, transition=args.transition, transitions=args.transitions, transition_duration=args.transition_duration)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "add-text":
+            from .engine import add_text
+            result = add_text(
+                args.input, text=args.text, position=args.position,
+                font=args.font, size=args.size, color=args.color,
+                shadow=not args.no_shadow,
+                start_time=args.start_time, duration=args.duration,
+                output_path=args.output,
+            )
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "add-audio":
+            from .engine import add_audio
+            result = add_audio(
+                args.video, args.audio, volume=args.volume,
+                fade_in=args.fade_in, fade_out=args.fade_out,
+                mix=args.mix, start_time=args.start_time,
+                output_path=args.output,
+            )
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "resize":
+            from .engine import resize
+            result = resize(
+                args.input, width=args.width, height=args.height,
+                aspect_ratio=args.aspect_ratio, quality=args.quality,
+                output_path=args.output,
+            )
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "speed":
+            from .engine import speed
+            result = speed(args.input, factor=args.factor, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "convert":
+            from .engine import convert
+            result = convert(args.input, format=args.format, quality=args.quality, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "thumbnail":
+            from .engine import thumbnail
+            result = thumbnail(args.input, timestamp=args.timestamp, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "preview":
+            from .engine import preview
+            result = preview(args.input, output_path=args.output, scale_factor=args.scale)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "storyboard":
+            from .engine import storyboard
+            result = storyboard(args.input, output_dir=args.output_dir, frame_count=args.frames)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "subtitles":
+            from .engine import subtitles
+            result = subtitles(args.input, subtitle_path=args.subtitle, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "watermark":
+            from .engine import watermark
+            result = watermark(
+                args.input, image_path=args.image, position=args.position,
+                opacity=args.opacity, margin=args.margin,
+                output_path=args.output,
+            )
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "crop":
+            from .engine import crop
+            result = crop(args.input, width=args.width, height=args.height, x=args.x, y=args.y, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "rotate":
+            from .engine import rotate
+            result = rotate(args.input, angle=args.angle, flip_horizontal=args.flip_h, flip_vertical=args.flip_v, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "fade":
+            from .engine import fade
+            result = fade(args.input, fade_in=args.fade_in, fade_out=args.fade_out, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "export":
+            from .engine import export_video
+            result = export_video(args.input, quality=args.quality, format=args.format, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+        elif args.command == "extract-audio":
+            from .engine import extract_audio
+            result = extract_audio(args.input, output_path=args.output, format=args.format)
+            print(result)
+
+        elif args.command == "edit":
+            from .models import Timeline
+            with open(args.timeline) as f:
+                tl = Timeline.model_validate(json.load(f))
+            from .engine import edit_timeline
+            result = edit_timeline(tl, output_path=args.output)
+            print(json.dumps(result.model_dump(), indent=2))
+
+    except Exception as e:
+        from .errors import AgentCutError
+        if isinstance(e, AgentCutError):
+            print(json.dumps({"success": False, "error": e.to_dict()}, indent=2), file=sys.stderr)
+        else:
+            print(json.dumps({"success": False, "error": {"type": "unknown", "message": str(e)}}, indent=2), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

agentcut/client.py

@@ -0,0 +1,272 @@
+"""AgentCut Python client — clean API for programmatic video editing."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .engine import (
+    add_audio as _add_audio,
+    add_text as _add_text,
+    convert as _convert,
+    crop as _crop,
+    edit_timeline as _edit_timeline,
+    export_video as _export_video,
+    extract_audio as _extract_audio,
+    fade as _fade,
+    merge as _merge,
+    preview as _preview,
+    probe as _probe,
+    resize as _resize,
+    rotate as _rotate,
+    storyboard as _storyboard,
+    subtitles as _subtitles,
+    speed as _speed,
+    thumbnail as _thumbnail,
+    trim as _trim,
+    watermark as _watermark,
+)
+from .models import (
+    EditResult,
+    ExportFormat,
+    Position,
+    QualityLevel,
+    StoryboardResult,
+    ThumbnailResult,
+    VideoInfo,
+)
+
+
+class Client:
+    """AgentCut client for programmatic video editing.
+
+    Usage:
+        from agentcut import Client
+        editor = Client()
+
+        result = editor.trim("input.mp4", start="00:00:30", duration="00:00:15")
+        print(result.output_path)
+    """
+
+    def info(self, input_path: str) -> VideoInfo:
+        """Get metadata about a video file."""
+        return _probe(input_path)
+
+    def trim(
+        self,
+        input: str,
+        start: str | float = 0,
+        duration: str | float | None = None,
+        end: str | float | None = None,
+        output: str | None = None,
+    ) -> EditResult:
+        """Trim a clip by start time and duration."""
+        return _trim(input, start=start, duration=duration, end=end, output_path=output)
+
+    def merge(
+        self,
+        clips: list[str],
+        output: str | None = None,
+        transitions: list[str] | None = None,
+        transition_duration: float = 1.0,
+    ) -> EditResult:
+        """Merge multiple clips into one video.
+
+        Args:
+            clips: List of video file paths.
+            output: Output file path.
+            transitions: Transition types applied between each clip pair.
+                One per boundary (len = len(clips)-1). If fewer provided,
+                the last type is repeated. Example: ["fade", "dissolve", "fade"].
+            transition_duration: Duration of each transition in seconds.
+        """
+        return _merge(clips, output_path=output, transitions=transitions, transition_duration=transition_duration)
+
+    def add_text(
+        self,
+        video: str,
+        text: str,
+        position: str = "top-center",
+        font: str | None = None,
+        size: int = 48,
+        color: str = "white",
+        shadow: bool = True,
+        start_time: float | None = None,
+        duration: float | None = None,
+        output: str | None = None,
+    ) -> EditResult:
+        """Overlay text on a video."""
+        return _add_text(
+            video, text=text, position=position, font=font,
+            size=size, color=color, shadow=shadow,
+            start_time=start_time, duration=duration,
+            output_path=output,
+        )
+
+    def add_audio(
+        self,
+        video: str,
+        audio: str,
+        volume: float = 1.0,
+        fade_in: float = 0.0,
+        fade_out: float = 0.0,
+        mix: bool = False,
+        start_time: float | None = None,
+        output: str | None = None,
+    ) -> EditResult:
+        """Add or replace audio track."""
+        return _add_audio(
+            video, audio_path=audio, volume=volume,
+            fade_in=fade_in, fade_out=fade_out, mix=mix,
+            start_time=start_time, output_path=output,
+        )
+
+    def resize(
+        self,
+        video: str,
+        width: int | None = None,
+        height: int | None = None,
+        aspect_ratio: str | None = None,
+        quality: str = "high",
+        output: str | None = None,
+    ) -> EditResult:
+        """Resize a video or change aspect ratio."""
+        return _resize(
+            video, width=width, height=height,
+            aspect_ratio=aspect_ratio, quality=quality,
+            output_path=output,
+        )
+
+    def convert(
+        self,
+        video: str,
+        format: str = "mp4",
+        quality: str = "high",
+        output: str | None = None,
+    ) -> EditResult:
+        """Convert video to a different format."""
+        return _convert(video, format=format, quality=quality, output_path=output)
+
+    def speed(
+        self,
+        video: str,
+        factor: float = 1.0,
+        output: str | None = None,
+    ) -> EditResult:
+        """Change playback speed."""
+        return _speed(video, factor=factor, output_path=output)
+
+    def thumbnail(
+        self,
+        video: str,
+        timestamp: float | None = None,
+        output: str | None = None,
+    ) -> ThumbnailResult:
+        """Extract a frame from a video."""
+        return _thumbnail(video, timestamp=timestamp, output_path=output)
+
+    def preview(
+        self,
+        video: str,
+        output: str | None = None,
+        scale_factor: int = 4,
+    ) -> EditResult:
+        """Generate a fast low-res preview."""
+        return _preview(video, output_path=output, scale_factor=scale_factor)
+
+    def storyboard(
+        self,
+        video: str,
+        output_dir: str | None = None,
+        frame_count: int = 8,
+    ) -> StoryboardResult:
+        """Extract key frames as storyboard for human review."""
+        return _storyboard(video, output_dir=output_dir, frame_count=frame_count)
+
+    def subtitles(
+        self,
+        video: str,
+        subtitle_file: str,
+        output: str | None = None,
+    ) -> EditResult:
+        """Burn subtitles into a video."""
+        return _subtitles(video, subtitle_path=subtitle_file, output_path=output)
+
+    def watermark(
+        self,
+        video: str,
+        image: str,
+        position: str = "bottom-right",
+        opacity: float = 0.7,
+        margin: int = 20,
+        output: str | None = None,
+    ) -> EditResult:
+        """Add image watermark."""
+        return _watermark(
+            video, image_path=image, position=position,
+            opacity=opacity, margin=margin, output_path=output,
+        )
+
+    def crop(
+        self,
+        video: str,
+        width: int,
+        height: int,
+        x: int | None = None,
+        y: int | None = None,
+        output: str | None = None,
+    ) -> EditResult:
+        """Crop a video to a rectangular region."""
+        return _crop(video, width=width, height=height, x=x, y=y, output_path=output)
+
+    def rotate(
+        self,
+        video: str,
+        angle: int = 0,
+        flip_horizontal: bool = False,
+        flip_vertical: bool = False,
+        output: str | None = None,
+    ) -> EditResult:
+        """Rotate and/or flip a video."""
+        return _rotate(video, angle=angle, flip_horizontal=flip_horizontal, flip_vertical=flip_vertical, output_path=output)
+
+    def fade(
+        self,
+        video: str,
+        fade_in: float = 0.0,
+        fade_out: float = 0.0,
+        output: str | None = None,
+    ) -> EditResult:
+        """Add fade in/out effect to a video."""
+        return _fade(video, fade_in=fade_in, fade_out=fade_out, output_path=output)
+
+    def export(
+        self,
+        video: str,
+        output: str | None = None,
+        quality: str = "high",
+        format: str = "mp4",
+    ) -> EditResult:
+        """Render final video with quality settings."""
+        return _export_video(video, output_path=output, quality=quality, format=format)
+
+    def edit(self, timeline: dict[str, Any], output: str | None = None) -> EditResult:
+        """Execute a full timeline-based edit from JSON."""
+        return _edit_timeline(timeline, output_path=output)
+
+    def extract_audio(
+        self,
+        video: str,
+        output: str | None = None,
+        format: str = "mp3",
+    ) -> EditResult:
+        """Extract audio track from video."""
+        result_path = _extract_audio(video, output_path=output, format=format)
+        return EditResult(
+            output_path=result_path,
+            operation="extract_audio",
+            format=format,
+        )
+
+
+# Fix the circular import for resize
+from .engine import resize as _resize