video2flow 0.1.0__tar.gz

video2flow-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,44 @@
+# 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/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "video2flow"
+version = "0.1.0"
+description = "Extract video frames as descriptive text flows for LLM consumption"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "deepstrain", email = "dev@massiron.com"}]
+keywords = ["video", "frames", "llm", "vision", "description"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "opencv-python>=4.8",
+    "typer>=0.9",
+    "rich>=13.0",
+    "pillow>=10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/massiron/video2flow"
+Repository = "https://github.com/massiron/video2flow"
+Documentation = "https://github.com/massiron/video2flow#readme"
+
+[project.scripts]
+video2flow = "video2flow.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]

video2flow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

video2flow-0.1.0/src/video2flow/__init__.py

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

video2flow-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/video2flow.egg-info/PKG-INFO

@@ -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/src/video2flow.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/video2flow/__init__.py
+src/video2flow/cli.py
+src/video2flow/core.py
+src/video2flow/describe.py
+src/video2flow.egg-info/PKG-INFO
+src/video2flow.egg-info/SOURCES.txt
+src/video2flow.egg-info/dependency_links.txt
+src/video2flow.egg-info/entry_points.txt
+src/video2flow.egg-info/requires.txt
+src/video2flow.egg-info/top_level.txt
+tests/test_video2flow.py

video2flow-0.1.0/src/video2flow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

video2flow-0.1.0/src/video2flow.egg-info/entry_points.txt

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

video2flow-0.1.0/src/video2flow.egg-info/requires.txt

@@ -0,0 +1,4 @@
+opencv-python>=4.8
+typer>=0.9
+rich>=13.0
+pillow>=10.0

video2flow-0.1.0/src/video2flow.egg-info/top_level.txt

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

video2flow-0.1.0/tests/test_video2flow.py

@@ -0,0 +1,38 @@
+"""Tests for video2flow."""
+
+import json
+import tempfile
+from pathlib import Path
+
+from video2flow.describe import describe_frames, _parse_timestamp, _format_time
+
+
+def test_parse_timestamp():
+    assert _parse_timestamp("frame_000000_000.00s") == 0.0
+    assert _parse_timestamp("frame_000005_005.50s") == 5.5
+
+
+def test_format_time():
+    assert _format_time(0) == "00:00:00"
+    assert _format_time(3661) == "01:01:01"
+
+
+def test_describe_frames_empty_dir():
+    with tempfile.TemporaryDirectory() as tmp:
+        import pytest
+        with pytest.raises(FileNotFoundError):
+            describe_frames(Path(tmp) / "nonexistent")
+
+
+def test_describe_frames_with_images():
+    with tempfile.TemporaryDirectory() as tmp:
+        frame_dir = Path(tmp) / "frames"
+        frame_dir.mkdir()
+        (frame_dir / "frame_000000_000.00s.jpg").write_text("fake")
+        (frame_dir / "frame_000001_001.00s.jpg").write_text("fake")
+
+        result = describe_frames(frame_dir)
+        assert result["segment_count"] == 2
+        assert len(result["segments"]) == 2
+        assert result["transcript"] != ""
+        assert "example_prompt" in result["usage"]