vidclaude 0.2.0

package/vidclaude/util.py

@@ -0,0 +1,163 @@
+"""Shared utilities: ffmpeg wrappers, image encoding, caching, logging."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import subprocess
+import sys
+from io import BytesIO
+from pathlib import Path
+
+from PIL import Image
+
+logger = logging.getLogger("vidclaude")
+
+
+def setup_logging(verbose: bool) -> None:
+    """Configure logging level and format."""
+    level = logging.DEBUG if verbose else logging.INFO
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+    root = logging.getLogger("vidclaude")
+    root.setLevel(level)
+    root.addHandler(handler)
+
+
+# --- ffmpeg / ffprobe ---
+
+def check_ffmpeg() -> bool:
+    """Check if ffmpeg is available on PATH."""
+    try:
+        subprocess.run(
+            ["ffmpeg", "-version"],
+            capture_output=True, check=True, timeout=10,
+        )
+        return True
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        return False
+
+
+def run_ffmpeg(args: list[str], timeout: int = 300) -> subprocess.CompletedProcess:
+    """Run an ffmpeg command and return the result."""
+    cmd = ["ffmpeg"] + args
+    logger.debug("Running: %s", " ".join(cmd))
+    result = subprocess.run(
+        cmd, capture_output=True, text=True, timeout=timeout,
+    )
+    if result.returncode != 0:
+        logger.debug("ffmpeg stderr: %s", result.stderr[:500])
+    return result
+
+
+def run_ffprobe(video_path: str) -> dict:
+    """Run ffprobe and return parsed JSON output."""
+    cmd = [
+        "ffprobe", "-v", "quiet",
+        "-print_format", "json",
+        "-show_format", "-show_streams",
+        str(video_path),
+    ]
+    logger.debug("Running: %s", " ".join(cmd))
+    result = subprocess.run(
+        cmd, capture_output=True, text=True, timeout=30,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"ffprobe failed: {result.stderr[:300]}")
+    return json.loads(result.stdout)
+
+
+# --- Image utilities ---
+
+def resize_image(img: Image.Image, max_size: int = 1024) -> Image.Image:
+    """Resize image so the longest side is at most max_size pixels."""
+    w, h = img.size
+    if max(w, h) <= max_size:
+        return img
+    scale = max_size / max(w, h)
+    new_w, new_h = int(w * scale), int(h * scale)
+    return img.resize((new_w, new_h), Image.LANCZOS)
+
+
+def image_to_base64(path: str, max_size: int = 1024) -> str:
+    """Load image, resize, encode as JPEG base64."""
+    img = Image.open(path).convert("RGB")
+    img = resize_image(img, max_size)
+    buf = BytesIO()
+    img.save(buf, format="JPEG", quality=85)
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+# --- Timestamp formatting ---
+
+def format_timestamp(ms: int) -> str:
+    """Format milliseconds as MM:SS.mmm."""
+    total_sec = ms / 1000.0
+    minutes = int(total_sec // 60)
+    seconds = total_sec % 60
+    return f"{minutes:02d}:{seconds:06.3f}"
+
+
+def ms_to_hhmmss(ms: int) -> str:
+    """Format milliseconds as HH:MM:SS.mmm for longer videos."""
+    total_sec = ms / 1000.0
+    hours = int(total_sec // 3600)
+    minutes = int((total_sec % 3600) // 60)
+    seconds = total_sec % 60
+    if hours > 0:
+        return f"{hours:02d}:{minutes:02d}:{seconds:06.3f}"
+    return f"{minutes:02d}:{seconds:06.3f}"
+
+
+# --- Caching ---
+
+def get_cache_key(video_path: str) -> str:
+    """Generate a cache key from video path + size + mtime."""
+    p = Path(video_path).resolve()
+    stat = p.stat()
+    identity = f"{p}|{stat.st_size}|{stat.st_mtime}"
+    return hashlib.sha256(identity.encode()).hexdigest()[:12]
+
+
+def get_cache_dir(video_path: str, base_cache: str | None = None) -> Path:
+    """Get the cache directory for a video, creating it if needed."""
+    key = get_cache_key(video_path)
+    if base_cache:
+        cache_root = Path(base_cache)
+    else:
+        cache_root = Path(video_path).parent / ".vidcache"
+    cache_dir = cache_root / key
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    (cache_dir / "frames").mkdir(exist_ok=True)
+    return cache_dir
+
+
+def is_cached(cache_dir: Path) -> bool:
+    """Check if a cache directory has completed extraction."""
+    return (cache_dir / "meta.json").exists() and (cache_dir / "timeline.json").exists()
+
+
+# --- File discovery ---
+
+VIDEO_EXTENSIONS = {".mp4", ".mov", ".mkv", ".webm", ".avi", ".m4v"}
+
+
+def find_videos(path: str) -> list[str]:
+    """Find video files in a path. If path is a file, return it. If directory, find all videos."""
+    p = Path(path)
+    if p.is_file():
+        if p.suffix.lower() in VIDEO_EXTENSIONS:
+            return [str(p)]
+        raise ValueError(f"Not a recognized video file: {p.suffix}")
+    if p.is_dir():
+        videos = []
+        for f in sorted(p.iterdir()):
+            if f.is_file() and f.suffix.lower() in VIDEO_EXTENSIONS:
+                videos.append(str(f))
+        if not videos:
+            raise ValueError(f"No video files found in {p}")
+        return videos
+    raise FileNotFoundError(f"Path not found: {path}")

package/video_understand.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Multimodal video understanding powered by Claude.
+
+Entry point for the vidclaude CLI tool.
+Usage: python video_understand.py <video_or_folder> [options]
+Run with --help for full usage information.
+"""
+
+from vidclaude.cli import main
+
+if __name__ == "__main__":
+    main()