video2flow 0.1.0__py3-none-any.whl

video2flow/__init__.py

@@ -0,0 +1,3 @@
+"""video2flow — Extract video frames as descriptive text flows for LLM consumption."""
+
+__version__ = "0.1.0"

video2flow/cli.py

@@ -0,0 +1,52 @@
+"""video2flow CLI — Typer-based command line interface."""
+
+import typer
+from pathlib import Path
+from typing import Optional
+from rich.console import Console
+from video2flow.core import extract_frames
+from video2flow.describe import describe_frames, describe_video
+
+app = typer.Typer(help="video2flow — Video frame description for LLMs")
+console = Console()
+
+@app.command()
+def extract(
+    video: Path = typer.Argument(..., help="Input video file"),
+    output: Path = typer.Option(Path("frames"), "--output", "-o", help="Output directory"),
+    fps: float = typer.Option(1.0, "--fps", help="Frames per second to extract"),
+    max_frames: int = typer.Option(0, "--max-frames", "-n", help="Maximum frames (0 = unlimited)"),
+):
+    """Extract frames from a video file."""
+    result = extract_frames(video, output, fps=fps, max_frames=max_frames)
+    console.print(f"[green]OK[/green] Extracted {result['frame_count']} frames -> [bold]{output.resolve()}[/bold]")
+
+@app.command()
+def describe(
+    video: Path = typer.Argument(..., help="Input video file"),
+    fps: float = typer.Option(1.0, "--fps", help="Frames per second to sample"),
+    max_frames: int = typer.Option(10, "--max-frames", "-n", help="Maximum frames to describe"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output JSON file"),
+    provider: str = typer.Option("none", "--provider", "-p", help="Vision provider (none = filename-only descriptions)"),
+):
+    """Extract frames and generate textual descriptions for LLM consumption."""
+    result = describe_video(video, fps=fps, max_frames=max_frames, provider=provider)
+    if output:
+        import json
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False))
+        console.print(f"[green]OK[/green] Descriptions saved -> [bold]{output.resolve()}[/bold]")
+    else:
+        console.print(result["transcript"])
+
+@app.command()
+def pipeline(
+    video: Path = typer.Argument(..., help="Input video file"),
+    output: Path = typer.Option(Path("video_flow"), "--output", "-o", help="Output directory"),
+    fps: float = typer.Option(1.0, "--fps", help="Frames per second"),
+    max_frames: int = typer.Option(0, "--max-frames", "-n", help="Maximum frames"),
+):
+    """Full pipeline: extract frames + generate description flow."""
+    frames = extract_frames(video, output / "frames", fps=fps, max_frames=max_frames)
+    result = describe_frames(output / "frames", output / "flow.json")
+    console.print(f"[green]OK[/green] Pipeline complete -> [bold]{output.resolve()}[/bold]")
+    console.print(f"  Frames: {frames['frame_count']}, Segments: {result['segment_count']}")

video2flow/core.py

@@ -0,0 +1,56 @@
+"""video2flow core — Extract frames from video files."""
+
+import os
+from pathlib import Path
+
+
+def extract_frames(
+    video: Path,
+    output: Path,
+    fps: float = 1.0,
+    max_frames: int = 0,
+) -> dict:
+    video = Path(video).resolve()
+    output = Path(output).resolve()
+    output.mkdir(parents=True, exist_ok=True)
+
+    if not video.exists():
+        raise FileNotFoundError(f"Video not found: {video}")
+
+    import cv2
+    cap = cv2.VideoCapture(str(video))
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open video: {video}")
+
+    video_fps = cap.get(cv2.CAP_PROP_FPS)
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    duration = total_frames / video_fps if video_fps > 0 else 0
+    interval = max(1, int(video_fps / fps))
+
+    frame_count = 0
+    saved = 0
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        if frame_count % interval == 0:
+            if max_frames > 0 and saved >= max_frames:
+                break
+            ts = frame_count / video_fps
+            name = f"frame_{saved:06d}_{ts:06.2f}s.jpg"
+            path = output / name
+            cv2.imwrite(str(path), frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
+            saved += 1
+        frame_count += 1
+
+    cap.release()
+
+    return {
+        "video": str(video),
+        "total_frames": total_frames,
+        "video_fps": round(video_fps, 2),
+        "duration_s": round(duration, 2),
+        "extracted_fps": fps,
+        "frame_count": saved,
+        "output_dir": str(output),
+    }

video2flow/describe.py

@@ -0,0 +1,120 @@
+"""video2flow describe — Generate text descriptions of video frames for LLMs."""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def describe_frames(frame_dir: Path, output: Optional[Path] = None) -> dict:
+    frame_dir = Path(frame_dir)
+    if not frame_dir.exists():
+        raise FileNotFoundError(f"Frame directory not found: {frame_dir}")
+
+    frames = sorted(frame_dir.glob("*.jpg")) + sorted(frame_dir.glob("*.png"))
+    segments = []
+
+    for i, fp in enumerate(frames):
+        ts = _parse_timestamp(fp.stem)
+        size = fp.stat().st_size
+        dimension = _get_image_dimension(fp)
+
+        segments.append({
+            "segment": i,
+            "file": fp.name,
+            "timestamp_s": ts,
+            "timestamp_str": _format_time(ts),
+            "size_bytes": size,
+            "description": f"[Frame {i}] at {_format_time(ts)} — {dimension}",
+
+            "hint": (
+                "Pass this image to a vision-capable LLM (Claude 3.5+, GPT-4o, "
+                "Gemini 2.0) for detailed scene description."
+            ),
+        })
+
+    transcript_lines = [
+        f"[{s['timestamp_str']}] {s['description']}" for s in segments
+    ]
+    transcript = "\n".join(transcript_lines)
+
+    result = {
+        "video_source": str(frame_dir.parent),
+        "total_segments": len(segments),
+        "segment_count": len(segments),
+        "duration_s": segments[-1]["timestamp_s"] if segments else 0,
+        "segments": segments,
+        "transcript": transcript,
+        "usage": {
+            "description": (
+                "Pass the 'segments' array to any LLM. Each segment contains "
+                "a timestamp and filename. For detailed vision understanding, "
+                "send the image files directly to a multimodal model."
+            ),
+            "example_prompt": (
+                "You are analyzing a video. Below is the frame sequence:\n"
+                + transcript
+            ),
+        },
+    }
+
+    if output:
+        output = Path(output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False))
+
+    return result
+
+
+def describe_video(
+    video: Path,
+    fps: float = 1.0,
+    max_frames: int = 10,
+    provider: str = "none",
+) -> dict:
+    from video2flow.core import extract_frames
+
+    import tempfile
+    tmpdir = Path(tempfile.mkdtemp(prefix="v2f_"))
+
+    try:
+        frames = extract_frames(
+            video=video,
+            output=tmpdir / "frames",
+            fps=fps,
+            max_frames=max_frames,
+        )
+        frame_dir = Path(frames["output_dir"])
+        result = describe_frames(frame_dir)
+        result["extraction"] = frames
+        return result
+    finally:
+        import shutil
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def _parse_timestamp(stem: str) -> float:
+    parts = stem.split("_")
+    for p in parts:
+        if "s" in p:
+            try:
+                return float(p.replace("s", ""))
+            except ValueError:
+                pass
+    return 0.0
+
+
+def _format_time(seconds: float) -> str:
+    h, r = divmod(int(seconds), 3600)
+    m, s = divmod(r, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"
+
+
+def _get_image_dimension(path: Path) -> str:
+    try:
+        from PIL import Image
+        with Image.open(path) as img:
+            w, h = img.size
+            return f"{w}x{h}"
+    except Exception:
+        return "unknown"

video2flow-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: video2flow
+Version: 0.1.0
+Summary: Extract video frames as descriptive text flows for LLM consumption
+Author-email: deepstrain <dev@massiron.com>
+License: MIT
+Project-URL: Homepage, https://github.com/massiron/video2flow
+Project-URL: Repository, https://github.com/massiron/video2flow
+Project-URL: Documentation, https://github.com/massiron/video2flow#readme
+Keywords: video,frames,llm,vision,description
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Requires-Dist: pillow>=10.0
+
+# video2flow
+
+**Extract video frames as descriptive text flows for LLM consumption.**
+
+Claude, GPT-4o, Gemini and other multimodal models can see images but not
+video. `video2flow` bridges the gap: extract frames → generate timestamped
+descriptions → feed the text flow to any LLM.
+
+## Installation
+
+```bash
+pip install video2flow
+```
+
+## Usage
+
+```bash
+# Extract frames from a video
+video2flow extract video.mp4 -o frames/ --fps 1
+
+# Quick description (without vision API)
+video2flow describe video.mp4 --max-frames 10
+
+# Full pipeline
+video2flow pipeline video.mp4 -o video_flow/
+```
+
+## LLM Integration
+
+Pass the output JSON to any LLM:
+
+```python
+import json
+flow = json.loads(open("video_flow/flow.json").read())
+prompt = flow["usage"]["example_prompt"]
+# Then: response = llm.invoke(prompt)
+```
+
+For detailed vision understanding, send image files directly to a
+multimodal model alongside the flow transcript.
+
+## License
+
+MIT

video2flow-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+video2flow/__init__.py,sha256=LYpwThh9fFSzb0oY-jPXSz2AgNp5xi9MPcepkpMObUY,112
+video2flow/cli.py,sha256=QtZ7zHJWPBMymsDhI1qGJ7hgkG-179LlejojWvALJEU,2645
+video2flow/core.py,sha256=2K7_XHpw3Vf6aQAM8YMcKfgZPjLD46wzKLKSCXySbWM,1539
+video2flow/describe.py,sha256=rf9GLdgjGukKZ3QQUd3CrbYYrw4TKqcLtAvTwmu3xbI,3451
+video2flow-0.1.0.dist-info/METADATA,sha256=UNLU2Xcgwo1qi9GgnUVY2XR6BCp0ItdkOqnaroS3LrE,2009
+video2flow-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+video2flow-0.1.0.dist-info/entry_points.txt,sha256=B_QVW8KWUlmi6Oa7rCEGkT9y_YqQzt5Rwru4jxClFLs,50
+video2flow-0.1.0.dist-info/top_level.txt,sha256=3NdZV1zggioOwjiMf9dj1328hO0yzklj7HHKCX8l8a8,11
+video2flow-0.1.0.dist-info/RECORD,,

video2flow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

video2flow-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+video2flow = video2flow.cli:app

video2flow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+video2flow